Schnittstellenbeschreibung
api.v2.personalization
Copyright ©
Mindbreeze GmbH, A-4020 Linz, 2023.
Alle Rechte vorbehalten. Alle verwendeten Hard- und Softwarenamen sind Handelsnamen und/oder Marken der jeweiligen Hersteller.
Diese Unterlagen sind streng vertraulich. Durch die Übermittlung und Präsentation dieser Unterlagen alleine werden keine Rechte an unserer Software, an unseren Dienstleistungen und Dienstleistungsresultaten oder sonstigen geschützten Rechten begründet. Die Weitergabe, Veröffentlichung oder Vervielfältigung ist nicht gestattet.
Aus Gründen der einfacheren Lesbarkeit wird auf die geschlechtsspezifische Differenzierung, z.B. Benutzer/-innen, verzichtet. Entsprechende Begriffe gelten im Sinne der Gleichbehandlung grundsätzlich für beide Geschlechter.
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. 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:
Auslesen der mit der api.v2.personalization protokollierten Daten in app.telemetry | |
Einrichten der Personalisierung im Standard Mindbreeze InSpire Search Client |
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_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.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_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.
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
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/"
}
}