Referenz zum Ereignismodell

Jedes Ereignis, das Sie an die Konversionsverfolgung von Scanova senden — aus dem Browser wie von Ihrem Server — folgt derselben Struktur. Diese Seite beschreibt jedes Feld, das Sie mitschicken können, und was die Verarbeitung damit macht.

Browser-Ereignisse (`POST /ct`)

Browser-Ereignisse sendet das SDK automatisch oder Sie selbst über scanova('track', ...). Sie stehen für Aktionen, die im Browser des Nutzers stattfinden.

Felder, die Sie senden können

Feld	Typ	Pflicht	Beschreibung
`event_id`	UUID-Zeichenkette	Nein	Eindeutige Kennung dieses Ereignisses. Ohne Angabe erzeugt das SDK sie automatisch. Senden Sie eine feste ID aus Ihrem Code, wenn Sie gefahrlos wiederholen wollen.
`site_id`	Zeichenkette	Ja	Die ID Ihrer Tracking-Website aus dem Dashboard.
`event_type`	Zeichenkette	Ja	Die Art des Ereignisses. Verwenden Sie snake_case (z. B. `page_view`, `cta_click`, `signup_completed`).
`scan_session_id`	UUID-Zeichenkette	Nein	Setzt das SDK automatisch aus dem URL-Parameter `scnv`. Für die Zuordnung zum QR-Code erforderlich.
`web_session_id`	UUID-Zeichenkette	Nein	Setzt das SDK automatisch je Browser-Sitzung (Zeitfenster von 30 Minuten).
`visitor_id`	UUID-Zeichenkette	Nein	Setzt das SDK automatisch. Bleibt ein Jahr lang als Cookie erhalten.
`page_url`	Zeichenkette	Nein	Vollständige URL der aktuellen Seite samt Abfragezeichenfolge.
`page_title`	Zeichenkette	Nein	Titel der Seite. Das Browser-SDK sendet ihn nicht; sinnvoll nur bei eigenen Anbindungen direkt an die API.
`referrer`	Zeichenkette	Nein	Die verweisende URL.
`event_time`	ISO-8601-Zeichenkette	Nein	Zeitpunkt des Ereignisses in UTC. Ohne Angabe gilt der Eingangszeitpunkt auf dem Server. Ein ausdrücklich gesetzter Wert bleibt erhalten und wird nicht durch den Eingangszeitpunkt ersetzt — ein rückdatiertes Ereignis landet also im genannten Zeitraum, was beim Befüllen oder Migrieren von Daten hilft. Hinweis: Das Browser-SDK sendet einen Schlüssel `timestamp`, der ein eigenes, internes Feld ist — rufen Sie die API direkt auf, verwenden Sie `event_time`.
`device`	Objekt	Nein	Angaben zu Browser und Gerät — siehe unten.
`metadata`	Objekt	Nein	Eigene Schlüssel-Wert-Daten. Höchstens 10 KB, höchstens fünf Ebenen tief. Keine E-Mail-Adressen im Klartext.

Felder des Objekts device:

Feld	Beschreibung
`user_agent`	Die User-Agent-Zeichenkette des Browsers
`screen_width`	Bildschirmbreite in Pixeln
`screen_height`	Bildschirmhöhe in Pixeln
`language`	Sprache des Browsers (z. B. `en-US`)

Beispiel für die Nutzdaten eines Browser-Ereignisses

{
  "event_id": "f9ac7db6-f900-4d8e-8918-c846834195a8",
  "site_id": "N74rwgykxCwUe7SDFb2BMVN8Kc0aCQvKajiUKz9MSk3Bldn70jw8uLE3dUTgeS6r",
  "event_type": "cta_click",
  "scan_session_id": "7ad26d4f-3181-4ef8-b6ca-b8f59499dd43",
  "page_url": "https://yoursite.com/?scnv=7ad26d4f-3181-4ef8-b6ca-b8f59499dd43",
  "referrer": "",
  "timestamp": "2026-05-13T10:00:00.000Z",
  "device": {
    "user_agent": "Mozilla/5.0 ...",
    "screen_width": 1680,
    "screen_height": 1050,
    "language": "en-US"
  },
  "metadata": {
    "button_text": "Start Free Trial",
    "section": "pricing"
  }
}

Server-Ereignisse (`POST /server-events`)

Server-Ereignisse senden Sie mit einem API-Schlüssel aus Ihrem Backend. Sie stehen für Aktionen auf Ihrem Server, etwa abgeschlossene Käufe, bestätigte Registrierungen oder im CRM angelegte Leads.

Felder, die Sie senden können

Feld	Typ	Pflicht	Beschreibung
`event_id`	UUID-Zeichenkette	Empfohlen	Eindeutige Ereignis-ID für gefahrlose Wiederholungen. Einmal erzeugen, speichern, bei jeder Wiederholung erneut verwenden.
`site_id`	Zeichenkette	Ja	Die ID Ihrer Tracking-Website. Sie muss zu der Website passen, für die der API-Schlüssel gilt.
`event_name`	Zeichenkette	Ja	Sprechender Name des Ereignisses (z. B. `purchase`, `signup`, `lead`).
`scan_session_id`	UUID-Zeichenkette	Ja	Verknüpft dieses Server-Ereignis mit dem auslösenden QR-Code-Scan. Vom Browser an Ihren Server übergeben.
`web_session_id`	UUID-Zeichenkette	Nein	Die Sitzungs-ID aus dem Browser — übergeben Sie sie, wenn vorhanden, für eine genauere Verknüpfung der Sitzungen.
`visitor_id`	UUID-Zeichenkette	Nein	Die dauerhafte Besucher-ID aus dem Browser — übergeben Sie sie, wenn vorhanden.
`event_time`	ISO-8601-Zeichenkette	Nein	Wann das Ereignis stattfand. Standard ist der Eingangszeitpunkt.
`conversion_value`	Objekt	Nein	`{ "amount": 99.99, "currency": "USD" }`. Die Währung muss ein dreistelliger ISO-4217-Code sein.
`user_identifiers`	Objekt	Nein	Gehashte Nutzerkennungen — siehe unten. Senden Sie niemals E-Mail-Adressen oder Telefonnummern im Klartext.
`properties`	Objekt	Nein	Eigene Schlüssel-Wert-Daten. Höchstens 10 KB. Keine E-Mail-Adressen im Klartext.
`consent`	Zeichenkette	Nein	`granted`, `denied` oder `pending`.

Felder des Objekts user_identifiers (alle gehasht):

Feld	Beschreibung
`email_hash`	SHA-256-Hash der kleingeschriebenen E-Mail-Adresse des Nutzers
`phone_hash`	SHA-256-Hash der Telefonnummer des Nutzers im Format E.164
`external_id`	Ihre interne Nutzer- oder Kundennummer

Beispiel für die Nutzdaten eines Server-Ereignisses

{
  "event_id": "550e8400-e29b-41d4-a716-446655440000",
  "site_id": "N74rwgykxCwUe7SDFb2BMVN8Kc0aCQvKajiUKz9MSk3Bldn70jw8uLE3dUTgeS6r",
  "event_name": "purchase",
  "scan_session_id": "7ad26d4f-3181-4ef8-b6ca-b8f59499dd43",
  "conversion_value": { "amount": 49.99, "currency": "USD" },
  "user_identifiers": {
    "email_hash": "b94d27b9934d3e08a52e52d7da7dabfac484efe04294e576fc583c381f2d9c5d",
    "external_id": "usr_1234"
  },
  "properties": {
    "order_id": "ord_9876",
    "plan": "pro"
  }
}

Konventionen für Ereignisnamen

Verwenden Sie einheitliche, sprechende Namen in snake_case. Ein klares Schema macht Berichte leichter lesbar.

Gut	Besser vermeiden
`page_view`	`pageView`, `PageView`, `pv`
`cta_click`	`click1`, `btnClick`
`signup_completed`	`signup`, `reg`
`purchase`	`buy`, `order_placed_final`

Idempotenz

Browser- wie Server-Ereignisse unterstützen für die Dublettenerkennung ein Feld event_id:

Trifft dieselbe event_id mehrfach ein, wird die Dublette gespeichert, aber mit is_duplicate = 1 markiert
Dubletten bleiben in den Auswertungen automatisch außen vor
Verwenden Sie beim Wiederholen eines fehlgeschlagenen Server-Ereignisses immer dieselbe event_id

Datenschutz und DSGVO

Senden Sie niemals E-Mail-Adressen im Klartext in metadata oder properties. Nutzen Sie user_identifiers mit gehashten Werten.
Das Feld consent steuert, wie die Verarbeitung mit personenbezogenen Daten umgeht:
- granted — alle Felder werden normal gespeichert
- denied oder pending — page_url, referrer, city und metadata werden vor dem Speichern entfernt
- Der Wert von consent selbst wird als Nachweis immer gespeichert

Die Einwilligung aus dem Browser senden

Das Browser-SDK hat keine eingebaute Schnittstelle für Einwilligungen. Empfohlen ist, das SDK nur bedingt zu laden — je nach Entscheidung Ihrer Einwilligungsverwaltung:

<script>
  // Only load the SDK after the user grants consent
  if (userHasGrantedConsent()) {
    (function(w,d,s,o,f,js,fjs){
      w['ScanovaTrackingObject']=o;w[o]=w[o]||function(){(w[o].q=w[o].q||[]).push(arguments)};
      js=d.createElement(s),fjs=d.getElementsByTagName(s)[0];
      js.id=o;js.src=f;js.async=1;fjs.parentNode.insertBefore(js,fjs);
    })(window,document,'script','scanova','https://cdn.scanova.io/ct/js/qcg.min.js');
    scanova('init', 'YOUR_SITE_ID', { autoPageview: true });
  }
</script>

Die Einwilligung vom Server senden

Bei Server-Ereignissen schicken Sie den Wert consent in den Nutzdaten jeder Anfrage neben Ihren übrigen Feldern mit.

Überblick

Browser-SDK

Serverseitig

API-Referenz

Ressourcen

Browser-Ereignisse (`POST /ct`)

Felder, die Sie senden können

Beispiel für die Nutzdaten eines Browser-Ereignisses

Server-Ereignisse (`POST /server-events`)

Felder, die Sie senden können

Beispiel für die Nutzdaten eines Server-Ereignisses

Konventionen für Ereignisnamen

Idempotenz

Datenschutz und DSGVO

Die Einwilligung aus dem Browser senden

Die Einwilligung vom Server senden

​Browser-Ereignisse (POST /ct)

​Felder, die Sie senden können

​Beispiel für die Nutzdaten eines Browser-Ereignisses

​Server-Ereignisse (POST /server-events)

​Felder, die Sie senden können

​Beispiel für die Nutzdaten eines Server-Ereignisses

​Konventionen für Ereignisnamen

​Idempotenz

​Datenschutz und DSGVO

​Die Einwilligung aus dem Browser senden

​Die Einwilligung vom Server senden

Browser-Ereignisse (`POST /ct`)

Felder, die Sie senden können

Beispiel für die Nutzdaten eines Browser-Ereignisses

Server-Ereignisse (`POST /server-events`)

Felder, die Sie senden können

Beispiel für die Nutzdaten eines Server-Ereignisses

Konventionen für Ereignisnamen

Idempotenz

Datenschutz und DSGVO

Die Einwilligung aus dem Browser senden

Die Einwilligung vom Server senden