Developers

API Tracking Guidelines

Knowledge Tracking Actions

The Knowledge 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 Knowledge 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. Recommended for the semantic autocompleter.
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”. Recommended for the semantic autocompleter.
CONTACT_SEARCH CONTACT_SEARCH Indicates the user trigggered a partial search while typing in a contact form. 
CATEGORY CLICK_CATEGORY Indicates a user clicked on a content after navigating to it through categories.
PUSH CLICK_PUSH Indicates a user clicked on a push content
POPULAR CLICK_POPULAR Indicates a user clicked on a popular content
CONTENT CLICK_CONTENT Indicates a user reached a page that contains a content, for instance with a link.
AUTOCOMPLETER CLICK_AUTOCOMPLETER Indicates a user clicked on a content suggested with the autocompleter.
RELATED CLICK_RELATED Indicates a user clicked on a related content.
CHAINED CLICK_CHAINED Indicates a user clicked on content within a decision tree.
- USER_QUESTION_CLICK Indicates a user clicked on a user question.
CROSS-SELLING CLICK_CROSS_SELLING Indicates a user clicked on a cross selling.
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.
CROSS_SELLING DISPLAY_CROSS_SELLING Indicates a cross selling is displayed and can be clicked by the user.

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
CONTACT_SUBMIT
CONTACT_START
3 CLICK_MATCH
INSTANT_CLICK
4 CLICK_CATEGORY
5 CLICK_PUSH
6 CLICK_POPULAR
CLICK_CONTENT
CLICK_AUTOCOMPLETER
7 CLICK_RELATED
CLICK_CHAINED
8 CLICK_CROSSSELLING
USER_QUESTION_CLICK
9 SEARCH
INSTANT_SEARCH
10 (lowest) START
0 (no priority) USER_INFO
USER_BROWSER
RATE_CONTENT
RATE_SEARCH
DISPLAY_CROSS_SELLING
(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 Parameter and Tracking Endpoints

 
Note

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

The Knowledge 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 Knowledge API tracks atomic data automatically. This means that the tracking parameter is set to true by default in all the endpoints. 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 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 pass the codeparameter 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 Knowledge instance) 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 and autocomplete searches, you must configure it so that each time such a 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 autocomplete 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 track 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 events.

First, you have to configure an External matching type in your Knowledge instance from Settings > External matchings. The External matching type must be the name of the external instance in uppercase. (for example, if the external instance is called instance_b, the External matching type should be called INSTANCE_B). After configuring the External matching type, publish the changes in the instance to Test or Production.

To track clicks from the external instance in your instance, use the /inbtrck/events endpoint with the event type external_click, which needs two codes: searchCode and externalCode. You can obtain those codes from the response of the /search endpoint in the external instance.

Example

Given the following results from two searches applied to two different instances A and B:

// Call to search for instance A.
const resultsFromInstanceA = {
    results: [
        // ...
    ],
    tracking: {
        searchCode: '',
            // ...
        },
    }
// Call to search for instance B.

const resultsFromInstanceB = {
    results: [
        {
            id: 1,
            // ...
            tracking: {
                externalCode: '',
                // ...
            },
        },
        // ...
    ],
    // ...
}

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

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