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.

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 Parameter and Tracking Endpoints

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

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