XGEN

https://docs.xgen.ai/
Admin
XGEN provides generative AI tools for e-commerce teams, including powerful search (XSearch) and...
Tokens:5,141
Snippets:21
Trust Score:8.2
Update:1 year ago
Show doc for...
Tokens:
Raw
### Example JSON Response for Search API

Source: https://docs.xgen.ai/v1/docs/search-function

This JSON object illustrates the typical structure of a successful response from the search API, including product data, pagination details, caching information, and facet aggregations for filtering search results. It serves as a concrete example of the data format.

```JSON
{
    "page": 0,
    "total_result": 1705,
    "cache_ttl_used": 86400,
    "hrnn_n": 0,
    "search_threshold_achieved": "Not triggered",
    "behavior_id": "bdb7268b-ada6-4310-8353-f7b34713e1b5",
    "response_engine": "ds",
    "is_from_cache": true,
    "is_sorted_by_hrnn": false,
    "is_keyword_config_applied": false,
    "is_ai_sorting_tried": false,
    "is_neural": true,
    "is_cached_filter_applied": true,
    "is_url_redirect": false,
    "products_list": [
        {
            "prod_code": "xyz",
            "prod_name": "Fancy Dress",
            "prod_price": 3800,
            "image": "example.com/image/product_1.jpg"
        },
        {
            "prod_code": "abc",
            "prod_name": "Fun Dress",
            "prod_price": 1800,
            "image": "example.com/image/product_2.jpg"
        },
        {
            "prod_code": "def",
            "prod_name": "Nice Dress",
            "prod_price": 1800,
            "image": "example.com/image/product_3.jpg"
        }
    ],
    "product_code_variant_mapping": {},
    "reason": [],
    "search_term_matches": [],
    "user_data": {},
    "facet": {
        "aggregations": {
            "group": {
                "color": {
                    "buckets": [
                        {
                            "doc_count": 1510,
                            "key": "-"
                        },
                        {
                            "doc_count": 134,
                            "key": "brown"
                        },
                        {
                            "doc_count": 30,
                            "key": "black"
                        },
                        {
                            "doc_count": 20,
                            "key": "tan"
                        }
                    ],
                    "doc_count_error_upper_bound": 0,
                    "sum_other_doc_count": 0
                },
                "is_in_stock": {
                    "buckets": [
                        {
                            "doc_count": 1578,
                            "key": "1"
                        },
                        {
                            "doc_count": 127,
                            "key": "0"
                        }
                    ],
                    "doc_count_error_upper_bound": 0,
                    "sum_other_doc_count": 0
                },
                "type": {
                    "buckets": [
                        {
                            "doc_count": 1591,
                            "key": "dresses"
                        },
                        {
                            "doc_count": 106,
                            "key": "shoes"
                        },
                        {
                            "doc_count": 4,
                            "key": "skirts"
                        }
                    ],
                    "doc_count_error_upper_bound": 0,
                    "sum_other_doc_count": 0
                }
            }
        }
    }
}
```

--------------------------------

### Implement onPageMatched for PDP Tracking in JavaScript

Source: https://docs.xgen.ai/v1/docs/onpagematched

This example demonstrates a practical application of the `onPageMatched` function. It shows how to integrate a `trackPdp` function call within `onPageMatched` to fire Product Detail Page (PDP) tracking events, ensuring they are triggered precisely when the page is matched and ready.

```JavaScript
onPageMatched: () => {
 	trackPdp(...)
}
```

--------------------------------

### xgenSdkIntegration: getSearchHistory API Reference

Source: https://docs.xgen.ai/v1/docs/search-history

Documents the `getSearchHistory` function, including its parameters, return value, and an example of the data structure returned.

```APIDOC
getSearchHistory()
  - Description: Retrieves the past 10 search queries that the user has made.
  - Parameters: None.
  - Returns: An array of strings containing the last 10 queries the user searched for. The first item in the array is the most recent search.
  - Example Response:
    [
        "pants",
        "shirt",
        "ties",
        "shoes for men",
        "shoes",
        "hat",
        "pants",
        "jacket",
        "hoodie",
        "sweatshirt"
    ]
```

--------------------------------

### Import and Call getSearchHistory Function

Source: https://docs.xgen.ai/v1/docs/search-history

Shows the basic setup for importing the `getSearchHistory` function from the `xgenSdkIntegration` module and executing it to retrieve search history.

```javascript
import { integration } from './xgenSdkIntegration';
const { getSearchHistory } = integration;

getSearchHistory();
```

--------------------------------

### XSearch Keyword Configuration and Management

Source: https://docs.xgen.ai/v1/docs/managed-keywords

Comprehensive guide to configuring and managing XSearch Keywords, including creation, settings, and result control. Keywords allow precise control over search results for specific terms, overriding engine-level settings.

```APIDOC
XSearch Keyword Configuration:

Keyword Creation:
  - Process: When setting up a new keyword, you must choose a region (or global).
  - Management Pages: Each keyword can be managed using four distinct pages: Settings, Results, Pinned, and Excluded.
  - Matching Logic: The user's entire query must match exactly with the configured keyword for it to apply (e.g., 'shirt' matches 'shirt' but not 'blue shirt').

Settings Overview:
  - The available settings will change based on the selected keyword type.

URL Redirect:
  - Purpose: Redirect specific search queries to custom landing pages (e.g., 'Sustainable' to 'www.brand.com/our-environmental-stance').
  - Configuration: Specify the target URL.
  - Behavior: Adjusts the output of the keyword to be the specified URL. The front-end component must also be configured to use this URL for navigation or display.
  - Limitations: When URL Redirects are enabled, the only other available setting to edit is 'Keyword Synonym'. All other settings are unavailable or will be ignored.

Keyword Synonym:
  - Purpose: Point multiple synonyms to the results of a single keyword, preventing redundant configuration.
  - Behavior: When a synonym redirects, its results, pinned products, excluded products, and keyword settings will all match the keyword it is redirected to.
  - Conflict Resolution: If a synonym is added that conflicts with an existing keyword, you will be prompted to delete and migrate that keyword to the current one, effectively combining the synonym records.

Expiration:
  - Purpose: Set a specific date and time for the Managed Keyword to expire.
  - Use Case: Ideal for temporary promotions, events, or sale periods.

Force No Results:
  - Purpose: Block the keyword from returning any search results.
  - Configuration: Set this option to 'true'.

Select Region:
  - Purpose: Change the region associated with the keyword after its initial creation.

Result Options:
  - Purpose: Control which results are returned by the keyword.
  - Options:
    - Pinned + Search Results: Returns all configured pinned products (manually selected or via 'Pin By Product Filter') followed by standard search results.
    - Pinned Only: Forces the keyword to return exclusively the pinned products (manually selected or via 'Pin By Product Filter'), with no standard search results.
```

--------------------------------

### Search API Response Field Definitions

Source: https://docs.xgen.ai/v1/docs/search-function

Detailed definitions for each field within the search API's JSON response, explaining their purpose, data types, and any specific behaviors or deprecation statuses. This serves as a comprehensive guide to interpreting the search results and understanding the data returned.

```APIDOC
Search API Response Fields:

page (number):
  - Description: This is the current page of results, defaults to `0` unless pagination is used.

total_result (number):
  - Description: The total number of results available for the query.

cache_ttl_used (number):
  - Description: Returns the interval set for this query's cache expiration.

hrnn_n (number):
  - Description: The number of products that will be sorted by the primary prediction model if this is configured.

search_threshold_achieved (string):
  - Description: Deprecated.

behavior_id (string):
  - Description: The ID of the Search Engine that was used (behavior is the technical name for a Search Engine).

response_engine (string):
  - Description: This defines which engine supplied the results: DeepSearch, GenSearch, or HybridSearch.

is_from_cache (boolean):
  - Description: Whether or not the results came from the cache.

is_sorted_by_hrnn (boolean):
  - Description: Whether or not the results have been sorted by the primary prediction model.

is_keyword_config_applied (boolean):
  - Description: Boolean value if a keyword was matched and applied to this query.

is_ai_sorting_tried (boolean):
  - Description: Was there an attempt to sort the results by the primary prediction model.

is_neural (boolean):
  - Description: Boolean value that explains whether the request was intended to be DeepSearch or not.

is_cache_filter_applied (boolean):
  - Description: Deprecated.

is_url_redirect (boolean):
  - Description: Whether the result is a URL redirect or not.

products_list (array of objects):
  - Description: The list of products returned by the query, limited to the number of results specified.
  - Object Structure:
    - prod_code (string): Unique identifier for the product.
    - prod_name (string): Name of the product.
    - prod_price (number): Price of the product.
    - image (string): URL to the product's main image.

product_code_variant_mapping (object):
  - Description: A mapping of which variant specifically should be used for the product result.

reason (array):
  - Description: Deprecated.

search_term_matches (array):
  - Description: Deprecated.

user_data (object):
  - Description: Any relevant metadata about the user.

facet (object):
  - Description: The object that shows all facets available, including aggregations for various categories.
  - Object Structure:
    - aggregations (object): Contains various aggregation groups.
      - group (object): A grouping of facet categories.
        - color (object): Aggregation for product colors.
          - buckets (array of objects): List of color facet values and their counts.
            - doc_count (number): Number of products associated with this color.
            - key (string): The color value (e.g., "brown", "black").
        - is_in_stock (object): Aggregation for product stock status.
          - buckets (array of objects): List of stock status facet values and their counts.
            - doc_count (number): Number of products with this stock status.
            - key (string): The stock status value ("1" for in stock, "0" for out of stock).
        - type (object): Aggregation for product types.
          - buckets (array of objects): List of product type facet values and their counts.
            - doc_count (number): Number of products of this type.
            - key (string): The product type value (e.g., "dresses", "shoes").
```

--------------------------------

### Importing and Calling the Search Function

Source: https://docs.xgen.ai/v1/docs/search-function

Demonstrates how to import the `search` function from the SDK integration and call it with `query` and `options` parameters. This snippet illustrates the basic usage pattern for initiating a search operation.

```javascript
// Import the integration from the 'installation' step
import { integration } from './xgenSdkIntegration';
const { search } = integration;

search(query,options);
```

--------------------------------

### Perform Basic Product Search with XGEN AI

Source: https://docs.xgen.ai/v1/docs/search-function

Demonstrates how to perform a basic product search using the `search` function, retrieving products for a given query and deployment ID. It then iterates through the results to log product codes.

```JavaScript
// Get list of products for an element

const { products, total, page, facets } = await search('pants', { deploymentId: '3d8e3aa4-b1e9-4b1b-9ff6-ca4bc64806d0' });

// Console log prod_code of each product recommended

products.forEach(product => console.log(product.prod_code));
```

--------------------------------

### Search Function API Reference and Options

Source: https://docs.xgen.ai/v1/docs/search-function

Detailed API documentation for the `search()` function, including its signature, required parameters, and the comprehensive structure of the `SearchOptions` object. This section outlines all configurable aspects of a search query.

```APIDOC
search(query: string, options: SearchOptions)
  - Performs a search using the given query and returns the results.
  - Parameters:
    - query: string
      The search term that will be used to find relevant products.
    - options: SearchOptions (REQUIRED)
      Options used to control different settings within search.

SearchOptions Object:
  - deploymentId: string (REQUIRED)
    The deployment ID used for this search contains search engine settings and product filters, configurable within the platform.
  - page: number (Default: 0)
    The page number for the search results. Page numbers start at zero, with 60 products per page. Therefore, page 0 is the first page, page 1 the second, and so on.
  - pageSize: number (Default: 60)
    The amount of products that will be returned in the search result.
  - sortBy: string (Options: 'price', 'update_date')
    The product field that the results will be sorted by. This overrides any sorting done within the engine settings.
  - sortOrder: string (Options: 'asc', 'desc', Default: 'desc')
    The direction in which the sorting from `sortBy` will be applied.
  - context: object
    Dynamic filters change based on page context. The context object's key represents the variable in the filter, and its value substitutes that variable within the filter. Filters can be configured within the platform.
  - skipHistory: boolean (Default: false)
    If set to true, this query will not be added to the user's search history.
  - facets: boolean (Default: false)
    If set to true, the search response will contain all facets that have been configured within the product filter being used, along with the counts associated with each bucket.
  - autoRedirect: boolean (Default: true)
    If set to true, the page will automatically redirect to the given URL if a URL redirect keyword is searched.
```

```json
{
    "deploymentId": 1234,
    "page": 1,
    "context": {},
    "skipHistory": true,
    "facets": true
}
```

--------------------------------

### Implement Pagination for Product Search Results

Source: https://docs.xgen.ai/v1/docs/search-function

Illustrates how to retrieve subsequent pages of product search results by specifying the `page` option in the search parameters. This allows fetching additional sets of products beyond the initial results.

```JavaScript
// Get list of products for an element

const { products, total, page, facets } = await search('pants', { deploymentId: '3d8e3aa4-b1e9-4b1b-9ff6-ca4bc64806d0', page: 1 });

// Console log prod_code of each product recommended

products.forEach(product => console.log(product.prod_code));
```

--------------------------------

### Define pdpProduct Value Assignment Syntax

Source: https://docs.xgen.ai/v1/docs/pdpproduct

Illustrates the various accepted syntaxes for defining the `pdpProduct` value, including direct string assignment, synchronous function, and asynchronous function. The prediction API processes these definitions to identify the current product.

```JavaScript
pdpProduct: pdpProductCode
pdpProduct: () => pdpProductCode
pdpProduct: async () => pdpProductCode
```

--------------------------------

### Perform Contextual Product Search with XGEN AI

Source: https://docs.xgen.ai/v1/docs/search-function

Shows how to include a `context` object in the search parameters to refine product searches based on specific attributes like gender and category. This enables dynamic filtering of search results.

```JavaScript
const context = {
  gender: 'male',
  category: 'pants'
}

// Get list of products for an element
const { products, total, page, facets } = await search('jeans', { deploymentId: '3d8e3aa4-b1e9-4b1b-9ff6-ca4bc64806d0', context });
```

--------------------------------

### Understanding the Product Facet Object Structure

Source: https://docs.xgen.ai/v1/docs/search-function

Describes the structure of the `facet` object returned by the Product Filter, including its nested components like aggregations, groups, buckets, and document references, along with associated metadata.

```APIDOC
facet object:
  aggregations: The overall facet object
  group: A group of facets, which is the object that can be nested and which contains buckets
  buckets: A bucket is an array of potential options associated with a field (for example, a facet of “color” could have “red,” “green,” and “blue” as buckets
  doc: A single product is referred to as a “doc” within the response

Metadata:
  doc_count_error_upper_bound: Metadata related to any direct query errors in relation to faceting
  sum_other_doc_count: The number of products that were affected by errors
```

--------------------------------

### Asynchronously Process User Search History

Source: https://docs.xgen.ai/v1/docs/search-history

Demonstrates how to asynchronously retrieve the user's search history and then iterate through the returned array to log each search query to the console.

```javascript
const history = await getSearchHistory();

history.forEach(console.log);
```

--------------------------------

### Configure Element Hook with CSS Selector

Source: https://docs.xgen.ai/v1/docs/search-experiences

Illustrates how to use a CSS selector to define the target element in the DOM where an XSearch experience will be placed. The experience can then replace, or be placed above or below, the content of the targeted element.

```CSS
.searchSection
```

--------------------------------

### Assign pdpProduct with an Asynchronous Function

Source: https://docs.xgen.ai/v1/docs/pdpproduct

Illustrates using an asynchronous function for `pdpProduct` to fetch the product code from an API or perform other asynchronous operations. The prediction API will await the function's resolution, and the returned value will be used as the product code.

```JavaScript
pdpProduct: async () => {
  const pdpItem = fetch('/product').then(r => r.json());
  return pdpItem.id;
}
```

--------------------------------

### Assign pdpProduct with a String Literal

Source: https://docs.xgen.ai/v1/docs/pdpproduct

Demonstrates the simplest way to set the `pdpProduct` value by directly assigning a string literal representing the product code. This method is suitable when the product code is static or readily available.

```JavaScript
pdpProduct: 'abc123'
```

--------------------------------

### Configure XGen Type-to-Search Settings and Triggers

Source: https://docs.xgen.ai/v1/docs/search-experiences

Defines various settings and triggers for controlling the type-to-search behavior within XGen elements, including debounce time, API selection, and activation conditions based on user input. These settings are primarily used by the `getTypeToSearch` function within the elements' JavaScript.

```APIDOC
Type-to-Search Configuration:

General Settings:
  No Type to Search (boolean)
    - When this setting is enabled, there will be no search results as the user is typing.

  Enable Type to Search (boolean)
    - This will enable the type-to-search functionality within experiences.
    - This setting will also utilize XGen's type-to-search API which uses a faster version of DeepSearch.
    - You can select a trigger to define exactly when this functionality kicks in.

  Switch to Primary Search (boolean)
    - Instead of using the type-to-search API, type-to-search can be configured to use XGen's primary search API instead.
    - You can utilize triggers to define when primary search will kick in, or you can configure it to always use primary search.

  Debounce Time (number)
    - The debounce time is the amount of time required in between user actions in order for the search API to be called.
    - Example: If debounce is 150ms, when a user types a character, a 150ms timer starts. If another character is typed before the timer ends, the timer resets. The search API is called only when the timer completes without further input.
    - Debounce optimizes the API by preventing unnecessary requests, decreasing network load and API load, resulting in a faster user experience.

Type-to-Search Triggers:
  (Note: Any numerical values are 'greater than or equal to'.)

  No Trigger (boolean)
    - The setting will be activated as soon as the user starts typing.

  Character Count (number)
    - The setting will be activated as soon as the user types a query with that many characters.

  Word Count (number)
    - The setting will be activated once the user types a query with that many words.
    - A word is counted by groups of characters separated by white space. E.g., “red p” and “red pants” are two words, but “red “ (with trailing space) is one word.

  Key Input (boolean)
    - The setting will be activated once the user types one of the designated keys while the search input is selected.
```

--------------------------------

### Assign pdpProduct with a Synchronous Function

Source: https://docs.xgen.ai/v1/docs/pdpproduct

Shows how to assign `pdpProduct` to a synchronous arrow function that returns the product code. The function is executed at runtime, and its return value is used as the product identifier. This is useful for dynamic product codes derived synchronously.

```JavaScript
pdpProduct: () => 'abc123'
```

--------------------------------

### Define onPageMatched Function Syntax in JavaScript

Source: https://docs.xgen.ai/v1/docs/onpagematched

This snippet presents the standard synchronous and asynchronous arrow function syntax for defining the `onPageMatched` callback. It highlights that the function can be declared as `async` to handle asynchronous operations, which will be awaited before the page renders.

```JavaScript
onPageMatched: () => {}
onPageMatched: async () => {}
```

--------------------------------

### Product Catalog Field Mapping Schema

Source: https://docs.xgen.ai/v1/docs/product-catalog-mapping

This schema defines the standard and custom fields available for mapping product data in the catalog. It includes various data types like strings, arrays, integers, and booleans, allowing for flexible integration of product attributes. Custom fields provide extensibility without altering the core structure, enabling the addition of bespoke attributes as needed.

```APIDOC
prod_name: 'string',
prod_code: 'string',
link: 'string',
price: 'price_string',
sale_price: 'price_string',
is_on_sale: 'int_bool',
category: 'string',
categories: 'array_of_strings',
sub_collection: 'string',
sub_collections: 'array_of_strings',
type: 'string',
types: 'array_of_strings',
tag: 'string',
tags: 'array_of_strings',
variants: 'array_of_objects',
is_in_stock: 'int_bool',
sku: 'string',
image: 'string',
image_alt: 'string',
images: 'array_of_strings',
quantity: 'integer',
gender: 'string',
color: 'string',
size: 'string',
currency: 'string',
currency_symbol: 'string',
custom_string_1: 'string',
custom_string_2: 'string',
custom_string_3: 'string',
custom_string_4: 'string',
custom_string_5: 'string',
custom_string_6: 'string',
custom_string_7: 'string',
custom_string_8: 'string',
custom_string_9: 'string',
custom_string_10: 'string',
custom_array_1: 'array',
custom_array_2: 'array',
custom_array_3: 'array',
custom_array_4: 'array',
custom_array_5: 'array',
custom_array_6: 'array',
custom_array_7: 'array',
custom_array_8: 'array',
custom_array_9: 'array',
custom_array_10: 'array',
custom_int_1: 'integer',
custom_int_2: 'integer',
custom_int_3: 'integer',
custom_int_4: 'integer',
custom_int_5: 'integer'
```
Tokens:
Raw