Interface Description
api.v2.personalization
Copyright ©
Mindbreeze GmbH, A-4020 Linz. 2023.
All rights reserved. All hardware and software names are brand names and/or trademarks of their respective manufacturers.
These documents are strictly confidential. The submission and presentation of these documents does not confer any rights to our software, our services and service outcomes or other protected rights.
The dissemination, publication or reproduction hereof is prohibited.
For ease of readability, gender differentiation has been waived. Corresponding terms and definitions apply within the meaning and intent of the equal treatment principle for both sexes.
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:
Reading the data logged with api.v2.personalization in app.telemetry | |
Setting up personalization in the default Mindbreeze InSpire search client |
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.action_trigger_event
Is used to pass the event that triggered the action. Example: „MOUSE_LEFT_CLICK “.
Type: String
query_result.options_json
Can be used to display additional information of an action in the app.telemetry.
Type: Object as a string.
query_result.title
The title of the document (title Property).
Type: String
query_result.url
The URL of the document (url Property).
Type: String
query_result.comment
Can be used to log user comments on a document. Is displayed in the app.telemetry in the column “Comment”.
query_answer.weight
Can be used to communicate positive or negative user feedback (upvote or downvote). (Floating point number) Usually the values are between -1.0 (= downvote) and 1.0 (= upvote). This is displayed in the app.telemetry in the "Weight" column.
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.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.application_id
To uniquely identify an Insight App.
Default value: "Default Application"
Type: String
query_result.query_context.query_trigger_action
Indicates how the search was triggered.
Example: "submit"
Type: String
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".
query_result.query_context.properties
An array of JSON objects with key-value pairs to log custom properties in app.telemetry. Displayed in 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 "Custom Property 1" and "Custom Property 2" columns in app.telemetry:
"properties": [
{
"key": "resultcount",
"value": "534"
},
{
"key": "language",
"value": "de-AT"
}
]
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.
query_answer
This JSON object describes the user actions associated with a response. The members that can be set for this JSON object are described in the following subsections.
query_answer.action
The operation that the user has performed. Displayed in capital letters in the app.telemetry in the "Operation" column..
query_answer.action_trigger_event
Used to pass the event that triggered the action. Example: “MOUSE_LEFT_CLICK“.
Type: String
query_answer.options_json
Can be used to display additional information of an action in the app.telemetry.
Type: Object as String
query_answer.title
The title of the document belonging to the answer (title Property).
Type: String
query_answer.url
The URL of the document belonging to the response (url Property).
Type: String
query_answer.comment
Can be used to log user comments on the respective response. Displayed in the app.telemetry in the "Comment" column.
query_answer.duration_in_ms
The duration of the user action in milliseconds (e.g. if the user had a preview of the document open for a certain time and then closes it). Displayed in the app.telemetry in the "Duration (ms)" column.
query_answer.fqcategory
The fqcategory (Full Qualified Category) of the document belonging to the response that was involved in the user action. Displayed in the app.telemetry in the "FQCategory" column.
query_answer.weight
Can be used to communicate positive or negative user feedback (upvote or downvote). (Floating point number) Usually values are between -1.0 (downvote) and 1.0 (upvote). Displayed in the app.telemetry in the "Weight" column.
query_answer.answer
This JSON object describes the response itself. The following subsections discuss the members of this JSON object.
query_answer.answer.text
The text of the answer. Displayed in the app.telemetry in the "Answer Text" column.
query_answer.answer.property_name
The name of the property from the document from which the answer was generated. Displayed in the app.telemetry in the “Answer Property” column..
query_answer.answer.text_start_pos
The position of the answer in the associated document. (Integer) Displayed in the app.telemetry in the Answer Start Position column.
query_answer.similarity_score
Floating point value that reflects the quality of the response. It is displayed in the app.telemetry in the column "Similarity Score".
query_answer.key
The key (datasource/mes:key) of the document associated with the response that was involved in the user action. Displayed in the app.telemetry in the "Key" column.
query_answer.position
The result-position of the response that was involved in the user action. Note that the first response has position 0, which would make the tenth response position 9, for example. Displayed in the app.telemetry in the "Result Position" column.
query_answer.query_context
This JSON object describes the context of the search query. The following subsections discuss the members of this JSON object.
Note: You can also send the query context with the search query.
query_answer.query_context.application_id
To uniquely identify an Insight App.
Default: "Default Application"
Type: String
query_answer.query_context.query_trigger_action
Specifies how the search was triggered.
Example: "submit"
Type: String
query_answer.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 query (e.g. in JavaScript using new Date().getTime()). Displayed in the app.telemetry in the "Query ID" column.
query_answer.query_context.prev_query_id
This is the query_id that was set in the previous query. Displayed in the app.telemetry in the "Previous Query ID" column..
query_answer.query_context.refinement_id
The ID of the search query where filters (= facets) were changed (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()). This is displayed in the app.telemetry in the column "Refinement ID".
query_answer.query_context.prev_refinement_id
This is the refinement_id that was set in the previous query. It is displayed in the app.telemetry in the "Previous Refinement ID" column..
query_answer.query_context.properties
An array of JSON objects with key-value pairs to log custom properties in app.telemetry. It is displayed in the app.telemetry in the columns "Custom Property 1" to "Custom Property 10". Therefore, a maximum of 10 custom properties can be added.
The following example shows how to set the resultcount and language properties in the "Custom Property 1" and "Custom Property 2" columns in app.telemetry:
"properties": [
{
"key": "resultcount",
"value": "534"
},
{
"key": "language",
"value": "de-AT"
}
]
query_answer.scroll_position_in_percentage
The scroll position in the browser. Can be used, for example, in the close-action of a preview window to keep track of how far a user has scrolled down in the preview window. Values between 0 and 100 are valid. It is displayed in the app.telemetry in the column "Scroll position (%)".
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 query_result
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/"
}
}
Example query_answer
The following example illustrates the request format described above.
Header
Content-Type: application/json
Body
{
"query_answer": {
"action": "vote",
"weight": 1,
"url": "smb://companyfileshare/Configuration - Google Drive Connector.pdf",
"action_trigger_event": "MOUSE_LEFT_BUTTON",
"query_context": {
"query_id": "1688131765487",
"app_tab_id": "Everything",
"prev_query_id": "1688131765383",
"query_trigger_type": "AUTOMATIC",
"application_id": "Default Application",
"query_trigger_action": "queryURLParameter"
},
"result_id": "aHR0cHM6Ly9pbnNwaXJlLm1pbmRicmVlemUuY29tOjg0NDMvand0L3JlYWxtL21hc3Rlci9hcGkvdjEvcXVlcnkvMjMzMDE6NTgy",
"position": 0,
"fqcategory": "Microsoft File:/companyfileshare/configuration",
"key": "smb://companyfileshare/Configuration - Google Drive Connector.pdf",
"title": "Configuration - Google Drive Connector.pdf",
"comment": "",
"answer": {
"text": "“Exclude Filename Pattern“ If the filename of a document matches this \r\nregular expression, the document is ignored.",
"property_name": "content",
"context_before": "Example: application/vnd\\.google\\-\r\napps.* ignores all Google Docs documents.\r\n",
"context_after": " \r\nFor example: .*\\.zip ignores all ZIP archives.",
"text_start_pos": 16703
},
"similarity_score": 0.3604826331138611
},
"user_context": {
"referer": "https://inspire.mindbreeze.com/apps/client/?query=How%20to%20exclude%20Documents%3F",
"locale": "de-DE",
"service_id": "https://inspire.mindbreeze.com/apps/scripts/../../api/v2/",
"utc_time_zone_differential_in_seconds": 7200,
"service_url": "https://inspire.mindbreeze.com/apps/scripts/../../api/v2/personalization"
}
}