--- title: "Getting Started Guide" slug: "getting-started-guide" updated: 2025-12-10T14:54:47Z published: 2025-12-10T14:54:47Z canonical: "docs.xgen.ai/getting-started-guide" --- > ## 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. # Getting Started Guide 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` ```typescript 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. ```typescript 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](/v1/docs/events-summary) 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](/v1/docs/tracking#parameters). Example: ```typescript xg.track.pageView(); ``` **Example API Payload sent when the method is called correctly:** ```json {    "rec": "1",    "idsite": "client-tracker-id",    "url": "",    "urlref": "",    "locale": "en-us",    "uid": "{\"customer_id\":\"123\",\"user_type\":\"\",\"session_id\":\"",    "urlref": "",    "locale": "en-us",    "uid": "{\"customer_id\":\"123\",\"user_type\":\"\",\"session_id\":\"",    "urlref": "",    "locale": "en-us",    "uid": "{\"customer_id\":\"123\",\"user_type\":\"\",\"session_id\":\"",    "urlref": "",    "locale": "en-us",    "uid": "{\"customer_id\":\"123\",\"user_type\":\"\",\"session_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. ```json [    {        "rec": "1",        "idsite": "client-tracker-id",        "url": "",        "urlref": "",        "locale": "en-us",        "uid": "{\"customer_id\":\"123\",\"user_type\":\"\",\"session_id\":\"",        "action_name": "product_purchase",        "action_detail": "product_purchase",        "action_type": "ecomm",        "version": "2"    },    {        "rec": "1",        "idsite": "client-tracker-id",        "url": "",        "urlref": "",        "locale": "en-us",        "uid": "{\"customer_id\":\"123\",\"user_type\":\"\",\"session_id\":\"",        "action_name": "product_purchase",        "action_detail": "product_purchase",        "action_type": "ecomm",        "version": "2"    },    {        "rec": "1",        "idsite": "client-tracker-id",        "url": "",        "urlref": "",        "locale": "en-us",        "uid": "{\"customer_id\":\"123\",\"user_type\":\"\",\"session_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](/v1/docs/tracking#parameters5). Example: ```typescript xg.track.elementView({    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:** ```json {    "rec": "1",    "idsite": "client-tracker-id",    "url": "",    "urlref": "",    "locale": "en-us",    "uid": "{\"customer_id\":\"123\",\"user_type\":\"\",\"session_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](/v1/docs/tracking#parameters6). Example: ```typescript xg.track.elementRender({    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:** ```json {    "rec": "1",    "idsite": "client-tracker-id",    "url": "",    "urlref": "",    "locale": "en-us",    "uid": "{\"customer_id\":\"123\",\"user_type\":\"\",\"session_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](/v1/docs/tracking#parameters7). Example: ```typescript xg.track.elementClick({    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:** ```json {    "rec": "1",    "idsite": "client-tracker-id",    "url": "",    "urlref": "",    "locale": "en-us",    "uid": "{\"customer_id\":\"123\",\"user_type\":\"\",\"session_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](/v1/docs/tracking#parameters8). Example: ```typescript // 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: '', }); // or // Example being used in xg.search.getResults() xg.track.getResults({ query: 'your-query', options: { deploymentId: '', 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:** ```json {    "rec": "1",    "idsite": "client-tracker-id",    "url": "",    "urlref": "",    "locale": "en-us",    "uid": "{\"customer_id\":\"123\",\"user_type\":\"\",\"session_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](/v1/docs/tracking#parameters9). Example: ```typescript // 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: '',    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: '', collection: 'en-us' }, }); ``` **Example API Payload sent when the method is called correctly:** ```json {    "rec": "1",    "idsite": "client-tracker-id",    "url": "",    "urlref": "",    "locale": "en-us",    "uid": "{\"customer_id\":\"123\",\"user_type\":\"\",\"session_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": "",        "deployment_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:** ```json {    "rec": "1",    "idsite": "client-tracker-id",    "url": "",    "urlref": "",    "locale": "en-us",    "uid": "{\"customer_id\":\"123\",\"user_type\":\"\",\"session_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": "",        "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](/v1/docs/tracking#parameters11). Example: ```typescript // 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:** ```json [    {    "rec": "1",    "idsite": "client-tracker-id",    "url": "",    "urlref": "",    "locale": "en-us",        "uid": "{\"customer_id\":\"123\",\"user_type\":\"\",\"session_id\":\"