Developers

API Tracking Guidelines

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.

Log type
(Atomic)
Data key
(Session)
Action
- START Marks the start of the session.
- USER_BROWSER Stores the browser information of the user.
- USER_INFO Stores the user information in session.
- CONTACT_START Indicates a user started filling a contact form, converting the session in a contact session.
- CONTACT_SUBMIT Indicates a user clicked submit on a contact form. (This does not mean the form was submitted.)
- CONTACT_TICKET Indicates a user created a ticket and is being forwarded to another channel.
- MY_CUSTOM_KEY Custom data key to track customer events.
SEARCH SEARCH Indicates the user performed a search.
MATCH CLICK_MATCH Indicates a user clicked on a result.
INSTANT_MATCH INSTANT_CLICK Indicates a user clicked on an instant result, meaning a result resulting from an instant search.
CONTACT_MATCH CONTACT_CLICK Indicates a user clicked on a suggested content provided within a deflection tool.
INSTANT_SEARCH INSTANT_SEARCH Indicates the user triggered an automatic partial search while typing in the search box, without pressing ENTER or clicking “Search”.
CONTACT_SEARCH CONTACT_SEARCH Indicates the user triggered an automatic partial search while typing in a contact form. 
AUTOCOMPLETER CLICK_AUTOCOMPLETER Indicates a user clicked on a content suggested with the autocompleter.
- USER_QUESTION_CLICK Indicates a user clicked on a user question.
RATING RATE_CONTENT Indicates a user submitted a rating evaluating a specific content.
SEARCH_RATE RATE_SEARCH Indicates a user submitted a rating evaluating the results of a search.
KNOWLEDGE_BASE KNOWLEDGE_BASE Indicates the user retrieved all contents from the Knowledge Base.
KNOWLEDGE_BASE_MATCH CLICK_KNOWLEDGE_BASE Indicates a user clicked on a content obtained from the Knowledge Base, without performing any query

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).

Priority level Data Key
1 (highest) CONTACT_TICKET
2 CONTACT_CLICK
3 CONTACT_SUBMIT
4 CONTACT_SEARCH
5 CONTACT_START
6 CLICK_MATCH
6 CLICK_KNOWLEDGE_BASE
7 INSTANT_CLICK
8 CLICK_AUTOCOMPLETER
9 SEARCH
10 INSTANT_SEARCH
11 (lowest) START
11 KNOWLEDGE_BASE
0 (no priority) USER_INFO
0 USER_BROWSER
0 RATE_CONTENT
0 RATE_SEARCH
(custom) CUSTOM

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

Note

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

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, 
 }
)
 
Caution

No clicks are tracked on instance B with the above method. However, it is possible to manually track a click in instance B too, using the following code:

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

To track external clicks, configure an External Matching type in your Search application from Settings > External Matchings. The External Matching type must be the name of the external instance in uppercase. (e.g. using the scenario above, with an external instance called instance_b, the External Matching is INSTANCE_B).