# Werbe-Attribution

Verfolgen Sie den Anzeigenklick, der einen Kunden gebracht hat, bis zum Deal in Ihrem CRM und zurück zu Google Ads

> Full REST + WebSocket API reference: https://api.happ.tools/reference

Ein Besucher klickt auf Ihre Anzeige, liest ein paar Seiten, öffnet den Chat und hinterlässt eine Anfrage. Ihr CRM erhält den Deal — aber ohne jeden Hinweis darauf, welche Kampagne diesen Besuch bezahlt hat. Happ reicht den Klick jetzt durch die gesamte Kette weiter: Seite → Chat → Deal → zurück zum Werbenetzwerk.

Sie müssen nichts aktivieren. Jedes Widget, das mit dem aktuellen Einbettungs-Snippet geladen wird, beginnt beim nächsten Seitenaufruf mit der Erfassung.

## Was erfasst wird [#what-gets-collected]

Auf der ersten Seite des Besuchers liest das Einbettungsskript die Anzeigenparameter aus der URL und speichert sie auf Ihrer eigenen Domain:

| Gruppe            | Parameter                                                                       |
| ----------------- | ------------------------------------------------------------------------------- |
| Google            | `gclid`, `gbraid`, `wbraid`                                                     |
| Meta              | `fbclid`                                                                        |
| TikTok, Microsoft | `ttclid`, `msclkid`                                                             |
| Kampagnen-Labels  | `utm_source`, `utm_medium`, `utm_campaign`, `utm_content`, `utm_term`, `utm_id` |

Außerdem werden die Landingpage und der Referrer gespeichert.

Es werden zwei Kontaktpunkte gespeichert, nicht einer:

* **first touch** — die Kampagne, über die diese Person zum ersten Mal kam;
* **last touch** — worauf sie bei der Rückkehr geklickt hat; diesem Kontaktpunkt schreiben die Werbenetzwerke die Conversion zu.

Die Parameter bleiben beim Navigieren erhalten: Ein Besucher kann über die Anzeigen-URL einsteigen, fünf Seiten ohne Parameter in der Adresszeile ansehen und den Chat eine Stunde später öffnen — die Kampagne ist noch da. Ein Besuch ohne Anzeigenparameter überschreibt das Gespeicherte nie, sodass ein Kunde, der direkt zurückkehrt, um zu konvertieren, der Kampagne zugeordnet bleibt, die ihn gewonnen hat.

Gespräche aus einer Click-to-Messenger- oder Click-to-Instagram-Anzeige enthalten ihren Anzeigenkontext ebenso, mit Anzeigen-ID und Creative-Titel statt einer Klick-ID.

## Wo die Daten landen [#where-it-ends-up]

### Im CRM-Datensatz [#in-the-crm-record]

Jede CRM-Integration, die Leads oder Deals erstellt, schreibt die Herkunft in den Kommentar des Datensatzes:

```
--- Happ attribution ---
channel: widget
gclid: Cj0KCQjw...
utm_source: google
utm_medium: cpc
utm_campaign: raiden-brand
landing: /catalog
captured: 2026-09-19T08:12:44.000Z
```

Bewusst als Schlüssel-Wert-Zeilen: Ein Mitarbeiter kann sie lesen, und ein Skript, eine Tabellenformel oder ein n8n-Flow kann sie auswerten, ohne dass Sie bei uns einen Export anfragen müssen.

Der Agent muss nichts davon weitergeben. Eine Klick-ID besteht aus hundert undurchsichtigen Zeichen, und ein Modell, das sie kopieren soll, kürzt sie oder erfindet eine plausibel aussehende — eine falsche Klick-ID ist schlimmer als keine, weil sie als Conversion eines anderen hochgeladen wird. Die Plattform hängt sie serverseitig an, vollständig außerhalb des Gesprächs.

**NetHunt** stellt zusätzlich jedes Feld als zuordenbaren Parameter bereit — `attribution_gclid`, `attribution_utm_campaign`, `attribution_note` und die übrigen —, sodass Sie in den Integrationseinstellungen jedes Feld einer Spalte Ihres eigenen Ordners zuweisen können.

### In Ihrem Webhook [#in-your-webhook]

Wenn die Integration **Chat Webhook** verbunden ist, enthält jeder Nachrichten-Body ein `attribution`-Objekt, und ein neues Ereignis wird ausgelöst, wenn tatsächlich eine Anfrage erstellt wird:

```json
{
  "event": "lead.created",
  "eventId": "6f2a...:8821",
  "chatId": "6f2a1c84-...",
  "companyId": "8fb075ae-...",
  "toolName": "keepincrm_create",
  "entityId": "8821",
  "entityType": "leads",
  "phone": "+380731234567",
  "createdAt": "2026-09-19T08:14:02.000Z",
  "attribution": {
    "channel": "widget",
    "clickId": "Cj0KCQjw...",
    "clickNetwork": "google",
    "utmSource": "google",
    "utmMedium": "cpc",
    "utmCampaign": "raiden-brand",
    "landingPage": "/catalog",
    "referrer": "https://www.google.com/",
    "capturedAt": "2026-09-19T08:12:44.000Z",
    "note": "--- Happ attribution ---\nchannel: widget\ngclid: Cj0KCQjw..."
  }
}
```

`eventId` bleibt bei Wiederholungen stabil — deduplizieren Sie danach. Hat der Besucher über eine spätere Kampagne konvertiert als über die, mit der er zum ersten Mal kam, wird der first touch unter `attribution.first` mitgeliefert.

`phone` dient für [Enhanced Conversions for Leads](https://support.google.com/google-ads/answer/13258081): Sie gleichen über eine gehashte Telefonnummer ab und benötigen gar keine Klick-ID — die Rückfalllösung für Besucher, deren `gclid` nie in die URL gelangt ist.

Bodys ohne `event`-Feld sind wie bisher gewöhnliche Nachrichten.

### Auf der Seite, für GTM und GA4 [#on-the-page-for-gtm-and-ga4]

Wenn eine Anfrage erstellt wird, überträgt das Widget ein Ereignis in den `dataLayer` der einbettenden Seite:

```js
{
  event: "happ_lead_created",
  happ_event_id: "6f2a...:8821",
  happ_chat_id: "6f2a1c84-...",
  happ_entity_id: "8821",
  happ_entity_type: "leads",
  happ_widget_id: "wgt_..."
}
```

Das zählt die Anfrage, nicht das Öffnen des Chats — jeder neugierige Besucher öffnet den Chat, und eine so definierte Conversion liefert der Gebotsstrategie keine brauchbaren Signale. Das Ereignis wird im Browser dedupliziert, und `happ_event_id` entspricht der `eventId` des Webhooks, sodass sich eine serverseitige Kopie derselben Conversion damit abgleichen lässt.

In GTM: Erstellen Sie einen Trigger **Custom Event** auf `happ_lead_created`, verwenden Sie ihn für Ihr GA4-Ereignis oder Ihr Google-Ads-Conversion-Tag und übergeben Sie `happ_event_id` als Transaktions-/Ereignis-ID, damit beide Quellen nur einmal gezählt werden.

## Den Kreislauf mit Google Ads schließen [#closing-the-loop-with-google-ads]

1. Nehmen Sie die Deals, die Ihr CRM als gewonnen markiert.
2. Lesen Sie für jeden Deal die `gclid` aus der Attributionsnotiz (oder aus der Spalte, der Sie sie zugeordnet haben).
3. Laden Sie sie als [Offline-Conversions](https://support.google.com/google-ads/answer/2998031) mit Conversion-Wert und Zeitpunkt hoch.

Für Deals ohne Klick-ID — ein Besucher aus der organischen Suche, ein iOS-Besucher, bei dem nie eine `gclid` auftauchte — verwenden Sie stattdessen Enhanced Conversions for Leads mit der Telefonnummer.

## Einschränkungen [#limits]

* Parameter werden im `localStorage` des Browsers auf Ihrer Domain gespeichert. Ein Besucher, der Website-Daten löscht, das Gerät wechselt oder in einem privaten Fenster surft, gilt als neuer Besuch; der bereits in seinem Gespräch erfasste first touch wird dadurch nicht überschrieben.
* Ein aus dem Widget gestarteter Sprachanruf überträgt die Attribution noch nicht ins CRM — der Chat schon.
* Die Attribution gibt wieder, was in der URL stand. Führen Ihre Anzeigen auf eine Seite, die weiterleitet und dabei den Query-String verwirft, gibt es nichts zu erfassen; stellen Sie sicher, dass Ihre Weiterleitungen ihn beibehalten.