# Custom Integrations

URL: https://docs.ablyft.com/de/developers/integrations/custom-integrations/

> Erstelle JavaScript-Integrationen, die Experiment- und Variation-Daten an andere Tools senden, zum Beispiel in den Data Layer für Google Tag Manager.



**Custom Integrations** sind JavaScript-Snippets, die im Browser des Visitors laufen, wenn ein Experiment-Ereignis eintritt. Typischer Einsatz: Du sendest das Experiment und die Variation, die ein Visitor gesehen hat, an ein anderes Tool, zum Beispiel mit `dataLayer.push(...)` für Google Tag Manager oder GA4.

Eine Integration gehört zu einem **Projekt**. Sie gilt nicht workspace-weit und ist nicht an ein einzelnes Experiment gebunden. Jede **aktive** Integration wird mit dem Projekt-Snippet ausgeliefert und läuft für jedes Experiment und jede Variation, in die der Visitor eingeteilt wird.

## Wo finde ich sie?

Öffne **Project → Integrations → Custom Integrations**. Das Badge zeigt, wie viele Integrationen das Projekt hat. Ein aktives Abo ist erforderlich.

Die Liste zeigt Name, ob die Integration aktiv ist, den Trigger, ob sie synchron oder asynchron läuft, eine Vorschau des Codes und die letzte Aktualisierung. Mit den Zeilenaktionen kannst du eine Integration **Edit**, **Clone** oder **Delete**. Du kannst auch mehrere Zeilen auswählen und gemeinsam löschen.

## Integration erstellen

Lege eine neue Integration an und fülle die drei Bereiche aus.

### General

| Feld            | Regeln                                                                             |
| --------------- | ---------------------------------------------------------------------------------- |
| **Name**        | Pflichtfeld, bis zu 191 Zeichen, innerhalb des Projekts eindeutig.                 |
| **Description** | Optional, bis zu 2048 Zeichen.                                                     |
| **Active**      | Standardmäßig an. Inaktive Integrationen werden nicht an das Snippet ausgeliefert. |

### Trigger Settings

**When should this integration be triggered?**

| Option                           | Läuft                                                                                                                                           |
| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| **User bucketed**                | Nur beim ersten Mal, wenn ein Visitor einer Variation zugewiesen wird.                                                                          |
| **Experiment viewed** (Standard) | Jedes Mal, wenn der Visitor das Experiment sieht, also bei jedem Seitenaufruf oder erneuten Durchlauf, bei dem das Experiment ausgewertet wird. |

Zwei weitere Schalter steuern das Timing:

* **Run synchronously** (standardmäßig aus): führt die Integration sofort aus, statt sie in die Warteschlange zu stellen. Siehe [Sync und Async](#sync-and-async).
* **Run in preview mode** (standardmäßig aus): führt die Integration auch aus, wenn sich der Visitor im Preview-Modus befindet. Im Preview-Modus laufen Integrationen immer direkt und werden nie in die Warteschlange gestellt.

### Integration Code

Gib den **JavaScript-Code** ein. Er ist Pflicht und darf bis zu 32.768 Zeichen lang sein. Der Code läuft, sobald die Integration ausgelöst wird.

## Verfügbare Daten

Dein Code kann das aktuelle Projekt, Experiment und die Variation über `project`, `experiment` und `variation` lesen. Jedes Objekt hat ein `data`-Objekt:

| Objekt            | Felder       |
| ----------------- | ------------ |
| `project.data`    | `id`, `name` |
| `experiment.data` | `id`, `name` |
| `variation.data`  | `id`, `name` |

Dieselben Werte stehen auch als lokale Konstanten zur Verfügung: `projectId`, `projectName`, `experimentId`, `experimentName`, `variationId` und `variationName`.

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

## So läuft es auf der Website

1. **Die Veröffentlichung erfolgt automatisch.** Das Snippet wird neu veröffentlicht, wenn du eine Integration erstellst, löschst oder wiederherstellst oder ihren Namen, Code, Active-Status, Trigger, Sync-Flag oder Preview-Flag änderst. Du musst nicht manuell veröffentlichen.
2. **Nur aktive Integrationen werden aufgenommen**, sortiert nach Name. Der Code wird minifiziert, wenn die Projekteinstellung zum Verkleinern von JavaScript aktiv ist.
3. **Die Ausführung wartet auf DOM Ready**, versucht es dann sofort und wiederholt es alle 100 ms bis zu 20 Mal (etwa 2 Sekunden), bis der Code ohne Fehler durchläuft. Das hilft, wenn `dataLayer` oder eine Drittanbieter-Bibliothek spät lädt. Schlägt es weiterhin fehl, loggt die Browser-Konsole `Integration "<name>" did not complete after N attempts`.
4. **Nichts läuft, wenn Tracking für den Visitor deaktiviert ist** (Opt-out oder Do Not Track), außer im Preview-Modus.

> **Schreibe idempotenten Code:** Wenn dein Code teilweise erfolgreich ist und dann einen Fehler wirft, wird er erneut versucht und läuft möglicherweise mehrfach. Stelle sicher, dass eine doppelte Ausführung keinen Schaden anrichtet.

### Sync und Async

Eine Integration läuft direkt, wenn **Run synchronously** für die Integration aktiv ist **oder** der Run-Modus des Experiments **Synchronous** ist. Andernfalls wird sie in die Warteschlange gestellt und läuft zusammen mit den Tracker-Events.

Um den Modus für ein Experiment zu überschreiben, öffne die Code-Einstellungen des Experiments und wähle **Override integration run mode if necessary**:

* **Asynchronous**
* **Synchronous**
* **Inherit from integration (default)**

## Integrationen verwalten

* **Clone** erstellt eine Kopie mit dem Namen `<name> (Copy)` und übernimmt alle Einstellungen, auch **Active**.
* **Delete** entfernt die Integration. Sie verschwindet bei der nächsten Veröffentlichung aus dem Snippet.
* **View activities** auf der Edit-Seite zeigt den Änderungsverlauf. Es gibt keine Versionierung und kein Rollback.

## Nächste Schritte

- [Google Tag Manager + GA4](https://docs.ablyft.com/de/developers/integrations/google-tag-manager-ga4/): Nutze die integrierte Integration, um Experiment-Daten an GA4 zu senden.
- [External File Development](https://docs.ablyft.com/de/developers/application-integration/external-file-development/): Lade JavaScript und CSS von Variations von deinen eigenen URLs.
- [Data layer events](https://docs.ablyft.com/de/developers/tracking-and-events/datalayer-events/): Nutze Data-Layer-Einträge in Audiences und führe Code bei Pushes aus.