api.langify · Oktober 2026

UTM-Tracking

Von der Kampagne bis zum Umsatz: Woher kommen unsere Installationen – und welche davon zahlen?

← → zum Blättern · F für Vollbild
Warum

Die Frage dahinter

Nicht nur wie viele Shops eine Kampagne bringt, sondern welche davon upgraden – und wie viel MRR daraus entsteht.

Ablauf

Fünf Schritte vom Klick zum Report

1

Erfassen

Klick auf /install?utm_… → Zeile in install_attribution, Cookie mit install_uid

2

Verknüpfen

OAuth-Callback nach Installation → install_uid wird dem Shop zugeordnet

3

Auswerten

Plan-Wechsel → shop_plan_event + GA4-Event mit UTM-Daten

4

Report-API

/v2/api/staff/report, JWT mit Scope report

5

Intranet

Kennzahlen, Umsatz & MRR je Quelle, Journeys, PDF

Der Schlüssel

Eine ID hält alles zusammen

install_uid = 3f6c2a1e-8b7d-4c3e-…
EntstehtAPI erzeugt UUID v4 beim Erfassen des Klicks
Wandertv1 speichert sie als Cookie im Browser des Händlers
Kommt zurückOAuth-Callback schickt sie mit → shop_id wird gesetzt
Wird referenziertjedes Plan-Event trägt attribution_install_uid

Nur Neu- und Re-Installs werden verknüpft – Logins in bestehende Shops ändern nichts.

Schritt 1 + 2

Erfassen und Verknüpfen

POST /auth/remote/install-attribution

  • utm_source … utm_term, landing_url, referer
  • getrimmt, gekürzt, leer → NULL
  • referrer_domain = Host ohne www.
{ "success": true,
  "install_uid": "3f6c2a1e-…" }

POST /auth/remote/oauth/callback

  • JWT (remote-auth) + Shopify-HMAC prüfen
  • Neuer Shop oder Re-Install → link()
  • setzt shop_id und install_date
  • keine passende UID → still ignoriert
Schritt 3

Bei jedem Plan-Wechsel

Datenbank: shop_plan_event

  • upgrade, downgrade oder cancel
  • alter/neuer Plan, Preis (USD, monatlich)
  • attribution_install_uid → Verbindung zur Kampagne

Google Analytics 4

  • Events plan_change und plan_<ziel>
  • UTM als install_source, install_campaign, …
  • client_id = sha1(shopId) – pseudonym, je Shop
Schritt 4 + 5

Auswertung im Intranet

intern.lovely-app.com/report · Rolle reporting oder admin · live aus der API, 1 h Redis-Cache

Kennzahlen

Attributionen (davon verknüpft), Plan-Events, Verteilung nach Quelle, Medium, Kampagne

Umsatz & MRR

je Quelle, je Plan, verlorener Umsatz durch Kündigungen und Downgrades

Journeys

Plan-Verlauf je Shop: stabil, gekündigt, Wechsler, nur Trial, Reaktivierung

Drill-down

Klick auf Quelle oder Medium filtert die Tabelle; nur verknüpfte per linked=1

Vorjahresvergleich

gleicher Zeitraum ein Jahr früher, per compare=1

PDF-Export

alle Filter, A4 quer, zum Weitergeben

Nutzen

Was wir jetzt beantworten können

Welche Kampagne bringt die meisten Installationen?
Wie hoch ist die Conversion von Klick zu Installation je Quelle?
Welche Quellen bringen zahlende Kunden – und wie viel MRR?
Wie entwickelt sich das im Vergleich zum Vorjahr?
Grenzen

Bekannte Lücken und offene Punkte

Re-Install über neue Kampagne → 502

shop_id ist UNIQUE; ein zweiter link() für denselben Shop scheitert.

Ohne Cookie keine Zuordnung

Blockierte Cookies, Browserwechsel oder Direkt-Install aus dem App Store → unknown.

debug_mode=true in GA4

Alle Events landen in der DebugView – für Produktion prüfen.

GA4 braucht Custom Dimensions

install_*-Parameter müssen angelegt sein; keine Verbindung zur Web-Session.

Mehr Details

Fragen?

Vollständige Dokumentation mit Endpunkten, Datenmodell und SQL-Beispielen: Dokumentation (HTML / PDF)

→ Zur Dokumentation

EN