Tracking Service

The Tracking service lets you capture shopper interactions across your site, including page views, product views, category visits, add-to-cart actions, purchases, element impressions, clicks, and search activity, as well as custom events, so you can measure engagement, optimize experiences, and feed behavioral data back into XGEN’s AI models.

There are 3 ways to pass the locale to the track service events:

Note: The locale is a required field for all track events, but it is optional to pass directly in each event because there are 3 way to set the locale:

1. Pass the locale directly as a parameter. Example: xg.track.pageView({ locale: '<locale>' })

2. Use the xg.track.setLocale(<locale>: string) method to set the locale for any subsequent track events

3. Set the locale when creating the XGenClient instance

    cons xg = new XGenClient({
    	// ...other params,
    	locale: () => '<locale>',

    	// or

    	locale: '<locale>',
    })

There are also 3 ways to pass the group that a user belongs to:

Note: The group is not required, but is useful for segmenting users during A/B testing.

1. Pass the group directly as a parameter. Example: xg.track.pageView({ group: '<group>' })

2. Use the xg.track.setGroup(<group>: string) method to set the group for any subsequent track events

3. Set the group when creating the XGenClient instance

    cons xg = new XGenClient({
    	// ...other params,
    	group: () => '<group>',

    	// or

    	group: '<group>',
    })

Methods

// tracks a page view event.
xg.track.pageView({ locale });

// tracks the view of a item/product
xg.track.itemView({ item, context, locale });

// tracks the view of a category
xg.track.categoryView({ category, items, context, locale });

// tracks an add to cart event for an item/product
xg.track.addToCart({ item, context, locale });

// tracks a purchase order event for item(s)/product(s)
xg.track.purchaseOrder({ items, orderId, tax, discount, context, locale });

// tracks the view of a specific dom element
xg.track.elementView({ element, context, locale });

// tracks the render of a specific dom element
xg.track.elementRender({ element, context, locale });

// tracks the click of a specific dom element
xg.track.elementClick({ element, item, context, locale });

// tracks a search query event (tracked by default when calling xg.search.getResults())
xg.track.searchQuery({ query, queryId, deploymentId, page, context, locale });

// tracks the results of a search query (tracked by default when calling xg.search.getResults())
xg.track.searchResult({ query, queryId, deploymentId, page, context, locale });

// tracks a click of a search item/product
xg.track.searchClick({ query, queryId, deploymentId, page, item, items, context, locale });

// tracks a group assignment event
xg.track.groupAssignment({ group, previousGroup, context, locale });

// tracks a custom event
xg.track.customEvent({ category, action, name, value, locale });

// batch tracking - this will batch tracking events until send() is called
const batch = xg.track.createBatch();

batch.pageView();
batch.itemView({ item, context });

// optionally takes in a locale, group, url, and referrer to send the tracking events for
//ex. batch.send({locale: 'en', url: 'https://example.com/pdp', referrer: 'https://example.com/, group: 'group'})
batch.send();

All Tracking Events Return

{
  message: string;
  success: boolean;
}

pageView

pageView

Description: Tracks a page view event.

Parameters

Name	Type	Required	Description
`locale`	`string`	❌	The locale of the event
`group`	`object`	❌	The group if there is an AB test active (recommended to set the group globally when instantiating the `XGenClient`)
↳ `group.id`	`string`	❌	The id of the AB group
↳ `group.name`	`string`	❌	The name of the AB group
`url`	`string`	❌	The url the event was sent from (passed by default in the browser)
`referrer`	`string`	❌	The referrer the event was sent from (passed by default in the browser)
`context`	`object`	❌	Additional information about the event.

itemView

itemView

Description: Tracks a item/product view event.

Parameters

Name	Type	Required	Description
`item`	`object`	✅	The item/product to track
↳ `item.id`	`string`	✅	The id of the item/product
↳ `item.name`	`string`	✅	The name of the item/product
↳ `item.price`	`string`	✅	The price of the item/product
↳ `item.currency`	`string`	✅	The currency of the item/product. Ex. USD
`locale`	`string`	❌	The locale of the event
`group`	`object`	❌	The group if there is an AB test active (recommended to set the group globally when instantiating the `XGenClient`)
↳ `group.id`	`string`	❌	The id of the AB group
↳ `group.name`	`string`	❌	The name of the AB group
`url`	`string`	❌	The url the event was sent from (passed by default in the browser)
`referrer`	`string`	❌	The referrer the event was sent from (passed by default in the browser)
`context`	`object`	❌	Additional information about the event.

categoryView

categoryView

Description: Tracks a category view event.

Parameters

Name	Type	Required	Description
`category`	`string`	✅	The category to track
`items`	`string[]`	✅	The ids of the first few category items/products
`locale`	`string`	❌	The locale of the event
`group`	`object`	❌	The group if there is an AB test active (recommended to set the group globally when instantiating the `XGenClient`)
↳ `group.id`	`string`	❌	The id of the AB group
↳ `group.name`	`string`	❌	The name of the AB group
`url`	`string`	❌	The url the event was sent from (passed by default in the browser)
`referrer`	`string`	❌	The referrer the event was sent from (passed by default in the browser)
`context`	`object`	❌	Additional information about the event.

addToCart

addToCart

Description: Tracks an add to cart event.

Parameters

Name	Type	Required	Description
`item`	`object`	✅	The item/product to track
↳ `item.id`	`string`	✅	The id of the item/product
↳ `item.name`	`string`	✅	The name of the item/product
↳ `item.price`	`string`	✅	The price of the item/product
↳ `item.currency`	`string`	✅	The currency of the item/product. Ex. USD
↳ `item.quantity`	`number`	✅	The quantity of the item/product
`locale`	`string`	❌	The locale of the event
`group`	`object`	❌	The group if there is an AB test active (recommended to set the group globally when instantiating the `XGenClient`)
↳ `group.id`	`string`	❌	The id of the AB group
↳ `group.name`	`string`	❌	The name of the AB group
`url`	`string`	❌	The url the event was sent from (passed by default in the browser)
`referrer`	`string`	❌	The referrer the event was sent from (passed by default in the browser)
`context`	`object`	❌	Additional information about the event.

purchaseOrder

purchaseOrder

Description: Tracks a purchase order event.

Parameters

Name	Type	Required	Description
`items`	`object[]`	✅	The array of items/products to track
↳ `item.id`	`string`	✅	The id of the item/product
↳ `item.name`	`string`	✅	The name of the item/product
↳ `item.price`	`string`	✅	The price of the item/product
↳ `item.currency`	`string`	✅	The currency of the item/product. Ex. USD
↳ `item.quantity`	`number`	✅	The quantity of the item/product
`orderId`	`string`	✅	The unique identifier of the order
`locale`	`string`	❌	The locale of the event
`group`	`object`	❌	The group if there is an AB test active (recommended to set the group globally when instantiating the `XGenClient`)
↳ `group.id`	`string`	❌	The id of the AB group
↳ `group.name`	`string`	❌	The name of the AB group
`url`	`string`	❌	The url the event was sent from (passed by default in the browser)
`referrer`	`string`	❌	The referrer the event was sent from (passed by default in the browser)
`context`	`object`	❌	Additional information about the event.

elementView

elementView

Description: Tracks the view of a specific dom node.

Parameters

Name	Type	Required	Description
`element`	`object`	✅	Information about the dom node to track
↳ `element.id`	`string`	✅	The id of the dom node. For tracking XGen, this should match the recommendation experience ID. If tracking a competitor, prefix the id with `competitor-`
↳ `element.items`	`string[]`	✅	An array of the items/product ids shown in the element
`locale`	`string`	❌	The locale of the event
`group`	`object`	❌	The group if there is an AB test active (recommended to set the group globally when instantiating the `XGenClient`)
↳ `group.id`	`string`	❌	The id of the AB group
↳ `group.name`	`string`	❌	The name of the AB group
`url`	`string`	❌	The url the event was sent from (passed by default in the browser)
`referrer`	`string`	❌	The referrer the event was sent from (passed by default in the browser)
`context`	`object`	❌	Additional information about the event.

elementRender

elementRender

Description: Tracks the render of a specific dom node.

Parameters

Name	Type	Required	Description
`element`	`object`	✅	Information about the dom node to track
↳ `element.id`	`string`	✅	The id of the dom node. For tracking XGen, this should match the recommendation experience ID. If tracking a competitor, prefix the id with `competitor-`
↳ `element.items`	`string[]`	✅	An array of the items/product ids shown in the element
`locale`	`string`	❌	The locale of the event
`group`	`object`	❌	The group if there is an AB test active (recommended to set the group globally when instantiating the `XGenClient`)
↳ `group.id`	`string`	❌	The id of the AB group
↳ `group.name`	`string`	❌	The name of the AB group
`url`	`string`	❌	The url the event was sent from (passed by default in the browser)
`referrer`	`string`	❌	The referrer the event was sent from (passed by default in the browser)
`context`	`object`	❌	Additional information about the event.

elementClick

elementClick

Description: Tracks the render of a specific dom node.

Parameters

Name	Type	Required	Description
`element`	`object`	✅	Information about the dom node to track
↳ `element.id`	`string`	✅	The id of the dom node. For tracking XGen, this should match the recommendation experience ID. If tracking a competitor, prefix the id with `competitor-`
↳ `element.items`	`string[]`	✅	An array of the items/product ids shown in the element
`item`	`string`	✅	The id of the item/product clicked. This should match the `prod_code` in the XGen platform.
`locale`	`string`	❌	The locale of the event
`group`	`object`	❌	The group if there is an AB test active (recommended to set the group globally when instantiating the `XGenClient`)
↳ `group.id`	`string`	❌	The id of the AB group
↳ `group.name`	`string`	❌	The name of the AB group
`url`	`string`	❌	The url the event was sent from (passed by default in the browser)
`referrer`	`string`	❌	The referrer the event was sent from (passed by default in the browser)
`context`	`object`	❌	Additional information about the event.

searchQuery

searchQuery

Description: Tracks the search query. This is an event right before the search request is sent.

Parameters

Name	Type	Required	Description
`query`	`object`	✅	Information about the dom node to track
`queryId`	`string`	✅	The id of the search query
`deploymentId`	`string`	✅	The id of the deployment. For tracking XGen, this should match the search experience ID. If tracking a competitor, prefix the id with `competitor-`
`isTypeToSearch`	`boolean`	❌	Whether the query is a type-to-search query (defaults to `false`)
`page`	`number`	❌	The page number of the search query
`locale`	`string`	❌	The locale of the event
`group`	`object`	❌	The group if there is an AB test active (recommended to set the group globally when instantiating the `XGenClient`)
↳ `group.id`	`string`	❌	The id of the AB group
↳ `group.name`	`string`	❌	The name of the AB group
`url`	`string`	❌	The url the event was sent from (passed by default in the browser)
`referrer`	`string`	❌	The referrer the event was sent from (passed by default in the browser)
`context`	`object`	❌	Additional information about the event.

searchResult

searchResult

Description: Tracks the results of the search request.

Parameters

Name	Type	Required	Description
`query`	`object`	✅	Information about the dom node to track
`queryId`	`string`	✅	The id of the search query
`deploymentId`	`string`	✅	The id of the deployment. For tracking XGen, this should match the search experience ID. If tracking a competitor, prefix the id with `competitor-`
`items`	`string[]`	✅	An array of the items/product ids in the search results
`isTypeToSearch`	`boolean`	❌	Whether the query is a type-to-search query
`page`	`number`	❌	The page number of the search query
`locale`	`string`	❌	The locale of the event
`group`	`object`	❌	The group if there is an AB test active (recommended to set the group globally when instantiating the `XGenClient`)
↳ `group.id`	`string`	❌	The id of the AB group
↳ `group.name`	`string`	❌	The name of the AB group
`url`	`string`	❌	The url the event was sent from (passed by default in the browser)
`referrer`	`string`	❌	The referrer the event was sent from (passed by default in the browser)
`context`	`object`	❌	Additional information about the event.

searchClick

searchClick

Description: Tracks a click event on a search result.

Parameters

Name	Type	Required	Description
`query`	`object`	✅	Information about the dom node to track
`queryId`	`string`	✅	The id of the search query
`deploymentId`	`string`	✅	The id of the deployment. For tracking XGen, this should match the search experience ID. If tracking a competitor, prefix the id with `competitor-`
`item`	`string`	✅	The id of the item/product clicked. This should match the `prod_code` in the XGen platform.
`items`	`string[]`	✅	An array of the items/product ids in the search results
`isTypeToSearch`	`boolean`	❌	Whether the query is a type-to-search query
`page`	`number`	❌	The page number of the search query
`locale`	`string`	❌	The locale of the event
`group`	`object`	❌	The group if there is an AB test active (recommended to set the group globally when instantiating the `XGenClient`)
↳ `group.id`	`string`	❌	The id of the AB group
↳ `group.name`	`string`	❌	The name of the AB group
`url`	`string`	❌	The url the event was sent from (passed by default in the browser)
`referrer`	`string`	❌	The referrer the event was sent from (passed by default in the browser)
`context`	`object`	❌	Additional information about the event.

groupAssignment

groupAssignment

Description: Tracks when a user gets assigned to a specific AB group.

Parameters

Name	Type	Required	Description
`group`	`object`	✅	The group of the user
↳ `group.id`	`string`	✅	The id of the AB group
↳ `group.name`	`string`	✅	The name of the AB group
`previousGroup`	`object`	❌	The previous group of the user (if applicable)
↳ `previousGroup.id`	`string`	❌	The id of the AB group (previous)
↳ `previousGroup.name`	`string`	❌	The name of the AB group (previous)
`url`	`string`	❌	The url the event was sent from (passed by default in the browser)
`referrer`	`string`	❌	The referrer the event was sent from (passed by default in the browser)
`context`	`object`	❌	Additional information about the event.

customEvent

customEvent

Description: Tracks a custom event.

Parameters

Name	Type	Required	Description
`category`	`string`	✅	The category of the event type
`action`	`string`	✅	The action of the event
`name`	`string`	✅	The name of the event
`value`	`string`	✅	The value of the event
`locale`	`string`	❌	The locale of the event
`group`	`object`	❌	The group if there is an AB test active (recommended to set the group globally when instantiating the `XGenClient`)
↳ `group.id`	`string`	❌	The id of the AB group
↳ `group.name`	`string`	❌	The name of the AB group
`url`	`string`	❌	The url the event was sent from (passed by default in the browser)
`referrer`	`string`	❌	The referrer the event was sent from (passed by default in the browser)
`context`	`object`	❌	Additional information about the event.