Personalisierung

Der Bereich Personalisierung im Relevance Studio macht aus anonymen und eingeloggten User-Signalen Ranking-Anpassungen. Er besteht aus vier Schichten — jede optional und unabhängig pro Index aktivierbar:

1. Benutzerprofile — Feature-Vektoren pro User, abgeleitet aus Kauf- und Klick-Historie.
2. Segmente — grobe Kohorten (z. B. "Stammkäufer", "Schnäppchenjäger"), die Profile für editor-tunbare Boosts gruppieren.
3. Session-Reranking — kurzlebiges In-Session-Re-Ordering anhand der letzten Queries und Klicks.
4. Empfehlungen — related products, also-bought, frequently-viewed-together gespeist aus demselben Profilspeicher.

Wann Personalisierung aktivieren

Aktivieren Sie Personalisierung nur, wenn alle drei Bedingungen erfüllt sind:

• Ihre Suche hat ein echtes Konzept des wiederkehrenden Users (eingeloggt oder stabile anonyme ID).
• Sie haben mindestens ~10k Klick-Events pro Index und Woche — darunter ist das Signal zu verrauscht.
• Editor-Curations allein reichen nicht, um dieselbe Query für verschiedene User zu differenzieren.

Wenn Sie unsicher sind, starten Sie mit Session-Reranking allein — es braucht keine Historie und ist für Erstbesucher ein No-Op.

Wie personalize=true + sessionId in den Such-Call greifen

Jede öffentliche Search-Anfrage kann zwei Extra-Felder mitsenden:

• personalize: true im Body — schaltet die Schicht für diese Query an.
• sessionId: "<stable-id>" — eine UUID oder gehashter Cookie-Wert, der die Anfrage an das Profil (oder bei anonymen Usern an die Session) bindet.

Der Server löst diese Felder im Read-Pfad auf, bevor der Typesense- multi_search-Call abgeschickt wird, und AND-kombiniert einen Profil-Boost- Ausdruck ins bestehende Ranking. Der Ablauf entspricht den fünf Gates einer normalen Suche — Auth, Rate-Limit, Tenant-Filter, Scoped-Filter, multi_search — mit einem zusätzlichen Schritt zwischen Rate-Limit und Tenant-Filter: applyPersonalization.

Stabile IDs und PII

Die sessionId MUSS für AACsearch undurchsichtig sein. Senden Sie keine rohen E-Mail-Adressen, Telefonnummern oder CRM-User-IDs. Das empfohlene Muster:

sessionId = sha256(your_internal_user_id + BETTER_AUTH_SECRET_FRAGMENT).slice(0, 32)

Die server-seitige Historie hinter jedem Profil ist auf 100 Einträge pro Session begrenzt. Ältere Klicks und Views werden FIFO verworfen. Das ist Absicht: klein und schnell am Hot-Path zu laden, leicht zu löschen für DSGVO-Recht-auf-Vergessen-Anfragen (ein einziges DELETE /personalization/profile/<sessionId> reinigt es).

Beispiel: curl

curl -X POST https://api.aacsearch.com/api/search/public/multi \
  -H "Authorization: Bearer ss_search_pub_XXXXXX" \
  -H "Content-Type: application/json" \
  -d '{
    "searches": [
      {
        "collection": "products",
        "q": "running shoes",
        "query_by": "title,brand,description",
        "personalize": true,
        "sessionId": "9f3c1b2e8a7d4f6c0b1a2d3e4f5a6b7c"
      }
    ]
  }'

Die Antwortform bleibt unverändert. Falls personalize=true nicht greifen kann — leeres Profil, Personalisierung am Index deaktiviert, Scale-Plan- Entitlement fehlt — fällt der Request sauber auf das Standard-Ranking zurück und ein personalization_applied: false-Flag wird in den Metadaten mitgeschickt.

Beispiel: TypeScript-SDK / oRPC-Client

import { client } from "@repo/api/client";

const res = await client.search.public.multi.call({
  searches: [
    {
      collection: "products",
      q: "running shoes",
      query_by: "title,brand,description",
      personalize: true,
      sessionId: visitorSessionId, // sha256(uid + secret).slice(0, 32)
    },
  ],
});

Für die Browser-Nutzung bevorzugen Sie den Scoped-Search-Token-Flow aus Architektur → Read-Pfad — die Felder personalize und sessionId werden unverändert durch den Token weitergereicht.

Profil-Boost ins Ranking verdrahten

In Studio → Relevanz → Personalisierung wählt ein Admin, wie Profil- Features das Ranking beeinflussen. Drei Modi:

Das Boost-Gewicht ist eine Zahl 0–10. Starten Sie bei 1.0, beobachten Sie CTR im Panel Click-Feedback eine Woche lang, dann in 0.5er-Schritten hochziehen. Werte > 5.0 dominieren typisch Curations — nur dorthin, wenn ein A/B-Test es belegt hat.

Segmente

Ein Segment ist ein gespeicherter Filter über den Profil-Raum. Segmente werden in Studio definiert und server-seitig bei jeder personalisierten Anfrage ausgewertet. Out-of-the-Box-Beispiele:

• frequent_buyers — Profile mit ≥ 3 Käufen in den letzten 30 Tagen.
• cart_abandoners — Profile mit ≥ 1 add_to_cart und 0 purchase in 7 Tagen.
• discount_hunters — Profile, deren geklickte Produkte in ≥ 50% der letzten Klicks discount_pct > 0 hatten.

Jedes Segment hat ein eigenes Boost-Gewicht. Ein User in zwei Segmenten erhält das Maximum der beiden (nicht die Summe) — das hält die Mathe vorhersehbar bei Überlappungen.

Empfehlungen

Derselbe Profilspeicher treibt die Empfehlungs-Endpoints. Diese sind als eigene oRPC-Prozeduren exponiert und brauchen kein personalize=true am Search-Call:

• recommendations.related — content-basiert: ähnlich zum Input-Produkt.
• recommendations.alsoBought — collaborative: aus dem Klick-und-Kauf-Graph.
• recommendations.frequentlyViewedTogether — Co-View innerhalb einer Session.

Siehe den dedizierten Abschnitt Empfehlungen für das vollständige Request-/Response-Schema.

Best Practices zu PII

1. Niemals rohe E-Mail / Telefon / Kunden-ID in sessionId. Vorher mit einem server-seitigen Secret hashen.
2. Behandeln Sie sessionId als Token, nicht als Identifier. Sie sollte beim Logout rotieren.
3. Historie auf 100 Einträge begrenzt. Das ist der server-seitige Default und die einzig unterstützte Konfiguration — hier dokumentiert, damit Kunden Retention klar verstehen.
4. DSGVO-Delete-Hook verdrahten. Bei einem Recht-auf-Vergessen-Antrag rufen Sie die Prozedur personalization.profile.delete mit der stabilen sessionId auf. Der Wipe ist synchron und idempotent.
5. Keine Personalisierung in Admin-Inspektions-Sessions. Studio-Inspect- Queries sollten personalize=false setzen, damit der Ranking Explainer das unverfälschte Ranking sieht.

Verwandt

• Personalization API Reference — vollständige Request-/Response-Schemata für personalize=true und recommendations.*.
• Learning to Rank — die orthogonale Feedback-Loop, die unabhängig von Personalisierung aus Klicks lernt.
• Architektur → Read-Pfad — wo applyPersonalization im Request-Flow sitzt.
• Empfehlungen — die Oberfläche, die denselben Profilspeicher konsumiert.