Getting Started Guide

  • Updated on Dec 10, 2025
  • Published on Dec 9, 2025
  • 11 minute(s) read
Prev Next

  1. Initialize the XGenClient

For the remainder of this document we will use an example client with the below information:

key: client-key

secret: client-secret

clientId: 123

trackerId: client-tracker-id

locale: en-us

collection: en-us

import XGenClient from '@xgenai/sdk-core';

const xg = new XGenClient({
  key: 'client-key',
  secret: 'client-secret',
  clientId: '123',
  trackerId: 'client-tracker-id',
  locale: 'en-us', // <-- The locale will automatically be sent with every event because it was set globally on the client
  group: () => 'a' // <-- If running an AB test, the same can be done for group
});

Shopify Specific Initialization

When using the Shopify App and the SDK together, it is important to make sure the cookies are being set at the root level for the SDK so that duplicate cookies are not set in the user’s browser. Below is an example of how to pass those options.

import XGenClient, { LocalCookieAuthStore } from '@xgenai/sdk-core';
const xg = new XGenClient({
    ..., // Other params
    authStore: new LocalCookieAuthStore({ cookieOptions: { domain: '.example.com' } })
});

  1. Setup Event Tracking

For a high level break down and explanation of the different event types. See this document.

Global Notes:

  • The url and referrer are sent by default when the SDK is used in a browser environment.

  • In the uid the user_type and session_id should be coming from the xgen_user and xgen_session cookies respectively.

  • For competitor tracking, please send any id field prefixed with competitor-

    • This is important when running an AB test so we can separate our analytics vs our competitor analytics. And recommendation or search not powered by XGen should have the competitor- prefix.

Shopify Specific Event Tracking

If you are integrating using a hybrid approach with our Shopify App and the SDK, some events are sent by default by the app.

  • Events sent automatically:

    • page_view, product_view, category_view, product_purchase, purchase_order

  • Events that need to be handled in the SDK:

    • search, search_result, search_click, element_impression, element_view, element_click , add_to_cart

Page View

A page view event should be on each page refresh or page navigation on your site. See all options here.

Example:

xg.track.pageView();

Example API Payload sent when the method is called correctly:

{
    "rec": "1",
    "idsite": "client-tracker-id",
    "url": "<current-url>",
    "urlref": "<referrer-url>",
    "locale": "en-us",
    "uid": "{\"customer_id\":\"123\",\"user_type\":\"<user_type_from_cookie>\",\"session_id\":\"<session_from_cookie\"}",
    "action_detail": "page_view",
    "action_name": "page_view",
    "action_type": "ecomm"
}

Item View

An item view should be sent when a user lands on a product display page and should include information about the currently viewed product. See all options here.

Example:

xg.track.itemView({
  item: {
    id: '123' // This MUST match the exact prod_code in the XGen Catalog,
    name: 'Dress',
    price: 200,
    currency: 'USD'
  }
});

Example API Payload sent when the method is called correctly:

Notes

  • In the cvar property, the information sent above should line up like in the example below.

{
    "rec": "1",
    "idsite": "client-tracker-id",
    "url": "<current-url>",
    "urlref": "<referrer-url>",
    "locale": "en-us",
    "uid": "{\"customer_id\":\"123\",\"user_type\":\"<user_type_from_cookie>\",\"session_id\":\"<session_from_cookie\"}",
    "cvar": "{\"2\":[\"_pkp\",200],\"3\":[\"_pks\",\"123\"],\"4\":[\"_pkn\",\"Dress\"],\"5\":[\"_pkc\",\"{\\\"currency_code\\\":\\\"USD\\\"}\"]}",
    "action_name": "product_view",
    "action_detail": "product_view",
    "action_type": "ecomm"
}

Category View

A category view should be sent on product listing pages to send information about the category and some of the products returned on those pages. See all options here.

Example:

xg.track.categoryView({
  category: 'Dresses',
  items: ['123', '456', '789', ...], // Add the first 10 products if available. This should match exactly to the prod_codes in the XGen catalog.
});

Example API Payload sent when the method is called correctly:

Notes:

  • In cvar , the _pkc field should line up with the category sent above

  • In context.plpProducts , the items should match with the items field sent above

{
    "rec": "1",
    "idsite": "client-tracker-id",
    "url": "<current-url>",
    "urlref": "<referrer-url>",
    "locale": "en-us",
    "uid": "{\"customer_id\":\"123\",\"user_type\":\"<user_type_from_cookie>\",\"session_id\":\"<session_from_cookie\"}",
    "cvar": "{\"5\":[\"_pkc\",\"Dresses\"]}",
    "action_name": "category_view",
    "action_detail": "category_view",
    "action_type": "ecomm",
    "context": {
        "plpProducts": [
            "123",
            "456",
            "789",
            ...
        ]
    }
}

Add to Cart

An add to cart event should be sent anytime an item is added to the user’s cart from anywhere on the site. See all options here.

Example:

xg.track.addToCart({
  item: {
    id: '123' // This MUST match the exact prod_code in the XGen Catalog,
    name: 'Dress',
    price: 200,
    currency: 'USD',
    quantity: 2
  }
});

Example API Payload sent when the method is called correctly:

Notes:

  • In ec_items, It should go, in order, id, name, currency, price, quantity

  • In revenue, it should be price * quantity

{
    "rec": "1",
    "idsite": "client-tracker-id",
    "url": "<current-url>",
    "urlref": "<referrer-url>",
    "locale": "en-us",
    "uid": "{\"customer_id\":\"123\",\"user_type\":\"<user_type_from_cookie>\",\"session_id\":\"<session_from_cookie\"}",
    "ec_items": "[[\"123\",\"Dress\",\"{\\\"currency_code\\\":\\\"USD\\\"}\",200,2]]",
    "revenue": 400,
    "action_name": "product_add",
    "action_detail": "product_add",
    "action_type": "ecomm"
}

Purchase Order

An event sent when a user makes a purchase on the site. This event will group product purchase (individual items purchased) and the purchase order (the group of items purchased together) into on method call. See all options here.

Example:

xg.track.purchaseOrder({
	items: [
		    {
			    id: '123',
			    name: 'Dress',
			    price: 200,
			    quantity: 2,
			    currency: 'USD',
		    },
            {
		        id: '456',
			    name: 'Pants',
			    price: 100,
			    quantity: 1,
			    currency: 'USD',
		     }
		],
		orderId: '<order-id>',
});

Example API Payload sent when the method is called correctly:

Notes:

  • This is an example purchase order with two unique products purchased. You can see two product purchase events along with one purchase order event. The purchase order event is important for our Purchased With recommendation model.

[
    {
        "rec": "1",
        "idsite": "client-tracker-id",
        "url": "<current-url>",
        "urlref": "<referrer-url>",
        "locale": "en-us",
        "uid": "{\"customer_id\":\"123\",\"user_type\":\"<user_type_from_cookie>\",\"session_id\":\"<session_from_cookie\"}",
        "ec_items": "[[\"123\",\"Dress\",\"{\\\"currency_code\\\":\\\"USD\\\"}\",200,2]]",
        "ec_id": "<order-id>",
        "action_name": "product_purchase",
        "action_detail": "product_purchase",
        "action_type": "ecomm",
        "version": "2"
    },
    {
        "rec": "1",
        "idsite": "client-tracker-id",
        "url": "<current-url>",
        "urlref": "<referrer-url>",
        "locale": "en-us",
        "uid": "{\"customer_id\":\"123\",\"user_type\":\"<user_type_from_cookie>\",\"session_id\":\"<session_from_cookie\"}",
        "ec_items": "[[\"456\",\"Pants\",\"{\\\"currency_code\\\":\\\"USD\\\"}\",100,1]]",
        "ec_id": "<order-id>",
        "action_name": "product_purchase",
        "action_detail": "product_purchase",
        "action_type": "ecomm",
        "version": "2"
    },
    {
        "rec": "1",
        "idsite": "client-tracker-id",
        "url": "<current-url>",
        "urlref": "<referrer-url>",
        "locale": "en-us",
        "uid": "{\"customer_id\":\"123\",\"user_type\":\"<user_type_from_cookie>\",\"session_id\":\"<session_from_cookie\"}",
        "ec_items": "[[\"123\",\"Dress\",\"{\\\"currency_code\\\":\\\"USD\\\"}\",200,2],[\"456\",\"Pants\",\"{\\\"currency_code\\\":\\\"USD\\\"}\",100,1]]",
        "revenue": 500,
        "ec_id": "<order-id>",
        "ec_st": 500,
        "ec_tx": 0,
        "ec_dt": "0",
        "idgoal": "0",
        "action_name": "purchase_order",
        "action_detail": "purchase_order",
        "action_type": "ecomm",
        "version": "2"
    }
]

Element View

An element view event should be sent when an element in the dom becomes visible in the viewport. The best practice to handle this logic is by attaching an intersection observer. See all options here.

Example:

xg.track.elementView({
    element: {
        id: '<element-id>', // The id of the element to track. For example, the XGen experience id (sm_el_...)
        items: ['123', '456', '789', ...], // The product codes that are recommended by this element
    },
});

Example API Payload sent when the method is called correctly:

{
    "rec": "1",
    "idsite": "client-tracker-id",
    "url": "<current-url>",
    "urlref": "<referrer-url>",
    "locale": "en-us",
    "uid": "{\"customer_id\":\"123\",\"user_type\":\"<user_type_from_cookie>\",\"session_id\":\"<session_from_cookie\"}",
    "c_n": "<element-id>",
    "c_t": "123,456,789,...", // The product codes that are recommended by this element
    "c_i": "elementViewed",
    "action_name": "content_tracking",
    "action_detail": "element_view",
    "action_type": "smart_element"
}

Element Render

An element render event should be sent when an element is rendered in the dom. It needs to be visible and have a width and height > 0px. See all options here.

Example:

xg.track.elementRender({
    element: {
        id: '<element-id>', // The id of the element to track. For example, the XGen experience id (sm_el_...)
        items: ['123', '456', '789', ...], // The product codes that are recommended by this element
    },
});

Example API Payload sent when the method is called correctly:

{
    "rec": "1",
    "idsite": "client-tracker-id",
    "url": "<current-url>",
    "urlref": "<referrer-url>",
    "locale": "en-us",
    "uid": "{\"customer_id\":\"123\",\"user_type\":\"<user_type_from_cookie>\",\"session_id\":\"<session_from_cookie\"}",
    "c_n": "<element-id>",
    "c_t": "123,456,789,...", // The product codes that are recommended by this element
    "action_name": "content_tracking",
    "action_detail": "element_impression",
    "action_type": "smart_element"
}

Element Click

An element click event should be sent when an item is clicked in one of the recommendation elements. (There is a separate event for search). See all options here.

Example:

xg.track.elementClick({
    element: {
        id: '<element-id>', // The id of the element to track (sm_el_...)
        items: ['456', '789', ...], // The products recommended by the element
    },
    item: '123', // The product code of the item that was clicked
});

Example API Payload sent when the method is called correctly:

{
    "rec": "1",
    "idsite": "client-tracker-id",
    "url": "<current-url>",
    "urlref": "<referrer-url>",
    "locale": "en-us",
    "uid": "{\"customer_id\":\"123\",\"user_type\":\"<user_type_from_cookie>\",\"session_id\":\"<session_from_cookie\"}",
    "c_n": "<element-id>",
    "c_p": "123", // The product code of the product that was clicked
    "c_t": "123,456,789,...", // The product codes that are recommended by this element
    "c_i": "elementClicked",
    "action_name": "content_tracking",
    "action_detail": "element_click",
    "action_type": "smart_element"
}

Search Query

This event should be sent when a user first sends a search request to the XGen backend. (This will be sent by default when using the SDK xg.search.getResults method). See all options here.

Example:

// Direct tracking api call
xg.track.searchQuery({
    query: 'your-query',
    queryId: 'id-of-search-request', /* A unique identifier for this search request. The SAME queryId must be used for search_query, search_result, and search_click events so they can be linked together. */
    deploymentId: '<xsearch-experience-id>',
});

// or

// Example being used in xg.search.getResults()
xg.track.getResults({
	query: 'your-query',
	options: { deploymentId: '<xsearch-experience-id>', collection: 'en-us' },
});

// Both a search_query and search_result will be sent automatically here

Example API Payload sent when the method is called correctly:

{
    "rec": "1",
    "idsite": "client-tracker-id",
    "url": "<current-url>",
    "urlref": "<referrer-url>",
    "locale": "en-us",
    "uid": "{\"customer_id\":\"123\",\"user_type\":\"<user_type_from_cookie>\",\"session_id\":\"<session_from_cookie\"}",
    "query_id": "id-of-search-request", // Should be a unique identifier fo the group of search events - this is done automatically with xg.search.getResults()
    "action_name": "search",
    "action_detail": "search",
    "action_type": "search_service",
    "context": {
        "query": "your-query", // should match you query passed
        "deployment_id": "<xsearch-experience-id>", // should match the deploymentId passed
        "is_type_to_search": false, // If the results came from type to search or not - Is true if forceDeepSearch is turned on in xg.search.getResults()
        "page": 0 // The page of the results
    }
}

Search Result

This event should be sent when a user gets the response back from the XGen backend. (This will be sent by default when using the SDK xg.search.getResults method). See all options here.

Example:

// Direct tracking api call
xg.track.searchResult({
    query: 'your-query',
    queryId: 'id-of-search-request', /* A unique identifier for this search request. The SAME queryId must be used for search_query, search_result, and search_click events so they can be linked together. */
    deploymentId: '<xsearch-experience-id>',
    items: ['123', '456', '789', ...] // The items that the search response returns
});

// or

// Example being used in xg.search.getResults()
// Both a search_query and search_result will be sent automatically here
xg.track.getResults({
	query: 'your-query',
	options: { deploymentId: '<xsearch-experience-id>', collection: 'en-us' },
});

Example API Payload sent when the method is called correctly:

{
    "rec": "1",
    "idsite": "client-tracker-id",
    "url": "<current-url>",
    "urlref": "<referrer-url>",
    "locale": "en-us",
    "uid": "{\"customer_id\":\"123\",\"user_type\":\"<user_type_from_cookie>\",\"session_id\":\"<session_from_cookie\"}",
    "c_n": "<xsearch-experience-id>",
    "c_t": "123,456,789,...",
    "c_i": "searchResult",
    "query_id": "id-of-search-request",
    "action_name": "content_tracking",
    "action_detail": "search_result",
    "action_type": "search_service",
    "context": {
        "query": "<your-query>",
        "deployment_id": "<your-xsearch-experience-id",
        "is_type_to_search": false,
        "page": 0
    }
}

Search Click

A search click event should be sent when an item from a search response is clicked by a user. See all options here.

Example:

xg.track.searchClick({
	query: 'your-query',
    queryId: 'id-of-search-request', /* A unique identifier for this search request. The SAME queryId must be used for search_query, search_result, and search_click events so they can be linked together. */
    deploymentId: '<xsearch-experience-id>',
	item: '123', // product code of the item that was clicked
    items: ['123', '456', '789', ...] // The items that the search response returns
});

Example API Payload sent when the method is called correctly:

{
    "rec": "1",
    "idsite": "client-tracker-id",
    "url": "<current-url>",
    "urlref": "<referrer-url>",
    "locale": "en-us",
    "uid": "{\"customer_id\":\"123\",\"user_type\":\"<user_type_from_cookie>\",\"session_id\":\"<session_from_cookie\"}",
    "c_n": "<xsearch-experience-id>",
    "c_p": "123",
    "c_t": "123,456,789,...",
    "c_i": "searchClicked",
    "query_id": "id-of-search-request",
    "action_name": "content_tracking",
    "action_detail": "search_click",
    "action_type": "search_service",
    "context": {
        "query": "your-query",
        "deployment_id": "<xsearch-experience-id>",
        "page": 0
    }
}

Group Assignment

A group assignment event should be sent when a user is assigned an AB group for the first time or switches AB groups during a test. See all options here.

Example:

// Example of user initially being assigned a group
xg.track.groupAssignment({
	group: { id: 'test-id', name: 'A' },
});

// Example of user switching groups
xg.track.groupAssignment({
	group: { id: 'test-id', name: 'A' },
	previousGroup: { id: 'test-id', name: 'B' },
});

Example API Payload sent when the method is called correctly:

[
    {
    "rec": "1",
    "idsite": "client-tracker-id",
    "url": "<current-url>",
    "urlref": "<referrer-url>",
    "locale": "en-us",
        "uid": "{\"customer_id\":\"123\",\"user_type\":\"<user_type_from_cookie>\",\"session_id\":\"<session_from_cookie\",\"testing_group_name\":\"A\",\"ab_test_id\":\"test-id\"}",
        "action_name": "group_assignment",
        "action_detail": "group_assignment",
        "action_type": "ecomm",
        "context": {
            "new_value": "A",
            "prev_value": "B"
        }
    }
]

  1. Setup XRecommend (if applicable)

  1. Create an XRecommend Experience in the XGen Platform

    2. Name your experience, create a custom identifier (optional), and choose “API Version”

      2. Configure your experience and select a Recommendation Type (see this table for information about each of the recommendation types)

  2. Use the SDK to get predictions for your experience (see response here)

    1. // Returns a recommendation response mapped by element IDs. Way to fetch multiple experiences in one call.
xg.recommend.getResults({ elementIds: ['sm_el_xrec_experience', 'sm_el_another_experience_id'], options: { pathname: '/en-us/' } });

// Returns a recommendation response for the given element ID.
xg.recommend.getResultsById({ elementId: 'sm_el_xrec_experience', options: { pathname: '/en-us/' } });

  1. Setup XSearch (if applicable)

  1. Create an XSearch Experience in the XGen Platform

    2. Name your deployment and choose “API Version”

      2. Configure your experience with an engine and merchandising rule (should be setup previously)

  2. Use the SDK to get search results for your experience

    1. // Returns a search response containing the results
xg.search.getResults({query: 'coat', options: {collection: 'en-us', deploymentId:'deployment_id'}});