API Tracking Guidelines

Knowledge Tracking Actions

The Knowledge Management 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 Management App.

Atomic logs actions are listed according to a log type. Session logs 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.
CONTACT_MATCH CONTACT_CLICK Indicates a user clicked on a suggested content provided within a deflection tool.
INSTANT_SEARCH INSTANT_SEARCH Indicates the user started a partial search while typing in the search box.
CONTACT_SEARCH CONTACT_SEARCH Indicates the user started 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 Management 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 Management 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 Management 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 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

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

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