Sporing af events

POST /v1/events/track er et offentligt, kun-skrivende endpoint bygget til at blive kaldt direkte fra en kundes eget website — det kan modtage events, men kan ikke læse noget tilbage, så det er sikkert at kalde med blot en offentlig nøgle, i modsætning til jeres primære API-nøgle.

Spor en enkelt event

curl -X POST https://api.wezend.com/v1/events/track \
  -H "Content-Type: application/json" \
  -d '{
    "public_key": "wz_pk_...",
    "event": "product_viewed",
    "identifiers": { "email": "anna@example.com" },
    "properties": { "sku": "DK-1180", "price": 499 }
  }'

En enkelt event returnerer 202 { "ok": true }.

Events knyttes til en kontaktprofil via identifiers (email eller telefon) — en event uden identifiers (eller et anonymous_id) accepteres, men kan aldrig knyttes til en kontaktprofil.

Batch af events

{
  "public_key": "wz_pk_...",
  "events": [
    { "event": "product_viewed", "identifiers": { "email": "anna@example.com" }, "properties": { "sku": "DK-1180" } },
    { "event": "add_to_cart", "identifiers": { "email": "anna@example.com" }, "properties": { "sku": "DK-1180", "qty": 1 } }
  ]
}

returnerer 202 { "accepted": 2, "rejected": 0 }.

Origin-begrænsning

I kan sende nøglen som X-ZC-Key i stedet for i body'en. Hver offentlig nøgle kan valgfrit begrænses til en tilladelsesliste af origins, så en lækket nøgle kun kan bruges til at sende events fra jeres eget domæne — en tom liste betyder alle origins. GET /v1/account/tracking-key returnerer den nøgle sammen med et klar-til-indsættelse-<script>-snippet, og PUT /v1/account/tracking-origins sætter tilladelseslisten (fx ["https://shop.eksempel.dk"]).

Identificér en navngiven kontakt

Event-tracking navngiver ingen og kræver derfor ingen signatur: den offentlige nøgle identificerer jeres konto og intet andet. Alt, der taler på en navngiven kontakts vegne, kræver en — in-app-indbakken (POST /v1/inapp/feed, POST /v1/inapp/read) og det at hænge en push-enhed på en kontakt (POST /v1/push/subscribe med en email). Den offentlige nøgle ligger i jeres sidekilde, så den kan aldrig i sig selv bevise, at den besøgende er netop én bestemt af jeres kontakter.

De kald tager en signatur, jeres egen server producerer — user_hash = HMAC-SHA256(lowercase(trim(email)), jeres identitets-secret), hex:

// your backend, when rendering the page — never in browser code
const crypto = require("crypto");
const email = user.email.trim().toLowerCase();
const userHash = crypto.createHmac("sha256", process.env.WEZEND_IDENTITY_SECRET)
                       .update(email).digest("hex");
// hand userHash to the page next to the email, then: wezend.identify(email, userHash)

Sæt adressen til små bogstaver og trim den før hashen. Vi gør det samme, så Anna@Firma.dk og anna@firma.dk verificerer som samme kontakt — opslaget bag signaturen er også case-insensitivt. Signerer I den rå streng, får en bruger der skrev et stort bogstav en 403, der ser ud som vores fejl.

Secreten hentes fra GET /v1/account/tracking-identity (dashboard: Indstillinger → Tracking) og er ikke den offentlige nøgle — hold den på jeres server. POST /v1/account/tracking-identity/rotate udsteder en ny og ugyldiggør hver hash, der allerede er beregnet, så udrul den nye secret før I roterer. Et kald, der kræver en signatur og kommer uden, afvises med 403 og identity_required: true. Push-registrering kan springe det over ved at udelade email — enheden er så anonym. Slår I kravet helt fra (PUT /v1/account/tracking-identity med { "require_identity": false }), kan enhver, der læser jeres sidekilde, hente enhver kontakts beskeder ved at oplyse adressen, så gør det kun, hvis I ikke har identificeret trafik.

Hvad sker der bagefter

Når events ankommer, genberegnes beregnede traits, og segment-medlemskab opdateres i realtid — enhver journey, der overvåger den trigger eller det segment, kan udløses øjeblikkeligt, uden et batch-job involveret.