Schnittstellenbeschreibung

api.v2.personalization

Einleitung

Dieses Dokument beschäftigt sich mit der Mindbreeze Web API zum Analysieren des Userverhaltens. Die API ist dafür zuständig, Useraktionen in der app.telemetry aufzuzeichnen.

Bitte beachten Sie, dass diese API dafür vorgesehen ist, um Benutzeraktionen in den Suchresultaten zu analysieren, wie beispielsweise das Öffnen oder die Vorschau von Dokumenten oder Antworten. Wie Sie Suchanfragen mit der Mindbreeze Web API absetzen, können Sie in der api.v2.search Schnittstellenbeschreibung nachlesen.

Personalisierungs-Requests werden als HTTP POST-Request an ein Client Service gesendet. Der Pfad für Personalisierungs-Requests lautet: <Client Service URL>/api/v2/personalization.

Im Body des HTTP-Request wird ein JSON-Dokument mitgeschickt, das die Personalisierungs-Requests beschreibt.

In den folgenden Dokumentationen finden Sie weiter Informationen zur Personalisierung:

Felder im Personalisierungs-Requests

query_result

Dieses JSON-Objekt beschreibt die Benutzeraktionen, bezogen auf das Suchresultat. Welche Member bei diesem JSON-Objekt gesetzt werden können, wird in den folgenden Unterabschnitten beschrieben.

query_result.action

Die Operation, welche der User ausgeführt hat. Wird in Großbuchstaben in der app.telemetry in der Spalte „Operation“ angezeigt.

query_result.action_trigger_event

Wird verwendet, um das Event, welches die Aktion getriggert hat, zu übergeben. Beispiel: „MOUSE_LEFT_CLICK“.
Type: String

query_result.options_json

Kann dafür verwendet werden, um zusätzliche Informationen einer Aktion in der app.telemetry anzuzeigen.
Type: Objekt als String

query_result.title

Der Titel des Dokuments (title Property).
Type: String

query_result.url

Die URL des Dokuments (url Property).
Type: String

query_result.comment

Kann dafür verwendet werden, um Kommentare von Benutzern zum jeweiligen Dokument zu protokollieren. Wird in der app.telemetry in der Spalte „Comment“ angezeigt.

query_answer.weight

Kann dafür verwendet werden, um positives oder negatives Benutzer-Feedback (Upvote oder Downvote) zu kommunizieren. (Fließkommazahl) Üblicherweise liegen die Werte zwischen -1,0 (= Downvote) und 1,0 (= Upvote). Dies wird in der app.telemetry in der Spalte „Weight“ angezeigt.

query_result.duration_in_ms

Die Dauer der Benutzeraktion in Millisekunden (z.B. wenn der Benutzer eine Vorschau des Dokuments eine gewisse Zeit offen hatte und anschließend schließt). Wird in der app.telemetry in der Spalte „Duration (ms)“ angezeigt.

query_result.fqcategory

Die fqcategory (Full Qualified Category) des Dokuments, das bei der Benutzeraktion involviert war. Wird in der app.telemetry in der Spalte „FQCategory“ angezeigt.

query_result.key

Der Key (datasource/mes:key) des Dokuments, das bei der Benutzeraktion involviert war. Wird in der app.telemetry in der Spalte „Key“ angezeigt.

query_result.position

Die Ergebnisposition des Dokuments, das bei der Benutzeraktion involviert war. Beachten Sie, dass das erste Dokument die Position 0 hat, womit beispielsweise das zehnte Dokument die Position 9 hätte. Wird in der app.telemetry in der Spalte „Result Position“ angezeigt.

query_result.query_context

Dieses JSON-Objekt beschreibt den Kontext der Suchanfrage. In den folgenden Unterabschnitten wird auf die Member dieses JSON-Objekts eingegangen.

Anmerkung: Sie können den Query-Context auch schon bei der Suchanfrage mitschicken.

query_result.query_context.application_id

Zum eindeutigen Identifizieren einer Insight App.
Standardwert: "Default Application"
Type: String

query_result.query_context.query_trigger_action

Gibt an, wie die Suche getriggert wurde.
Beispiel: "submit"
Type: String

query_result.query_context.query_id

Die ID der Suchanfrage (als Zahl ohne Vorzeichen). Empfohlen wird, einen UTC Timestamp (Millisekunden seit 1. Jänner 1970, 00:00:00.000 GMT) der aktuellen Zeit der Suchanfrage zu setzten (z.B. in JavaScript mittels new Date().getTime()). Wird in der app.telemetry in der Spalte „Query ID“ angezeigt.

query_result.query_context.prev_query_id

Dies ist die query_id die bei der vorherigen Suchanfrage gesetzt wurde. Wird in der app.telemetry in der Spalte „Previous Query ID“ angezeigt.

query_result.query_context.refinement_id

Die ID der Suchanfrage, bei der Filter (= Facetten) geändert wurden (als Zahl ohne Vorzeichen). Empfohlen wird, einen UTC Timestamp (Millisekunden seit 1. Jänner 1970, 00:00:00.000 GMT) der aktuellen Zeit der Suchanfrage zu setzten (z.B. in JavaScript mittels new Date().getTime()). Wird in der app.telemetry in der Spalte „Refinement ID“ angezeigt.

query_result.query_context.prev_refinement_id

Dies ist die refinement_id die bei der vorherigen Suchanfrage gesetzt wurde. Wird in der app.telemetry in der Spalte „Previous Refinement ID“ angezeigt.

query_result.query_context.properties

Ein Array von JSON-Objekten mit Key-Value-Paaren, um Custom-Properties in der app.telemetry zu protokollieren. Wird in der app.telemetry in den Spalten „Custom Property 1“ bis „Custom Property 10” angezeigt. Somit können maximal 10 Custom Properties hinzugefügt werden.

Im folgenden Beispiel wird gezeigt, wie die Properties resultcount und language in der app.telemetry in den Spalten „Custom Property 1“ und „Custom Property 2“ gesetzt werden:

"properties": [

    {

        "key": "resultcount",

        "value": "534"

    },

    {

        "key": "language",

        "value": "de-AT"

    }

]

scroll_position_in_percentage

Die Scroll-Position im Browser. Kann z.B. bei der Close Action eines Vorschaufensters verwendet werden, um zu protokollieren, wie weit ein User im Vorschaufenster runtergescrollt hat. Werte zwischen 0 und 100 sind gültig. Wird in der app.telemetry in der Spalte „Scroll position (%)“ angezeigt.

query_answer

Dieses JSON-Objekt beschreibt die Benutzeraktionen, bezogen auf eine Antwort. Welche Member bei diesem JSON-Objekt gesetzt werden können, wird in den folgenden Unterabschnitten beschrieben.

query_answer.action

Die Operation, welche der User ausgeführt hat. Wird in Großbuchstaben in der app.telemetry in der Spalte „Operation“ angezeigt.

query_answer.action_trigger_event

Wird verwendet, um das Event, welches die Aktion getriggert hat, zu übergeben. Beispiel: „MOUSE_LEFT_CLICK“.
Type: String

query_answer.options_json

Kann dafür verwendet werden, um zusätzliche Informationen einer Aktion in der app.telemetry anzuzeigen.
Type: Objekt als String

query_answer.title

Der Titel des zur Antwort gehörenden Dokuments (title Property).
Type: String

query_answer.url

Die URL des zur Antwort gehörenden Dokuments (url Property).
Type: String

query_answer.comment

Kann dafür verwendet werden, um Kommentare von Benutzern zur jeweiligen Antwort zu protokollieren. Wird in der app.telemetry in der Spalte „Comment“ angezeigt.

query_answer.duration_in_ms

Die Dauer der Benutzeraktion in Millisekunden (z.B. wenn der Benutzer eine Vorschau des Dokuments eine gewisse Zeit offen hatte und anschließend schließt). Wird in der app.telemetry in der Spalte „Duration (ms)“ angezeigt.

query_answer.fqcategory

Die fqcategory (Full Qualified Category) des zur Antwort gehörenden Dokuments, das bei der Benutzeraktion involviert war. Wird in der app.telemetry in der Spalte „FQCategory“ angezeigt.

query_answer.weight

Kann dafür verwendet werden, um positives oder negatives Benutzer-Feedback (Upvote oder Downvote) zu kommunizieren. (Fließkommazahl) Üblicherweise liegen die Werte zwischen -1,0 (Downvote) und 1,0 (Upvote). Wird in der app.telemetry in der Spalte „Weight“ angezeigt.

query_answer.answer

Dieses JSON-Objekt beschreibt die Antwort selbst. In den folgenden Unterabschnitten wird auf die Member dieses JSON-Objekts eingegangen.

query_answer.answer.text

Der Text der Antwort. Wird in der app.telemetry in der Spalte „Answer Text“ angezeigt.

query_answer.answer.property_name

Der Name des Properties vom Dokument, aus dem die Antwort erzeugt wurde. Wird in der app.telemetry in der Spalte „Answer Property“ angezeigt.

query_answer.answer.text_start_pos

Die Position der Antwort im zugehörigen Dokument. (Ganzzahl) Wird in der app.telemetry in der Spalte „Answer Start Position“ angezeigt.

query_answer.similarity_score

Fließkomma-Wert, welche die Qualität der Antwort wiederspiegelt. Wird in der app.telemetry in der Spalte „Similarity Score“ angezeigt.

query_answer.key

Der Key (datasource/mes:key) des zur Antwort gehörenden Dokuments, das bei der Benutzeraktion involviert war. Wird in der app.telemetry in der Spalte „Key“ angezeigt.

query_answer.position

Die Ergebnisposition der Antwort, die bei der Benutzeraktion involviert war. Beachten Sie, dass die erste Antwort die Position 0 hat, womit beispielsweise die zehnte Antwort die Position 9 hätte. Wird in der app.telemetry in der Spalte „Result Position“ angezeigt.

query_answer.query_context

Dieses JSON-Objekt beschreibt den Kontext der Suchanfrage. In den folgenden Unterabschnitten wird auf die Member dieses JSON-Objekts eingegangen.

Anmerkung: Sie können den Query-Context auch schon bei der Suchanfrage mitschicken.

query_answer.query_context.application_id

Zum eindeutigen Identifizieren einer Insight App.
Standardwert: "Default Application"
Type: String

query_answer.query_context.query_trigger_action

Gibt an, wie die Suche getriggert wurde.
Beispiel: "submit"
Type: String

query_answer.query_context.query_id

Die ID der Suchanfrage (als Zahl ohne Vorzeichen). Empfohlen wird, einen UTC Timestamp (Millisekunden seit 1. Jänner 1970, 00:00:00.000 GMT) der aktuellen Zeit der Suchanfrage zu setzten (z.B. in JavaScript mittels new Date().getTime()). Wird in der app.telemetry in der Spalte „Query ID“ angezeigt.

query_answer.query_context.prev_query_id

Dies ist die query_id die bei der vorherigen Suchanfrage gesetzt wurde. Wird in der app.telemetry in der Spalte „Previous Query ID“ angezeigt.

query_answer.query_context.refinement_id

Die ID der Suchanfrage, bei der Filter (= Facetten) geändert wurden (als Zahl ohne Vorzeichen). Empfohlen wird, einen UTC Timestamp (Millisekunden seit 1. Jänner 1970, 00:00:00.000 GMT) der aktuellen Zeit der Suchanfrage zu setzten (z.B. in JavaScript mittels new Date().getTime()). Wird in der app.telemetry in der Spalte „Refinement ID“ angezeigt.

query_answer.query_context.prev_refinement_id

Dies ist die refinement_id, die bei der vorherigen Suchanfrage gesetzt wurde. Wird in der app.telemetry in der Spalte „Previous Refinement ID“ angezeigt.

query_answer.query_context.properties

Ein Array von JSON-Objekten mit Key-Value-Paaren, um Custom-Properties in der app.telemetry zu protokollieren. Wird in der app.telemetry in den Spalten „Custom Property 1“ bis „Custom Property 10” angezeigt. Somit können maximal 10 Custom Properties hinzugefügt werden.

Im folgenden Beispiel wird gezeigt, wie die Properties resultcount und language in der app.telemetry in den Spalten „Custom Property 1“ und „Custom Property 2“ gesetzt werden:

"properties": [

    {

        "key": "resultcount",

        "value": "534"

    },

    {

        "key": "language",

        "value": "de-AT"

    }

]

query_answer.scroll_position_in_percentage

Die Scroll-Position im Browser. Kann z.B. bei der Close Action eines Vorschaufensters verwendet werden, um zu protokollieren, wie weit ein User im Vorschaufenster runtergescrollt hat. Werte zwischen 0 und 100 sind gültig. Wird in der app.telemetry in der Spalte „Scroll position (%)“ angezeigt.

user_context

Dieses JSON-Objekt beschreibt den Kontext des Benutzers. In den folgenden Unterabschnitten wird auf die Member dieses JSON-Objekts eingegangen.

Anmerkung: Sie können den Query-Context auch schon bei der Suchanfrage mittels api.v2.search mitschicken (z.B. für Sprache und Zeitzone).

user_context.referer

Dies ist die URL, auf der sich der Benutzer gerade befindet. Wird in der app.telemetry in den folgenden Spalten angezeigt:

• „Referer“: die gesamte URL
• „Referer Scheme“: das Schema der URL (http/https)
• „Referer Host“: der Hostname der URL
• „Referer Port“: der Port der URL (-1 wenn kein Port definiert wurde)
• „Referer Path“: der Pfad der URL

Beispiel query_result

Das folgende Beispiel veranschaulicht das oben beschriebene Request-Format.

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/"

    }

}

Beispiel query_answer

Das folgende Beispiel veranschaulicht das oben beschriebene Request-Format.

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"

    }

}