Search Tracking Actions

The Search API can track all the actions listed in the table below. Each action is associated with an atomic log, a session log or both (See Actions). This determines where this information will be available in the Dashboard section of the Search instance. Session log data is presented in the Dashboard section, Atomic log data is not.

Atomic log actions are listed according to a log type. Session log actions use data keys. This table shows all log types and data keys that come predefined in a new instance.

If an action has a log type, it can be tracked in Atomic logs. If it has a Data key, it can be tracked in Session logs. If it has both, it can be tracked in both.

Data keys

A data key also has a priority level that is given to its action. The session reports use the priority of an action to decide the most important action performed by the user. This most important action becomes the result of the session.

Example: If a user performs a search and sends a ticket, the result of the session will be that a ticket was sent. This is because the CONTACT_TICKET data key, as shown in the table below, has a higher priority (1) than the SEARCH data key (9).

Custom keys

All projects have a set of data keys defined by default, but it is possible to create new data keys to log custom actions. If you need custom data keys, contact your Inbenta representative.

Tracking Endpoints

The Search API tracks atomic data by default. However, in order to track session data, you must create a session and explicitly track the desired event data in order to get the relevant data reports.

The Search API tracks atomic data automatically. However, 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 /tracking/events endpoint.

Example

The /search endpoint automatically tracks the SEARCH action in both atomic and session logs if 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 pass the code parameter set as the clickCode obtained in the result.

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. Call the /tracking/events endpoint with the rate type and pass a data object. This data object should contain the rateCode you get from the content, a value (the id of the rating in the Search application) 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 type.

Tracking instant and autocomplete searches and answers

Instant answers are the answers that appear before the end user presses ENTER or clicks the “Search” icon/button. They appear as a result of an instant search, which is triggered when:

• An end user stops typing their search query for 2 seconds.
• An end user enters a special character that automatically triggers a search. Such characters can be .   ,   :   ;   (   )   ¿   ?   ¡   and   !
• An end user sees Typeahead/Semantic Autocomplete suggestions while they are typing their search query.

If you are using the SDK components InstantResults, Semantic Autocomplete and/or the Typeahead Autocomplete, the Search API automatically tracks the events INSTANT_SEARCH, CONTACT_SEARCH, INSTANT_CLICK, CLICK_AUTOCOMPLETER and CONTACT_CLICK. However, if you are not using these SDK components, you need to configure this behavior in your integration yourself.

Track instant searches

To make sure your API-only integration tracks instant searches, you must configure it so that each time an instant search is triggered, the Search API’s POST /federated-searches endpoint receives a request with the value instant in the type parameter.

This will ensure that instant searches are tracked as expected.

Track instant/autocompleter clicks

To make sure your API-only integration tracks all clicks on instant search and autocompleter results, you must configure it so that each time an end user clicks on such a result, the POST /tracking/events endpoint receives a request whose payload contains the clickCode value that is returned with the search results.

Tracking clicks from multiple instances

By default, all searches tracks matchings as internal results, because all results come from a single source, which is the knowledge base of the instance. However, if you set up your application to connect to other instances, this results in multiple sources. In this case, matchings from these other sources will be tracked as external.

If you need to track clicks from other instances, you can use the external_click event. It only needs two codes: the searchCode obtained from the response of the /search endpoint and an externalCode obtained from the content clicked from an external instance.

Example

// 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>', // ... 
    },
   },
   // ...
  ],
 // ...
}

To track a click on 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, 
 }
)

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