Widget-Analytics-Ereignisse

Das AACsearch-Widget verfolgt automatisch das Benutzerverhalten und sendet Ereignisse an den Analytics-Endpunkt. Diese Ereignisse speisen das Such-Analytics-Dashboard — Top-Anfragen, Null-Ergebnis-Rate, Klickrate und Suchen über Zeit.

Endpunkt

POST /api/events/track
Authorization: Bearer <ss_search_*- oder ss_scoped_*-Schlüssel>
Content-Type: application/json

Derselbe API-Schlüssel, der für die Suche verwendet wird (ss_search_*), wird zur Authentifizierung von Analytics-Ereignissen verwendet. Der Endpunkt ist CORS-aktiviert für alle Ursprünge.

Ereignistypen

Transport

Das Widget sendet Ereignisse mit keepalive: true, um den Verlust von Ereignissen bei der Seitennavigation zu verhindern:

fetch(eventsUrl, {
	method: "POST",
	headers: {
		"Content-Type": "application/json",
		Authorization: "Bearer " + apiKey,
	},
	keepalive: true,
	body: JSON.stringify(payload),
});

Payload-Schema

Sie können ein einzelnes Ereignis oder einen Batch von bis zu 50 Ereignissen senden.

Einzelnes Ereignis:

{
	"type": "search_query",
	"sessionId": "a1b2c3d4-e5f6-...",
	"anonymousUserId": "uid_xyz",
	"query": "blaue laufschuhe",
	"locale": "de",
	"referrer": "https://myshop.example.com/search",
	"metadata": {}
}

Batch:

{
	"events": [
		{ "type": "widget_open", "sessionId": "a1b2c3d4-..." },
		{ "type": "search_query", "query": "blaue laufschuhe", "sessionId": "a1b2c3d4-..." }
	]
}

Feldreferenz

Sitzungs-ID-Generierung

Das Widget generiert eine Sitzungs-ID mit crypto.randomUUID() und einem Fallback auf eine einfache Zufallszeichenkette:

const sessionId =
	typeof crypto !== "undefined" && crypto.randomUUID
		? crypto.randomUUID()
		: Math.random().toString(36).slice(2);

Die Sitzungs-ID ist pro Widget-Instanz / Seitenaufruf. Sie wird nicht persistiert.

Persistenz

Jedes Ereignis wird über recordSearchUsage() in der Tabelle SearchUsageEvent persistiert. Der Ereignistyp wird wie folgt abgebildet:

Alle Metadatenfelder (Anfrage, productId, position, filters, sort, locale, referrer, sessionId, anonymousUserId, user-agent) werden als JSON-Blob in SearchUsageEvent.metadata persistiert.

Was gespeichert wird und was nicht

Gespeichert:

• Ereignistyp
• Sitzungs-ID (ephemer, zufällig)
• Anonyme Benutzer-ID (zufällig, stabil pro Browser)
• Suchanfragetext
• Produkt-ID und Position für Klick-Ereignisse
• Facettenfilter
• Sortieroption
• Locale
• Referrer-URL (auf 512 Zeichen begrenzt)
• User-Agent-Zeichenkette (auf 256 Zeichen begrenzt)

Nicht gespeichert:

• Vollständige IP-Adresse — nur die serverseitige Anfrage wird verarbeitet; keine IP wird in SearchUsageEvent geschrieben
• E-Mail oder irgendein authentifizierter Benutzerkennzeichner
• Rohe Abfragestring-Parameter aus der Referrer-URL, die PII enthalten könnten

Teilpersistenz-Vorbehalt

Wenn ein Batch von Ereignissen gesendet wird und einige nicht persistiert werden können, gibt der Endpunkt zurück:

{
	"accepted": 4,
	"rejected": 1
}

Die rejected-Anzahl spiegelt Datenbankschreibfehler wider, keine Validierungsfehler. Validierungsfehler geben ein 400 zurück, bevor irgendwelche Schreibvorgänge stattfinden. Das Widget wiederholt abgelehnte Ereignisse nicht.

Analytics-Dashboard

In SearchUsageEvent gespeicherte Ereignisse speisen die Analytics-Prozeduren:

• search.usage — rohe Ereigniszeilen für den Zeitraum
• search.usageSummary — aggregierte Zählungen nach Typ
• search.topQueries — häufigste Suchanfragen
• search.analytics — Dashboard-Level-Analytics-Daten

Dashboard-Seiten unter Dashboard → Übersicht (KPI-Kacheln, Suchen über Zeit, Top-Anfragen) und Dashboard → Analytics lesen aus diesen Prozeduren.

Verwandte Seiten

• Widget-Übersicht
• Such-API-Authentifizierung
• Dashboard-Übersicht