Concepts

The Recommend API provides real time personalized recommendations by analyzing live and past customers' behaviors. These behaviors are captured by integrating our Activity Tracking API or by using our JavaScript tag in a web context.

Hyper personalization

To benefit from hyper personalized recommendations, you must implement correctly the userId parameter in the request body to the Recommend API. If your are also using our Discovery API (and Activity Tracking API), the userId must be the identical between these API calls to personnalize the entire customer journey.

WARNING : the userId is not mandatory in the API calls to the Recommend API. However some algorithms (e.g.: the NextProductToBuy, PersonalInterest, or Selection algorithms) require it and will send back as a response an empty list of products if not provided.

Retrieving the User ID via the Tag

The Sensefuel tag enables you to integrate a plug-and-play product search and personalized recommendation solution into your e-commerce website. Additionally, it automatically handles user tracking to optimize algorithms and provide actionable analytical data.

In some situations, you may want to use our APIs to implement search functionality, manage product listings, or handle recommendations while still benefiting from the user tracking handled by our tag. Below, we explain how to retrieve the user ID generated by our tag and use it with our APIs.

Features of the Sensefuel Tag

The Sensefuel tracking tag provides several key features:

Compliance with GDPR regulations

Assignment of a unique user ID

Assignment of a session ID

Tracking of the purchase journey (searches, product listings views, product detail views, add-to-cart actions, order confirmations, etc.)

Retrieving the User ID

Accessing the Sensefuel JavaScript Interface

The user ID is accessible through a JavaScript interface exposed by the Sensefuel tag. This interface is available under the global variable window.sensefuel_a038457e.

To retrieve the user ID, use the following call:

Precaution

Before accessing this interface, ensure that the tag is fully loaded on the page. If you attempt to call it before the tag is available, retrieving the user ID will fail.

Using the User ID with Sensefuel APIs

We distinguish two cases for using the Sensefuel APIs:

Dynamic Client-side Calls (Client-side Rendering)

In this case, the API is dynamically called at runtime from the browser (either directly or via an intermediary server you control).

Wait for the window.sensefuel_a038457e interface to become available.

Retrieve the user ID:

Pass this user ID along to our Discovery or Recommend APIs.

Server-side Calls (Server-side Rendering)

For SEO and performance reasons, you may choose to call our APIs from the server to pre-render personalized content.

On the user's first page visit, no user ID will be available. The page can be generated without an ID.

Once the page is loaded, the Sensefuel tag automatically generates a user ID.

To pass this user ID to the server during subsequent visits, store it in a first-party cookie:

The server can then retrieve this cookie on every request or page load and use the user ID to call our APIs.

The first-party cookie setup code provided is indicative, and you may adjust the path, SameSite, Expires, Domain, and other cookie options to comply with your cookie management policy (MDN Documentation).

User ID Updates

The Sensefuel tag may regenerate a new user ID in certain scenarios, such as when users refuse cookies under GDPR policies. In such cases:

A new user ID will be generated for every session.

Make sure to update the first-party cookie on each page load.

Static and Dynamic modes

You have 2 options for using the API : static mode and dynamic mode.

Static mode : This mode leverages back-office configurations for recommendations. In this case, a slotId parameter is required to match the pre-defined configurations in the back-office recommendation section.

Dynamic mode : This mode allows you to bypass back-office configurations and directly specify the recommendation parameters within the API request. Here, you have to define the algorithm to use in the request body, along with any constraints to fine-tune the recommendation results.

Operations

This API is accessible over HTTPS at the entry point api.sensefuel.live/recommend. Two fields are required regardless of the mode :

site UUID : A unique identifier for the site, included as part of the URL.

API Key : A unique key that authenticates the API consumer.

These values can be found and managed in the Sensefuel back-office under Headless > Frontend integration > Recommend API > Set up.

Get Recommendations

Use this endpoint to retrieve personalized product recommendations for users based on configured algorithms or dynamic parameters.

Request

Header Parameters

Parameter	Required	Content
`X-API-KEY`	Yes	Your dedicated API key.
`Content-Type`	Yes	Only 'application/json' is supported.

Path Parameters

Parameter	Required	Content
`siteUUID`	Yes	Your dedicated site UUID.

Request body schema (Json)

Parameter	Required	Content
`slotId`	Yes (in static mode)	ID of the slot corresponding to the zone where the recommended products are displayed.
`algorithm`	Yes (in dynamic mode)	Chosen algorithm. One of : • CROSS_SELLING • CROSS_VISIT • NEXT_PRODUCT • SEMANTIC_SIMILARITY • SELECTION • PERSONAL_INTEREST
`productURL`	Yes (on a product page)	URL of current visited product.
`userId`	No	Identifier of current user, allowing to personalize results.
`storeId`	No	Applies query to a specific seller/dealer/store.
`constraints`	No	In dynamic mode, allows to fine-tune the recommendation results.
`fields`	No	The products fields to return.
`selection`	No	The ID of the products selection within which to look for the recommended products.
`size`	No	In dynamic mode, the number of recommended products to return. Default: 10.
`segments`	No	List of user segmentation criteria used to pick the right slot config.

Samples

Static mode with the store identifier:

Static mode with the fields to return:

Static mode with targeting:

Dynamic mode:

Dynamic mode with a constraint on the brand:

Response

Response status codes

Status code	Description
`200`	Products to be recommended were retrieved and returned
`204`	No recommendation configuration can be applied for this request
`400`	Invalid request (e.g.: in dynamic mode, provided algorithm is unknown)
`401`	Access denied (missing or invalid API key)
`403`	The requested algorithm is not activated for the client
`404`	In static mode, slot not found
`500`	Technical error

Response body schema

The response body follows this JSON structure:

{
    "products": [
        {
            "item_group_id": "string",
            "id": "string",
            "title": "string",
            "price": "number",
            "brand": "string",
            "description": "string",
            "availability": "string",
            "sf:variants": [
                {
                    "link": "string",
                    "id": "string",
                    "image_link": "string",
                    "availability": "string",
                    "color": "string"
                }
            ]
        }
    ],
    "layout": {
        "titleAlignment": "string",
        "titleColor": "string",
        "backgroundColor": "string",
        "backgroundTitle": "string",
        "templateType": "string"
    },
    "details": {
        "configId": "string",
        "slotId": "string",
        "source": "string"
    }
}

The response contains three main sections:

products: an array of formatted items returned by the recommendation engine with dynamic attributes (id, title, price, availability, etc.).

layout (optional): this object providing visual display parameters (alignment, colors, template type) configured in the slot is only available in static mode.

details: this object contains metadata on the recommendations generation context. It contains the source of the data (catalog or offers), the identifier of the slot and the config used.

Samples

Dynamic mode:

{
    "products": [
        {
            "item_group_id": "PRODUCT_ID",
            "title": "PRODUCT_TITLE",
            "id": "CHOSEN_ARTICLE_ID",
            "price": 143,
            "brand": "PRODUCT_BRAND",
            "currency": "NOC",
            "is_new": true,
            "is_promo": false,
            "description": "PRODUCT_DESCR",
            "normal_price": 143,
            "link": "https://ARTICLE_URL",
            "image_link": "https://IMAGE_LINK.jpg",
            "availability": "in stock",
            "size": "CHOSEN_ARTICLE_SIZE",
            "color": "CHOSEN_ARTICLE_COLOR",
            "sf:variants": [
                {
                    "link": "https://ARTICLE_URL",
                    "id": "ARTICLE_ID",
                    "image_link": "https://ARTICLE_URL.jpg",
                    "availability": "in stock",
                    "size": "ARTICLE_SIZE",
                    "color": "ARTICLE_COLOR"
                },
                {
                    "link": "https://ARTICLE_URL",
                    "id": "ARTICLE_ID",
                    "image_link": "https://ARTICLE_URL.jpg",
                    "availability": "in stock",
                    "size": "ARTICLE_SIZE",
                    "color": "ARTICLE_COLOR"
                }
            ]
        },
        {
            "item_group_id": "SECOND_PRODUCT_ID",
            "title": "SECOND_PRODUCT_TITLE",
            "id": "CHOSEN_ARTICLE_ID",
            "price": 120,
            "brand": "SECOND_PRODUCT_BRAND",
            "currency": "NOC",
            "is_new": false,
            "is_promo": false,
            "description": "SECOND_PRODUCT_DESCR",
            "normal_price": 120,
            "link": "https://SECOND_PRODUCT_LINK",
            "image_link": "https://SECOND_PRODUCT_IMAGE_LINK.jpg",
            "availability": "in stock",
            "size": "SECOND_PRODUCT_SIZE",
            "color": "SECOND_PRODUCT_COLOR"
        }
    ]
}

Static mode - layout and details blocks are added:

{
    "products": [
        {
            "item_group_id": "PRODUCT_ID",
            "title": "PRODUCT_TITLE",
            "id": "ARTICLE_ID",
            "price": 120,
            "brand": "PRODUCT_BRAND",
            "currency": "NOC",
            "is_new": false,
            "is_promo": false,
            "description": "PRODUCT_DESCR",
            "normal_price": 120,
            "link": "https://PRODUCT_LINK",
            "image_link": "https://PRODUCT_IMAGE_LINK.jpg",
            "availability": "in stock",
            "size": "PRODUCT_SIZE",
            "color": "PRODUCT_COLOR"
        }
    ],
    "layout": {
        "titleAlignment": "SLOT_CONFIG_TITLE_ALIGNMENT",
        "titleColor": "SLOT_CONFIG_TITLE_COLOR",
        "backgroundColor": "SLOT_CONFIG_BACKGROUND_COLOR",
        "backgroundTitle": "SLOT_CONFIG_BACKGROUND_TITLE",
        "templateType": "SLOT_CONFIG_TEMPLATE_TYPE"
    },
    "details": {
        "configId": "SLOT_CONFIG_ID",
        "slotId": "SLOT_IDENTIFIER",
        "source": "offers" // offers OR catalog
    }
}

Error special cases:

Some errors can occur while processing the products recommendation request. In those cases, the request end up with a 200 status response with an empty recommended products list. Here are the cases:

Forbidden use of the algorithm: the conditions required for the usage of the current recommenation algorithm are not met.
Example: In the case of the SemanticSimilarity algorithm, the search2vec feature was not activated for the last indexation.

No recommendation config found: No active configuration found from the slot. You need to check the activation conditions (dates, audiences, scopes) of the slot configurations.

No user profile found: no user profile data retrieved with the provided user id parameter or user profile is empty.

No items found in the cart: The user profile data is found but no items were added to the cart. This can happen when using the NextProductToBuy algorithm. You need to make sure that some articles are added to the user cart.

No visited items found: The user profile data is found but no items were visited by the user. This can occur when using the PersonalInterest algorithm.

No resolved vectors: The vector associated to the current product can not be found or computed.

Recommend API

Concepts#

Hyper personalization#

Retrieving the User ID via the Tag#

Features of the Sensefuel Tag#

Retrieving the User ID#

Accessing the Sensefuel JavaScript Interface#

Precaution#

Using the User ID with Sensefuel APIs#

Dynamic Client-side Calls (Client-side Rendering)#

Server-side Calls (Server-side Rendering)#

User ID Updates#

Static and Dynamic modes#

Operations#

Get Recommendations#

Request#

Header Parameters#

Path Parameters#

Request body schema (Json)#

Samples#

Response#

Response status codes#

Response body schema#

Samples#

Error special cases:#

Concepts

Hyper personalization

Retrieving the User ID via the Tag

Features of the Sensefuel Tag

Retrieving the User ID

Accessing the Sensefuel JavaScript Interface

Precaution

Using the User ID with Sensefuel APIs

Dynamic Client-side Calls (Client-side Rendering)

Server-side Calls (Server-side Rendering)

User ID Updates

Static and Dynamic modes

Operations

Get Recommendations

Request

Header Parameters

Path Parameters

Request body schema (Json)

Samples

Response

Response status codes

Response body schema

Samples

Error special cases: