General concepts

Objectives

Sensefuel provides a dedicated API for tracking user activity ("clickstream"). If you are not using the Sensefuel JavaScript tag on your website, or if you are integrating our solutions into a mobile app or any other non-web environment, implementing this API is mandatory.

This API ensures the proper functioning of the Sensefuel platform and delivers the full value expected by business teams. Specifically, it enables:

The generation of business performance dashboards available within the Sensefuel platform

Our AI to learn from user behavior

Real-time hyper-personalization of the customer journey

Operation

This API can be reached in HTTP (s) on the entry point api.search.sensefuel.live.
APIs are called with application authentication keys and entry point dedicated to Sensefuel API activity requests
(as described in the Sensefuel backend> Apis> Settings). This API must be called from your servers and not from your sites / applications directly.

Calls are made via the POST method. Query body and response are sent as JSON documents.
The HTTP response code makes it possible to follow the correct interpretation of the requests.

Session ID

Any new visit of a user requires the creation of a session via our API. This visit is then associated with a session identifier, returned by our API in the create response. Its storage and its lifespan are managed by yourself.

Identification of a user

For a given user, its multiple visits are associated with each other by a user identifier. This identifier may come from:

your own user identification system;

our tag if present on your site;

if not, an identifier will be generated during the creation of a session, which you must store.

Warning: this user identifier cannot contain any personal information.

Identification of a user path

The different visits of a user are also associated with each other by a path identifier.
This identifier makes it possible to produce cross statistics dedicated to the user path. The storage and the lifetime of this identifier are managed by yourself.

Warning: this user identifier cannot contain any personal information.

User Activity Tracking

To track a user's activity during their visit, all sent events require the session ID and user ID if possible.

For a given user in a given session, one or more events can be sent.
Since customization is calculated in real time, we invite you to send an event immediately after the action is completed.
The user ID also allows us to resume the custom profile from past visits.
Of course, this identifier must be used in your search queries using our dedicated API.

Once the session is created, the activity of a user is followed by the events described in our API.
An event is essentially determined by the following attributes:

location_name: context of the event;

namespace: object of the event;

type_id: action performed;

tag: description of the data to be attached with the event;

the data to be attached.

Only the {location_name, namespace, type_id, tag} tuples described in the Events section are allowed. New types of events are likely to be described in the future.

To have a GDPR compliant privacy policy, a user should not be tracked from session to session if he has not accepted it.
To implement this privacy policy with activityTrackingAPI, the storage of the userId must follow these two recommendations :

if the user has declined the GDPR policy, the userId should be stored to a non-persistent storage (eg: session storage). This userId can be used inside the session and the data can be tracked normally. When the user closes his browser or his application, the non-persistent storage is erased and userId is lost. A new connection to the application will generate another userId.

if the user has accepted the GDPR policy, the userId should be transfered from a non-persistent storage to a persistent storage (eg: local storage). When the user closes his browser/application and reopens it later, the userId should be reused to allow cross-session tracking and authorize our IA algorithms to perform optimally.

URLs associated with events

Products URLs, when supplied with events, must be present in the catalog feed data.

Session creation

Query

The body of the request to create a session is composed of the following elements:

required

Name	Description
timestamp	Session creation date (string ISO8601)

non-mandatory

Name	Description
track_id	session ID (string 256 characters max) if you managed one
user_agent	user agent of the user (string 1024 characters max) - if not, you should use one value from UserAgent section
ip_source	user IP address (string ipv4) - Not stored, it is hashed / salted and allows us to filter sessions likely to pollute the analyzes (bots, test tools, headquarters, callcenter, ...)
journey_id	user journey ID (string 256 characters max)
user_id	user ID (string 256 characters max)

If defined, track_id, journey_id and user_id will be sent back in call response.

If not defined, track_id, journey_id and user_id will be generated and sent back in call response.

Call example :

Response

The response is a JSON document that contains the following elements :

Name	Description
track_id	session ID (string 256 characters max)
journey_id	user journey ID if available (string 256 characters max)
user_id	user ID if available (string 256 characters max)
userState	Information set related to user_id (JSON object)
knownUser	true if we own enough information to personalize suggest actions from DiscoveryAPI (boolean)

The session ID, the journey ID and the user ID are to be stored by yourself.

The session ID has a limited lifetime that must be managed by yourself. Although dependent on the business context, we estimate that it usually expires 30 minutes after the last user event.

Likewise, the journey ID has a limited lifetime that must be managed by yourself. We estimate that it usually expires 24 hours after the last user event (so the last session).

Response example :

userState details

userState is a JSON object containing:

Name	Description
track_count	Tracks count since first visit (long)
frequency	mean time between two tracks, expressed in days (double)
last_buy_date	last buy date (string - iso 8601 date - optional)
last_buy_product_types	Lastly bought product types (values from g:product_type attribute), as map: <product_type>:<poids> (JSON object - optional)
track_delta_first	elapsed time since first visit, expressed in days (double)
known_universes	Product universe (first level from g:product_type) in which a user concern is detected, as map: <univers>:<probabilité> (JSON object)
known_leaves	product types (values from g:product_type attribute) in which a user concern is detected, as map: <product_type>:<probabilité> (JSON object)
client_profile	Information associated to user_id from UserTrackingAPI calls (JSON object)

Example with a defined session id

Call example :

Response example :

UserAgent

The UserAgent value is used to build an efficient device filtering in our analytics. We also take advantage of this information to detect some biases in activity tracking.
Your ActivityTrackingAPI implementation context may not allow you to provide a user agent.
If so, we invite you to send one of the following values from UserAgent column:

Device\Platform	Android	Apple	Windows	Linux
Mobile	android mobile	apple mobile	windows mobile	linux mobile
Tablet	android tablet	apple tablet	windows tablet	linux tablet
Desktop	android desktop	apple desktop	windows desktop	linux desktop

Sending a user's activity

A user activity is described by the following mandatory fields :

Name	Description
track_id	Session ID (string 256 characters max)	Associate all events in the same session
source	Description of the general context of the API use, eg : website, application (string 256 characters max)
version	Your application version
events	List of events describing a user's activity (array with 16 event descriptions max)

It can be completed by the following non-mandatory fields :

Name	Description
user_agent	user's user agent (string 1024 characters max)
user_id	user ID. If not present, session ID is used (string 256 characters max)

Event description

Definition

An event is defined by the following mandatory fields :

Name	Description
timestamp	Event date (string ISO8601)

An event can also be completed by the following non-mandatory fields:

Name	Description	Use at Sensefuel
current_page	URL of the current page, if available according to context (string 2083 caractères max)	We can identify biases in tracking

## URL description

Most events are associated with products or pages.
If it is a link to a product, by sending an array of links, we can then relate that event to the characteristics of the products concerned.

We limit the sending to 64 URLs in a single call.

A URL must contain the http or https protocol (see the Google Shopping recommendation here: https://support.google.com/merchants/answer/6324416?hl=en)

A link is described by:

Name	Description
link	URL (string 2083 characters max)

In the case of products, we expect to find its URL in product feed. If another URL is presented to the user, you must send both links:

Name	Description
link	Canonical URL (string 2083 characters max)
doc_link	URL of the product presented (string 2083 characters max)

## Breadcrumb description

A breadcrumb is a representation of the different levels of ventilation of a product.
It may differ from the one sent in the product feed.
It is therefore useful for better describing products and improving the relevance of the solution.
A breadcrumb is sent as an array allowing up to 10 levels of depth.

Each level has :

Name	Description
name	Level name
link	URL of the product presented (string 2083 characters max)

When sending, the levels must be ordered in the order of presentation of the breadcrumb.
Ideally, the first level describes the product universe.
If set, a "root" level such as "Home" must not be sent.

Events supported

First page visited

A beginning of visit requires the sending of a dedicated event:

location_name (string 256 characters max)	namespace (string 256 characters max)	type_id (string 256 characters max)	tag (string 256 characters max)	urls (array with 64 strings max of 2083 characters max)
startup_page	page	visited	page	URL of the current page

Sending example :

Page with a list of products

Activity on a product list page requires the following events to be sent:

location_name (string 256 characters max)	namespace (string 256 characters max)	type_id (string 256 characters max)	tag (string 256 characters max)	urls (array with 64 strings max of 2083 characters max)
product_listing	product	listed	product	URLs of displayed products
product_listing	product	inspected	product	URL of the product overflown
product_listing	product	clicked	product	URL of the product clicked
product_listing	cart	added	product	URL of the product added to the basket

It is not necessary to send all the products URLs from a list, only those actually displayed to the user (as far as possible).
On the other hand, if the user navigates in this list (pagination, scroll with lazy load) and sees other products, these products must be sent in a new event of type {product_listing, product, listed, product}.

Example of sending a product list:

Example of sending multiple events to the product list:

Page with a search result

A search results page can come from your pre-existing solution or sensefuel.
The engine that generates a search results page is described by delivery_mode and expects "legacy" values for your pre-existing solution or "sensefuel" if our search API is used.

Activity on such a page requires sending the following events:

location_name (string 256 characters max)	namespace (string 256 characters max)	type_id (string 256 characters max)	tag (string 256 characters max)	delivery_mode (string 256 characters max)	expression (string 256 characters max)	urls (array with 64 strings max of 2083 characters max)
search_listing	product	listed	product	legacy/sensefuel	search keywords	URLs of displayed products
search_listing	product	inspected	product	legacy/sensefuel	search keywords	URL of the product overflown
search_listing	product	clicked	product	legacy/sensefuel	search keywords	URL of the product clicked
search_listing	cart	added	product	legacy/sensefuel	search keywords	URL of the product added to basket

Example of sending a search result:

In case of empty search result, you must send an event with an empty urls array.

Product sheet visit

The activity on a product sheet requires the following events to be sent:

location_name (string 256 characters max)	namespace (string 256 characters max)	type_id (string 256 characters max)	tag (string 256 characters max)	urls (array with 64 strings max of 2083 characters max)
product_sheet	product	visited	product	URLs of displayed products
product_sheet	cart	added	product	URL of product added to basket

Example of sending a product sheet visit:

Basket validation

The activity on the basket validation page requires the sending of the following event during the validation of the basket:

location_name (string 256 characters max)	namespace (string 256 characters max)	type_id (string 256 characters max)	tag (string 256 characters max)	total (encodable number with IEEE 754-2008 binary64)
checkout	cart	confirmed	total	cart total value when validated

Example of sending a basket validation:

Documentation

General concepts#

Objectives#

Operation#

Session ID#

Identification of a user#

Identification of a user path#

User Activity Tracking#

GDPR compliant#

URLs associated with events#

Session creation#

Query#

Response#

userState details#

Example with a defined session id#

UserAgent#

Sending a user's activity#

Event description#

Definition#

Events supported#

First page visited#

Page with a list of products#

Page with a search result#

Product sheet visit#

Basket validation#