Server-seitige Conversions

Manche Conversions entstehen nicht im Browser. Eine Anfrage wird erst Tage später zum bezahlten Auftrag, ein Abo wird nach der Testphase aktiv, eine Bestellung erst nach der Bonitätsprüfung freigegeben.

Mit der Server-API meldest du solche Ereignisse aus deinem eigenen Backend an usertrax. usertrax findet den ursprünglichen Besuch wieder und überträgt dessen Werbe-Attribution — gclid, fbclid, UTM-Parameter — auf das neue Ereignis. So landet der Umsatz in Google Ads und Meta bei der Kampagne, die ihn ausgelöst hat.

Ablauf

Referenz beim Formular-Versand speichern

Der Tracker gibt dir die IDs des laufenden Besuchs:

const ids = window.usertrax.getTrackingIds();
// { session_id: "…", visitor_id: "…" }

Schreibe session_id in ein verstecktes Formularfeld und speichere den Wert zusammen mit der Anfrage in deiner Datenbank:

<form method="post" action="/anfrage">
  <input type="hidden" name="usertrax_session" id="usertrax_session" />
  <!-- weitere Felder -->
</form>

<script>
  document.getElementById("usertrax_session").value =
    window.usertrax.getTrackingIds().session_id || "";
</script>

Server-Key holen
Im Dashboard unter Domains → Einstellungen findest du den Server-Key (utx_sk_…).
Der Server-Key ist geheim. Er gehört ausschließlich in dein Backend — niemals in JavaScript, HTML oder ein öffentliches Repository. Er ist nicht derselbe Wert wie der Auth-Key aus dem Tracking-Script.

Conversion melden

Sobald aus der Anfrage ein Auftrag wird, schickt dein Backend:

curl -X POST https://api.usertrax.io/api/v1/server/conversions \
  -H "X-Server-Key: utx_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "event": "purchase",
    "event_id": "auftrag-8123",
    "value": 2500.00,
    "currency": "EUR",
    "reference": { "session_id": "die-gespeicherte-session-id" },
    "user_data": { "email": "kunde@example.com" }
  }'

Antwort:

{
  "status": "success",
  "conversion_id": 91823,
  "event_id": "auftrag-8123",
  "attribution_source": "session"
}

attribution_source zeigt, worüber die Verknüpfung gefunden wurde. Steht dort none, konnte usertrax den ursprünglichen Besuch nicht zuordnen — die Conversion wird trotzdem gespeichert, aber ohne Werbe-Attribution.

Verknüpfung ohne gespeicherte Session-ID

usertrax probiert mehrere Wege durch und nimmt den ersten Treffer:

Feld	Beschreibung
`reference.session_id`	Die zuverlässigste Variante — siehe oben
`reference.event_id`	Die `event_id` der ursprünglichen Conversion, z. B. deines `lead`-Events
`reference.visitor_id`	Der wiedererkennbare Besucher über mehrere Sitzungen hinweg
`user_data.email`	Wird einem bestehenden Profil zugeordnet

Du kannst gclid, fbclid und utm auch direkt mitschicken, wenn du sie selbst gespeichert hast. Direkt übergebene Werte haben immer Vorrang vor geerbten.

Mehrere Conversions auf einmal

Für nächtliche Abgleiche gibt es einen Batch-Endpunkt mit bis zu 100 Ereignissen pro Anfrage:

curl -X POST https://api.usertrax.io/api/v1/server/conversions/batch \
  -H "X-Server-Key: utx_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "conversions": [
      { "event": "purchase", "event_id": "auftrag-1", "value": 1200 },
      { "event": "purchase", "event_id": "auftrag-2", "value": 890 }
    ]
  }'

Die Antwort meldet jedes Element einzeln zurück. Ein fehlerhafter Datensatz blockiert die übrigen nicht.

Felder

Feld	Typ	Beschreibung
`event`	string, Pflicht	Name des Ereignisses, z. B. `purchase` (max. 100 Zeichen)
`event_id`	string	Deine eigene ID, z. B. die Auftragsnummer. Dient der Dublettenerkennung
`value`	number	Wert der Conversion
`currency`	string	ISO-Code, z. B. `EUR`. Ohne Angabe gilt die Währung der Domain
`event_timestamp`	string	Zeitpunkt im ISO-8601-Format. Ohne Angabe: jetzt. Max. 90 Tage rückwirkend
`label`	string	Freies Label zur Einordnung im Dashboard
`reference.session_id`	string	Session-ID aus `getTrackingIds()`
`reference.event_id`	string	`event_id` der ursprünglichen Conversion
`reference.visitor_id`	string	Visitor-ID aus `getTrackingIds()`
`user_data`	object	`email`, `customer_id`, `phone` — für Profil-Zuordnung und Enhanced Conversions
`meta_data`	object	Beliebige Zusatzdaten, die am Ereignis gespeichert werden
`gclid`, `fbclid`, `fbc`, `fbp`, `msclkid`, `ttclid`, `adcell`, `awc`, `li_fat_id`	string	Klick-IDs, falls du sie selbst gespeichert hast
`utm`	object	`utm_source`, `utm_medium`, `utm_campaign`, `utm_term`, `utm_content`
`landing_page`	string	Einstiegsseite des ursprünglichen Besuchs
`first_touchpoint`, `last_touchpoint`	string	Kanal des ersten bzw. letzten Kontakts
`ip_address`, `user_agent`	string	IP und User-Agent des ursprünglichen Besuchs, nicht deines Servers. Verbessert das Matching bei Meta

Alle Felder außer event sind optional. Was du nicht mitschickst, ergänzt usertrax aus dem verknüpften Besuch.

Gut zu wissen

Doppelte Meldungen werden über event_id abgefangen. Schick ruhig denselben Auftrag zweimal — die Antwort lautet dann duplicate, und es entsteht keine zweite Conversion.
Rückdatierung ist bis 90 Tage möglich (event_timestamp im ISO-8601-Format). Ältere Ereignisse lehnt usertrax ab, weil Google Ads und Meta sie ohnehin verwerfen.
Bestehende Ereignisse bleiben unverändert. Aus der Anfrage wird kein Auftrag „umgeschrieben“ — es entsteht ein zusätzliches Ereignis. Dein Funnel bleibt sichtbar.
Die Endpunkte findest du auch in der API-Referenz unter „Server-Side Tracking“.