--- title: "Tracking Service" slug: "tracking" updated: 2025-12-09T14:59:42Z published: 2025-12-09T14:59:42Z canonical: "docs.xgen.ai/tracking" --- > ## Documentation Index > Fetch the complete documentation index at: https://docs.xgen.ai/llms.txt > Use this file to discover all available pages before exploring further. # 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 ```typescript    cons xg = new XGenClient({     // ...other params,     locale: () => '',     // or     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 ```typescript    cons xg = new XGenClient({     // ...other params,     group: () => '',     // or     group: '',    }) ``` --- ## Methods ```typescript // 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** ```javascript {  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. |