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 event types 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.

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 /federated-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. This is similar to 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 may 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 project A.
const resultsFromProjectA = {
  results: [
    // ...
  ],
  tracking: {
    searchCode: '',
    // ...
  },
}
// Call to search for project B.
const resultsFromProjectB = {
  results: [
    {
      id: 1,
      tracking: {
        externalCode: '',
        // ...
      },
    },
    // ...
  ],
  // ...
}

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: resultsFromProjectA.tracking.searchCode,
  externalCode: resultsFromProjectB.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: resultsFromProjectB.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.