Interface Description

api.v2.personalization

Introduction

This document deals with the Mindbreeze Web API for analyzing user behavior. The API is responsible for recording user actions in the app.telemetry.

Please note that this API is designed to analyze user actions in the search results, such as opening or previewing documents. Information on how to perform searches with the Mindbreeze Web API can be found in the api.v2.search Interface Description.

Personalization requests are sent as HTTP POST requests to a client service. The path for personalization requests is: <Client Service URL>/api/v2/personalization.

A JSON document that describes the personalization requests is sent with the body of the HTTP request.

You can find more information on personalization in the following documentation:

Fields in Personalization Requests

query_result

This JSON object describes the user actions related to the search result. Which members can be set for this JSON object is described in the following subsections.

query_result.action

The operation performed by the user. Displayed in capital letters in the app.telemetry in the “Operation” column.

query_result.comment

Can be used to log user comments on a document. Is displayed in the app.telemetry in the column “Comment”.

query_result.duration_in_ms

The duration of the user action in milliseconds (for example, if the user had a preview of the document open for a certain time and then closed it). Displayed in the app.telemetry in the column “Duration (ms)”.

query_result.fqcategory

The fqcategory (Full Qualified Category) of the document that was involved in the user action. Appears in the app.telemetry in the “FQCategory” column.

query_result.key

The key (datasource/mes:key) of the document involved in the user action. Is displayed in the app.telemetry in the column “Key”.

query_result.position

The result position of the document that was involved in the user action. Note that the first document has the position 0, so for example the tenth document has the position 9. Is displayed in the app.telemetry in the column “Result Position”.

query_result.properties

An array of JSON objects with key-value pairs to log custom properties in app.telemetry. Displayed in the app.telemetry in the columns “Custom Property 1” to “Custom Property 10”. Thus, a maximum of 10 custom properties can be added.

The following example shows how to set the resultcount and language properties in the app.telemetry in the columns “Custom Property 1” and “Custom Property 2”:

"properties": [

    {

        "key": "resultcount",

        "value": "534"

    },

    {

        "key": "language",

        "value": "de-AT"

    }

]

query_result.query_context

This JSON object describes the context of the search query. The following subsections describe the members of this JSON object.

Note: You can also send the query context with the search query.

query_result.query_context.query_id

The ID of the search query (as an unsigned number). It is recommended to set a UTC timestamp (milliseconds since January 1, 1970, 00:00:00.000 GMT) of the current time of the search query (e.g. in JavaScript using new Date().getTime()). Is displayed in the app.telemetry in the column “Query ID”.

query_result.query_context.prev_query_id

This is the query_id that was set in the previous query. Displayed in the app.telemetry in the column ”Previous Query ID”.

query_result.query_context. refinement_id

The ID of the search query in which filters (= facets) were changed (as unsigned numbers). It is recommended to set a UTC timestamp (milliseconds since January 1, 1970, 00:00:00.000 GMT) of the current time of the search query (e.g. in JavaScript using new Date().getTime()). Displayed in the app.telemetry in the column "Refinement ID".

query_result.query_context. prev_refinement_id

This is the refinement_id that was set in the previous query. Displayed in the app.telemetry in the column "Previous Refinement ID".

scroll_position_in_percentage

The scroll position in the browser. Can be used, for example, during the close action of a preview window to log how far a user has scrolled down in the preview window. Values between 0 and 100 are valid. Displayed in the app.telemetry in the “Scroll position (%)” column.

user_context

This JSON object describes the context of the user. The following subsections describe the members of this JSON object.

Note: You can also send the query context with the search query using api.v2.search (for example, for language and time zone).

user_context.referer

This is the URL where the user is currently located. Displayed in the app.telemetry in the following columns:

• "Referer": the entire URL
• "Referer Scheme": the scheme of the URL (http/https)
• "Referer Host": the host name of the URL.
• "Referer Port": the port of the URL (-1 if no port has been defined)
• "Referer Path: the path to the URL.

Example

The following example illustrates the request format described above.

Header

Content-Type: application/json

Body

{

    "query_result": {

        "query_context": {

            "query_id": "1552292350743",

            "properties": [

                {

                    "key": "resultcount",

                    "value": "534"

                },

                {

                    "key": "language",

                    "value": "de-AT"

                }

            ],

            "prev_query_id": "1552292349847"

        },

        "action": "preview",

        "position": 2,

        "weight": 0.5,

        "fqcategory": "Microsoft Exchange:Default",

        "key": "AQMkADU3YjMxNzg0LWE2OTQtNGQ3ZC1iZTFjLWJhMTc0Mzk1NGY4YwAuAAADooiUNxWDyEmjTSU5uGq 5gEAShd4IrQ/NU6YapRuM8OUPQAAAyIAAAA=@AQMkADU3YjMxNzg0LWE2OTQtNGQ3ZC1iZTFjLWJhMTc0Mzk1NGY4YwBGAAADooiUNxWDyEmjTSU5uGq 5gcAShd4IrQ/NU6YapRuM8OUPQAAAyIAAAAkKagZlMRnQ76P/8/misL4AAAAFm8giQAAAA==",

        "comment": ""

    },

    "user_context": {

        "referer": "https://inspire.mydomain.com/apps/client/"

    }

}