API Tracking Guidelines

Note: For a full list of trackable actions, see the API Routes section.

Note: Inbenta strongly recommends that you track as many actions as possible.

To track any data, make sure that you set the tracking parameter to true on the endpoints you want to track. This ensures that atomic data will be automatically logged. In order to track session data, you must get the sessionToken from the /tracking/session endpoint. Then, send this sessionToken in the x-inbenta-session header to track the actions in the session.

As long as you send this sessionToken, all actions are tracked in the same session. However, if there is no request to the API for 30 minutes, another session with the same sessionToken is created.

Certain actions cannot be logged automatically since they depend of the user interaction such as a click or a rate. You must track these actions explicitly with the the /tracking/events endpoint.

Example: The /search endpoint automatically tracks the SEARCH action in both atomic and session logs if the tracking parameter is set to true and the sessionToken is passed. However, when you want to track a click on one of the results you must use the /tracking/events endpoint with the parameter type set to click and click code obtained in the result.

To track when the content information is shown (for example, after a customer click in a content title), use clickCode inside the content. Use it to call a /tracking/events defined with a click type and a data object.

Finally, the user may rate the content, which is something you certainly may want to track. To track content ratings, use the rateCode inside the content. Use the code to call a /tracking/events defined with a rate type and a data object. This object will contain a code, a value (the id of the rating in the Backstage) and optionally the user's comment.

You can also track results ratings. It is the same as a content tracker, but with a search_rate event.

Tracking clicks from multiple instances

If you need to track clicks from multiple instances into another, you can use the external_click event. It only needs two codes: the searchCode from the main search, and a externalCode from contents of a different instance.

// Call to search for instance A.
const resultsFromInstanceA = {
 results: [
    // ...
  ],
  tracking: {
   searchCode: '<search_code>',
    // ...
  },
}
// Call to search for instance B.
const resultsFromInstanceB = {
  results: [
    {
     id: 1,
      // ...
      tracking: {
       externalCode: '<external_code>',
        // ...
      },
    },
    // ...
  ],
  // ...
}

Example:

To register a click to the result with ID 1 (from instance B) into the search of the instance A, use the following code:

clientA.track('external_click', {
 searchCode: resultsFromInstanceA.tracking.searchCode,
 externalCode: resultsFromInstanceB.results[0].tracking.externalCode,
})

Caution: No clicks are tracked on instance B with the above method. It is possible however to manually track instance B as well, using the following code:

clientB.track('click', {
 code: resultsFromInstanceB.results[0].tracking.clickCode,
})

Important: You should configure an external type inside the main instance in order to track the external click. The external type should be the name of the external instance in uppercase. In the example above, if the external instance is instance_b, the external type will be INSTANCE_B.