# Data layer events

URL: https://docs.ablyft.com/de/developers/tracking-and-events/datalayer-events/

> Nutze Einträge deines Data Layers, um Audiences zu starten und eigenen Code auszuführen.



Viele Websites sammeln Informationen in einem **Data Layer**: einem JavaScript-Array namens `window.dataLayer`. Tag Manager wie
der Google Tag Manager lesen ihn, und dein Shop oder deine Anwendung pusht Einträge hinein, zum Beispiel wenn ein Produkt in den
Warenkorb gelegt wird:

```js
window.dataLayer = window.dataLayer || [];
window.dataLayer.push({
  event: 'add_to_cart',
  ecommerce: { currency: 'EUR', value: 29.9, coupon: 'SUMMER' }
});
```

Ein Eintrag hat üblicherweise einen `event`-Key mit seinem Namen sowie beliebige weitere Daten. ABlyft kann auf zwei Arten auf solche Einträge reagieren:

* in einer **Audience**, um Visitors erst einzuschließen, nachdem etwas passiert ist (kein Code nötig),
* in **deinem eigenen Code**, mit zwei Hilfsfunktionen.

## Data-Layer-Events in Audiences nutzen

Eine Audience kann erst dann zu passen beginnen, nachdem ein bestimmter Data-Layer-Eintrag erschienen ist. Das ist nützlich, um Visitors anzusprechen,
die gerade etwas in den Warenkorb gelegt haben, die eine Consent-Kategorie akzeptiert haben oder deren Eintrag einen bestimmten Wert enthält.

1. Gehe zu **Targeting & Goals → Audiences** und erstelle oder bearbeite eine Audience.

2. Füge den Targeting-Block **dataLayer Event** hinzu.

3. Fülle die Regel aus:

   | Feld           | Beschreibung                                                                                                              |
   | -------------- | ------------------------------------------------------------------------------------------------------------------------- |
   | **Event name** | Der Wert des `event`-Keys, nach dem gesucht wird, zum Beispiel `add_to_cart`.                                             |
   | **Check**      | Was für den Eintrag zutreffen muss, siehe Tabelle unten.                                                                  |
   | **Property**   | Der zu prüfende Key, bei verschachtelten Daten mit Punkten: `ecommerce.coupon`. Nicht nötig bei **Event exists**.         |
   | **Value**      | Der Wert, mit dem verglichen wird. Nicht nötig bei **Event exists**, **property exists** und **property does not exist**. |

4. Speichere und [verknüpfe die Audience mit deinem Experiment](https://docs.ablyft.com/de/guides/audiences-and-delivery/audiences/).

### Checks (Operatoren)

| Check                       | Der Eintrag passt, wenn …                                                              |
| --------------------------- | -------------------------------------------------------------------------------------- |
| **Event exists**            | ein Eintrag mit diesem Event-Namen gepusht wurde. Property und Value werden ignoriert. |
| **property exists**         | die Property im Eintrag vorhanden ist                                                  |
| **property does not exist** | die Property fehlt                                                                     |
| **is (exactly)**            | die Property dem Value entspricht (als Text verglichen)                                |
| **is not (exactly)**        | die Property fehlt oder vom Value abweicht                                             |
| **contains**                | die Property, als Text, den Value enthält                                              |
| **does not contain**        | die Property, als Text, den Value nicht enthält                                        |
| **is greater than**         | die Property, als Zahl, größer als der Value ist                                       |
| **is less than**            | die Property, als Zahl, kleiner als der Value ist                                      |

Ist die Property ein Objekt oder eine Liste, vergleicht ABlyft deren JSON-Text.

### Wie es sich verhält

* ABlyft betrachtet Einträge, die **bereits im Data Layer** sind (der neueste mit diesem Event-Namen zählt), sowie
  alle **später** gepushten Einträge.
* Sobald ein Eintrag den Check erfüllt, gilt die Audience für den **Rest dieses Seitenaufrufs** als passend. Die
  Experiments, die die Audience verwenden, werden sofort erneut ausgewertet.
* Für die nächste Seite wird nichts gespeichert. Nach einem Reload muss der Data Layer erneut einen passenden Eintrag enthalten.
* Mehrere Regeln innerhalb eines Blocks werden mit ODER verknüpft; mehrere Blöcke einer Audience werden mit UND verknüpft.

> **Das Experiment muss auf einer aktiven Page laufen:** Ein Audience-Trigger wertet nur Experiments auf Pages neu aus, die bereits aktiv sind. Stelle sicher, dass die
> [Page](https://docs.ablyft.com/de/guides/audiences-and-delivery/pages/) des Experiments zu der URL passt, auf der der Eintrag gepusht wird.

## Wählen, wie ABlyft den Data Layer beobachtet

Das Snippet muss neue Einträge bemerken. Wie es das tut (**Intercept** oder **Polling**), steuert die Project-Einstellung **Data layer
watching**, siehe [Snippet settings](https://docs.ablyft.com/de/developers/installation/snippet-settings/#data-layer-watching). Ersetzt ein anderes Skript
`dataLayer.push`, wähle **Polling**. Die Einstellung gilt für die obigen Audience-Regeln und für `watchDataLayerEntry()` unten.

## Code ausführen, wenn ein Eintrag gepusht wird

Verwende diese Funktionen im Code von Variations, Page-Callbacks oder Projects, wo `ablyftTools` verfügbar ist. Beide sind in der
[Tools-Referenz](https://docs.ablyft.com/de/developers/reference/javascript-api/tools/#data-layer) beschrieben.

### `watchDataLayerEntry`

Reagiert auf jeden Eintrag mit dem angegebenen Event-Namen, siehe [`watchDataLayerEntry`](https://docs.ablyft.com/de/developers/reference/javascript-api/tools/#watchdatalayerentry).

```js
const stop = ablyftTools.watchDataLayerEntry('add_to_cart', (entry) => {
  console.log('Item added', entry.ecommerce.value);
});

// later, if no longer needed
stop();
```

Beispiel: Sende ein [Custom Goal](https://docs.ablyft.com/de/developers/tracking-and-events/custom-goals/), wenn ein Lead-Event auftritt. Für einen Kauf-Wert
siehe das Beispiel unter [Revenue tracking](https://docs.ablyft.com/de/developers/tracking-and-events/revenue-tracking/#take-the-value-from-your-page).

```js
ablyftTools.watchDataLayerEntry('generate_lead', () => {
  window.ablyft.push({ eventType: 'custom', eventName: 'lead' });
});
```

### `checkForDataLayerEntry`

Wartet auf einen bestimmten Eintrag, siehe [`checkForDataLayerEntry`](https://docs.ablyft.com/de/developers/reference/javascript-api/tools/#checkfordatalayerentry).
Das ist nützlich, um eine Page mit dem **Callback**-Trigger zu starten:

```js
ablyftTools.checkForDataLayerEntry(
  [['event', 'page_view'], ['page_location', 'https://www.example.com/test']],
  () => activate()
);
```

Siehe [Dynamische Inhalte](https://docs.ablyft.com/de/developers/application-integration/dynamic-content/#callback-trigger).

## Experiment-Informationen an den Data Layer senden

Die andere Richtung ist ebenfalls üblich: Dein Analytics-Tool soll wissen, welche Variation ein Visitor gesehen hat. Dafür kannst du eine
**Integration** hinzufügen, die läuft, wenn ein Visitor gebucketet wird oder ein Experiment ansieht. Gehe zu **Integrations → Custom Integrations**,
wähle den Trigger (**User bucketed** oder **Experiment viewed**) und füge JavaScript hinzu. Im Code kannst du `project`,
`experiment` und `variation` (jeweils mit `id` und `name`) sowie die Variation-`metadata` verwenden:

```js
dataLayer.push({
  'event': 'experimentViewed',
  'experiment_name': experiment.data.name,
  'variation_name': variation.data.name
});
```

Ein Tag Manager kann dieses Event dann an Google Analytics 4 weiterleiten. Die Integrationsdokumentation von ABlyft beschreibt eine
fertige Verbindung für den Google Tag Manager und GA4; kontaktiere den ABlyft-Support, wenn du Hilfe bei der Einrichtung möchtest.

## Fehlerbehebung

* **Audience passt nie:** Öffne die Browser-Konsole und führe `window.dataLayer` aus. Prüfe, dass der Event-Name exakt so geschrieben ist
  wie in der Audience und dass der Property-Pfad korrekt ist (Groß-/Kleinschreibung beachten).
* **Funktioniert nach einem Reload, aber nicht bei später gepushten Events:** Ein anderes Skript hat möglicherweise `dataLayer.push` ersetzt, nachdem ABlyft es
  umhüllt hat. Stelle **Data layer watching** auf **Polling**.
* **Callback läuft zweimal:** `watchDataLayerEntry` meldet auch einen Eintrag, der bereits existierte, als du dich registriert hast. Rufe
  die Stop-Funktion auf oder mache deinen Code sicher für zweimalige Ausführung.
* Aktiviere den [Debug-Modus](https://docs.ablyft.com/de/developers/debugging/preview-and-live-log/#debug-mode): Audience-Trigger werden mit
  `AUDIENCE TRIGGER activated` protokolliert.

## Nächste Schritte

- [Tools](https://docs.ablyft.com/de/developers/reference/javascript-api/tools/): Alle Hilfsfunktionen.
- [Custom goals](https://docs.ablyft.com/de/developers/tracking-and-events/custom-goals/): Conversions aus deinem Code zählen.
- [Audiences](https://docs.ablyft.com/de/guides/audiences-and-delivery/audiences/): Targeting-Regeln kombinieren.