API für Browser-Ereignisse — POST /ct - Scanova API Documentation

Der Endpunkt /ct nimmt die Browser-Ereignisse des Scanova-Browser-SDK entgegen. In der Regel rufen Sie ihn nicht selbst auf — das übernimmt das SDK. Diese Seite beschreibt das Anfrageformat für eigene Anbindungen und zur Fehlersuche. Basis-URL: https://t.scanova.io

Endpunkt

POST https://t.scanova.io/ct

Ein Authentifizierungs-Header ist nicht nötig. Anfragen werden geprüft, indem der Header Origin oder Referer gegen die Liste Allowed Domains der Website abgeglichen wird.

Anfrage

Header:

Content-Type: application/json
Origin: https://yoursite.com

Anfragetext:

{
  "event_id": "f9ac7db6-f900-4d8e-8918-c846834195a8",
  "site_id": "YOUR_SITE_ID",
  "event_type": "cta_click",
  "scan_session_id": "7ad26d4f-3181-4ef8-b6ca-b8f59499dd43",
  "web_session_id": "2d0c328a-01d0-4010-85f4-f327130d1bd4",
  "visitor_id": "363fe851-7d8f-4090-902f-0f5a462829f5",
  "page_url": "https://yoursite.com/pricing",
  "referrer": "https://yoursite.com/",
  "timestamp": "2026-05-13T10:00:00.000Z",
  "device": {
    "user_agent": "Mozilla/5.0 ...",
    "screen_width": 1440,
    "screen_height": 900,
    "language": "en-US"
  },
  "metadata": {
    "button_text": "Start Free Trial",
    "section": "pricing"
  }
}

Felder

Feld	Typ	Pflicht	Beschreibung
`site_id`	Zeichenkette	Ja	ID der Tracking-Website
`event_type`	Zeichenkette	Ja	Name des Ereignisses in snake_case
`event_id`	UUID-Zeichenkette	Nein	ID zur Dublettenerkennung. Ohne Angabe automatisch erzeugt.
`scan_session_id`	UUID-Zeichenkette	Nein	Zuordnungs-ID des QR-Code-Scans
`web_session_id`	UUID-Zeichenkette	Nein	Sitzungs-ID im Browser (Zeitfenster von 30 Minuten)
`visitor_id`	UUID-Zeichenkette	Nein	Dauerhafte Besucher-ID (Cookie mit einem Jahr Laufzeit)
`page_url`	Zeichenkette	Nein	URL der aktuellen Seite
`referrer`	Zeichenkette	Nein	Verweisende URL
`timestamp`	ISO 8601	Nein	Zeitpunkt des Ereignisses. Standard ist der Eingangszeitpunkt.
`device`	Objekt	Nein	User-Agent, Bildschirmmaße, Sprache
`metadata`	Objekt	Nein	Eigene Daten. Höchstens 10 KB, fünf Ebenen tief.
`consent`	Zeichenkette	Nein	`granted`, `denied` oder `pending`

Antwort

Erfolg (200):

{
  "event_id": "f9ac7db6-f900-4d8e-8918-c846834195a8"
}

Fehlerantworten:

Status	Ursache
`400`	Ein Pflichtfeld fehlt oder die `site_id` ist ungültig
`403`	`Origin` bzw. `Referer` der Anfrage stehen nicht in den Allowed Domains der Website
`413`	Die Nutzdaten überschreiten die Größengrenze
`422`	Validierungsfehler in einem Feld
`429`	Ratengrenze überschritten (100 Anfragen pro Minute und IP-Adresse)

CORS

Der Endpunkt /ct unterstützt CORS. Browser-Anfragen von freigegebenen Domains sind erlaubt, und zwar mit:

Access-Control-Allow-Origin: <origin>
Access-Control-Allow-Methods: POST, OPTIONS

Preflight-Anfragen (OPTIONS) liefern 204 samt der passenden CORS-Header.

Batch-Endpunkt

Um mehrere Browser-Ereignisse in einer Anfrage zu senden:

POST https://t.scanova.io/collect/batch

Der Anfragetext umschließt ein Array:

{
  "events": [
    { "site_id": "...", "event_type": "pageview", ... },
    { "site_id": "...", "event_type": "scroll", "metadata": { "scroll_depth": 25 } }
  ]
}

Bis zu 100 Ereignisse je Stapelanfrage.

Überblick

Browser-SDK

Serverseitig

API-Referenz

Ressourcen

API für Browser-Ereignisse — POST /ct

Endpunkt

Anfrage

Felder

Antwort

CORS

Batch-Endpunkt

​Endpunkt

​Anfrage

​Felder

​Antwort

​CORS

​Batch-Endpunkt

Endpunkt

Anfrage

Felder

Antwort

CORS

Batch-Endpunkt