# Meta Ads-Integration

<Aside type="caution" icon="setting" title="Hilfe vom Entwicklungsteam erforderlich">
 Sie benötigen Hilfe von Ihrem Entwicklungsteam, um die Integration einzurichten. Bitte teilen Sie diese Anleitung mit ihnen.
</Aside>

Die [Meta Ads](https://www.facebook.com/business/ads)-Integration ermöglicht es Ihnen, Pushwoosh-Zielgruppen mit Ihren Meta-Werbekonten zu synchronisieren. Nutzen Sie sie, um Benutzer in Werbekampagnen gezielt anzusprechen oder auszuschließen und bezahlte Anzeigen als weiteren Kanal in Ihrer Customer Journey hinzuzufügen.

## Anwendungsfälle

Nutzen Sie diese Integration, um:

* hochwertige Benutzer in mehreren Kanälen anzusprechen, um Käufe oder das Engagement zu steigern
* Benutzer, die in anderen Kanälen weniger reaktionsfreudig sind, erneut anzusprechen (Retargeting)
* Unterdrückungs-Zielgruppen (Suppression Audiences) zu erstellen, damit treue Kunden keine unnötigen Anzeigen erhalten


## Voraussetzungen
Bevor Sie Meta Ads verbinden, stellen Sie sicher, dass:

* Sie die Rolle **Admin** in Ihrem Pushwoosh-Konto haben. Informationen zur Funktionsweise von Rollen und Berechtigungen finden Sie unter [Benutzerzugriff und Berechtigungen verwalten](/de/product/account-management-and-security/multi-login-accounts/#creating-and-managing-roles-also-known-as-groups).
* Sie einen [**Facebook Business Manager**](https://www.facebook.com/business/tools/business-manager) eingerichtet haben, um die Facebook-Assets Ihrer Marke zu verwalten, einschließlich Werbekonten, Seiten und Apps.
* Sie ein aktives [**Facebook-Werbekonto**](https://www.facebook.com/business/tools/ads-manager) haben, das mit Ihrem Business Manager verknüpft ist.
* Der Administrator Ihres Facebook Business Managers Ihnen entweder die Berechtigung **Kampagnen verwalten** oder **Werbekonten verwalten** für die Werbekonten erteilt hat, die Sie mit Pushwoosh verwenden möchten.
* Sie die allgemeinen Geschäftsbedingungen für diese Werbekonten akzeptiert haben.
* Sie die [**Nutzungsbedingungen für Custom Audiences von Facebook**](https://business.facebook.com/legal/terms/customaudience) für die Facebook-Werbekonten, die Sie mit Pushwoosh verwenden möchten, akzeptiert haben.

## Meta Ads in Pushwoosh einrichten

1. Gehen Sie in Pushwoosh zu **Einstellungen** > **Drittanbieter-Integrationen**.

2. Klicken Sie in der Meta Ads-Karte auf **Login-Seite**.

<img src="/integrations-meta-ads-integration-1.webp" alt="Seite für Drittanbieter-Integrationen mit Meta Ads-Karte, die Links zu Konfiguration, Einrichtungsanleitung und Login-Seite zeigt"/>

3. Melden Sie sich bei Ihrem Meta-Konto an und klicken Sie dann auf **Weiter**.

4. Wählen Sie die Werbekonten aus, die Sie verbinden möchten.
<img src="/integrations-meta-ads-integration-6.webp" alt="Meta-Bildschirm zur Auswahl der Geschäftszugriffsoption für die verbundene Integration" width="480" />

5. Überprüfen Sie die angeforderten Berechtigungen für den Werbekonto- und Geschäftszugriff.

6. Klicken Sie auf **Speichern**. Meta zeigt dann eine Bestätigung an, dass Ihr Konto verbunden ist.

### Verbindungsstatus überprüfen


Nach der Einrichtung werden Sie zur Seite **Meta Ads** in Pushwoosh weitergeleitet.

<img src="/integrations-meta-ads-integration-8.webp" alt="Pushwoosh Meta Ads-Seite mit „Verbunden“-Badge, Tabelle der Werbekonten mit Spalte für Geschäftskonto, Kopfzeilen-Aktionen und „Wie man Zielgruppen mit Meta synchronisiert“" />

Die Tabelle der Werbekonten listet jedes verbundene Konto mit folgenden Informationen auf:

* **Name des Werbekontos**
* **Geschäftskonto**
* **ID**

Öffnen Sie die drei Punkte am Ende einer Zeile und wählen Sie **Werbekonto entfernen**, um dieses Werbekonto aus der Liste in Pushwoosh zu löschen.

### Verbundene Werbekonten verwalten

Klicken Sie auf der Seite **Meta Ads** auf **Konten verwalten**, um den Dialog zu öffnen. Verwenden Sie den Schalter in jeder Zeile, um das jeweilige Werbekonto in die Integration einzubeziehen oder auszuschließen.
Klicken Sie auf **Anwenden**, um die Änderungen zu speichern, oder auf **Abbrechen**, um ohne Speichern zu schließen.

So passen Sie die Listenansicht an:

* Schalten Sie **Nur verbundene anzeigen** ein oder aus, um die angezeigten Zeilen zu begrenzen.
* Geben Sie in **Nach Name oder ID suchen...** ein, um Konten in der Liste zu finden.

<img src="/integrations-meta-ads-integration-4.webp" alt="Dialog „Werbekonten verwalten“ mit Schalter „Nur verbundene anzeigen“, Suche nach Name oder ID, Zeilenschaltern mit „Verbunden“- oder „Getrennt“-Badges, Abbrechen und Anwenden" />



### Projekt-Tags zu Meta-Feldern zuordnen

Das Zuordnen von Benutzereigenschaften ermöglicht es Ihnen, Pushwoosh mitzuteilen, welche Meta-Benutzerattribute welche **Tag-Namen**-Felder in Ihrem Projekt aktualisieren sollen. Auf diese Weise werden Daten, die von Meta kommen, dort gespeichert, wo Sie es erwarten.

<Aside type="note">
Für die Zielgruppensynchronisierung sendet Pushwoosh immer eine Kennung pro Benutzer aus **E-Mail**, **Telefonnummer** oder **MADID**, je nachdem, was im Profil vorhanden ist. Konfigurieren Sie die Zuordnung, wenn Meta **zusätzliche** Benutzerattribute über die oben genannten Kennungen hinaus erhalten soll.
</Aside>

1. Klicken Sie auf der Seite **Meta Ads** auf **Benutzerdaten zuordnen**.

2. Wählen Sie für jedes **Facebook-Feld** in der linken Spalte einen **Tag-Namen** in Ihrem Projekt aus dem Steuerelement auf der rechten Seite.
Ordnen Sie nur die Zeilen zu, die Sie benötigen.

<img src="/integrations-meta-ads-integration-3.webp" alt="Modal „Projekt-Tags zu Meta-Feldern zuordnen“ mit den Spalten „Facebook-Feld“ und „Tag-Name“, Kontrollkästchen zum Überschreiben, Abbrechen und Speichern" width="480" />

<Aside type="note" title="Automatisch zugeordnete Felder">
Pushwoosh ordnet diese Felder automatisch zu. Sie legen sie nicht in **Projekt-Tags zu Meta-Feldern zuordnen** fest:

* **E-Mail**
* **Telefonnummer**
* **MADID**
</Aside>
3. Klicken Sie auf **Speichern**, um die Zuordnung anzuwenden, oder auf **Abbrechen**, um ohne Speichern zu schließen.

## MADID-Erfassung im SDK aktivieren

Meta Ads gleicht Benutzer anhand von Gerätekennungen (MADID) ab, die über das mobile SDK erfasst werden.
Das Pushwoosh SDK sammelt Werbekennungen (GAID bei Android, IDFA bei iOS) nicht
automatisch. Beide Plattformen erfordern eine ausdrückliche Zustimmung des Benutzers, bevor die Kennung ausgelesen werden kann.
Fordern Sie in Ihrer Anwendung die Zustimmung des Benutzers an, lesen Sie die Kennung aus, wenn dies gestattet ist, und übergeben Sie den
Wert an das SDK.

<Tabs syncKey="maid-sdk">
<TabItem label="Android">

**1. Fügen Sie die Abhängigkeit hinzu**

```groovy
implementation 'com.google.android.gms:play-services-ads-identifier:...'
```

**2. Deklarieren Sie die AD_ID-Berechtigung (erforderlich für targetSdk ≥ 33)**

Fügen Sie dies zu Ihrer `AndroidManifest.xml` hinzu:

```xml
<uses-permission android:name="com.google.android.gms.permission.AD_ID"/>
```

<Aside type="caution">
Ohne diese Berechtigung auf Android 13+ gibt `AdvertisingIdClient.getAdvertisingIdInfo()` stillschweigend eine Null-UUID (`00000000-0000-0000-0000-000000000000`) zurück. Das Pushwoosh SDK normalisiert dies zu `null`, sodass keine MADID an den Server gesendet wird und der Abgleich der Meta-Zielgruppe nicht funktioniert.
</Aside>

**3. Rufen Sie die GAID ab und übergeben Sie sie an das SDK**

`getAdvertisingIdInfo` muss in einem Hintergrund-Thread aufgerufen werden:

```java

String gaid = AdvertisingIdClient.getAdvertisingIdInfo(context).getId();

Pushwoosh.getInstance().setAdvertisingId(gaid);

```

Um den gespeicherten Wert im Backend zu löschen, übergeben Sie `null` oder eine leere Zeichenfolge:

```java
Pushwoosh.getInstance().setAdvertisingId(null);
```

**Verhaltenshinweise:**

- Wenn sich der Wert seit dem letzten erfolgreichen Aufruf nicht geändert hat, wird keine Netzwerkanfrage gestellt.
- Wenn die Netzwerkanfrage fehlschlägt, versuchen Sie es beim nächsten App-Start erneut.
- Der Aufruf wird ignoriert, wenn `Pushwoosh.stopCommunication()` aktiv ist.
- Die Null-UUID (`00000000-0000-0000-0000-000000000000`) wird genauso wie `null` behandelt – die gespeicherte MADID wird im Backend gelöscht.

</TabItem>
<TabItem label="iOS">

**1. Fügen Sie die Nutzungsbeschreibung zur `Info.plist` hinzu**

Apple verlangt diesen Schlüssel, bevor der ATT-Berechtigungsdialog angezeigt wird:

```xml
<key>NSUserTrackingUsageDescription</key>
<string>Wir verwenden Ihre Werbekennung, um Ihnen relevante Anzeigen zu zeigen.</string>
```

**2. Deklarieren Sie die Tracking-Domain in Ihrem Privacy Manifest**

Wenn Ihre App IDFA für das Tracking verwendet, verlangt Apple, dass Sie die Domains, die Tracking-Daten erhalten, in Ihrem [Privacy Manifest](https://developer.apple.com/documentation/bundleresources/privacy-manifest-files) (`PrivacyInfo.xcprivacy`) auflisten. Die vollständigen Anforderungen finden Sie unter [TN3182](https://developer.apple.com/documentation/technotes/tn3182-adding-privacy-tracking-keys-to-your-privacy-manifest).

Setzen Sie `NSPrivacyTracking` auf `true` und fügen Sie die Pushwoosh-Tracking-Domain zu `NSPrivacyTrackingDomains` hinzu:

```xml
<key>NSPrivacyTracking</key>
<true/>
<key>NSPrivacyTrackingDomains</key>
<array>
    <string>tracking.svc-nue.pushwoosh.com</string>
</array>
```

<Aside type="note">
Wenn der Benutzer die ATT-Berechtigung nicht erteilt hat, blockiert iOS Netzwerkanfragen an alle in `NSPrivacyTrackingDomains` aufgeführten Domains. Die MADID wird nicht gesendet, unabhängig davon, was Ihr Code tut.
</Aside>

**3. Fordern Sie die Tracking-Autorisierung an und übergeben Sie die IDFA an das SDK**

`ATTrackingManager` erfordert iOS 14 oder höher. Wenn Ihr Bereitstellungsziel unter iOS 14 liegt, umschließen Sie den Aufruf mit einer Verfügbarkeitsprüfung.

Das Pushwoosh SDK ruft `ATTrackingManager` nicht auf. Fordern Sie die Tracking-Autorisierung in Ihrer Anwendung an und übergeben Sie das Ergebnis dann an das SDK:

```swift
import AppTrackingTransparency
import AdSupport

if #available(iOS 14, *) {
    ATTrackingManager.requestTrackingAuthorization { status in
        let idfa = status == .authorized
            ? ASIdentifierManager.shared().advertisingIdentifier.uuidString
            : nil
        Pushwoosh.configure.setAdvertisingId(idfa)
    }
}
```


Um den gespeicherten Wert im Backend zu löschen, übergeben Sie `nil` oder eine leere Zeichenfolge:

```swift
Pushwoosh.configure.setAdvertisingId(nil)
```

**Verhaltenshinweise:**

- Wenn sich der Wert seit dem letzten erfolgreichen Aufruf nicht geändert hat, wird keine Netzwerkanfrage gestellt.
- Wenn die Netzwerkanfrage fehlschlägt, rufen Sie `setAdvertisingId` beim nächsten App-Start erneut auf.
- Der Aufruf wird ignoriert, wenn `Pushwoosh_ALLOW_SERVER_COMMUNICATION` deaktiviert ist.
- Die Null-UUID (`00000000-0000-0000-0000-000000000000`) wird genauso wie `nil` oder eine leere Zeichenfolge behandelt – die gespeicherte MADID wird im Backend gelöscht.

> Rufen Sie `requestTrackingAuthorization` aus dem Haupt-UI-Fluss Ihrer App auf. Apple empfiehlt, dies nach der Anzeige eines eigenen Erklärungsbildschirms zu tun, nicht sofort beim Start.

</TabItem>
</Tabs>

### Wie es funktioniert

Sobald Sie `setAdvertisingId` aufrufen, sendet das SDK den Wert als `madid`-Feld zusammen mit dem App-Code und der Geräte-Hardware-ID an den Pushwoosh-Tracking-Endpunkt. Pushwoosh verwendet diese Kennung, um Ihre Gerätedatensätze mit den Meta Ads-Zielgruppen zur Synchronisierung abzugleichen.


## Zielgruppen in Journeys synchronisieren

Der Punkt **Zielgruppen-Synchronisierung** im **Journey Builder** verknüpft Ihre Journey mit einer Meta Custom Audience. Jedes Mal, wenn ein Benutzer diesen Punkt erreicht, fordert Pushwoosh Meta auf, ihn entweder zur Zielgruppe hinzuzufügen oder daraus zu entfernen.

Sie können dies beispielsweise verwenden, um die Anzeige einer Webinar-Werbung für Benutzer zu beenden, die sich bereits registriert haben, damit Sie keine Werbeausgaben für Personen verschwenden, die sie nicht mehr sehen müssen.

So konfigurieren Sie die Zielgruppen-Synchronisierung:

1. Öffnen Sie den [**Journey Builder**](/de/product/customer-journey/pushwoosh-journey-overview/).

2. Fügen Sie einen [**zielgruppenbasierten Eintritt**](/de/product/customer-journey/journey-elements/entry-elements/audience-based-entry/) hinzu. Wählen Sie unter **Zielgruppenquelle** ein Pushwoosh-Segment oder eine Liste, die definiert, wer in diese Journey eintritt. Zum Beispiel ein Segment **Benutzer mit dem Tag `webinar_registered` auf `true` gesetzt**. Nur diese Benutzer werden die Journey durchlaufen und die **Zielgruppen-Synchronisierung** erreichen.

3. Fügen Sie den Punkt **Zielgruppen-Synchronisierung** hinzu.

4. Wählen Sie unter **Wie sollen Benutzerinformationen mit der Meta-Zielgruppe synchronisiert werden** eine Option aus:
   * **Benutzer zur Zielgruppe hinzufügen**. Fügt jeden Benutzer, der diesen Schritt erreicht, der von Ihnen ausgewählten Meta-Zielgruppe hinzu. Verwenden Sie dies beispielsweise, um eine Anzeige für Benutzer zu schalten, die sich angemeldet, aber noch nicht teilgenommen haben.
   * **Benutzer aus der Zielgruppe entfernen**. Entfernt jeden Benutzer, der diesen Schritt erreicht, aus dieser Meta-Zielgruppe. Wählen Sie in diesem Beispiel diese Option, um die Anzeige der Webinar-Werbung für bereits registrierte Benutzer zu beenden.

5. Wählen Sie unter **Meta Ads-Konto** das verbundene Werbekonto aus.

6. Wählen Sie unter **Zielgruppe** die Meta-Zielgruppe aus, zum Beispiel **Webinar**.

<img src="/integrations-meta-ads-integration-10.webp" alt="Panel für die Zielgruppen-Synchronisierung mit Dropdown-Menü „Zielgruppe“ und ausgewählter Meta Custom Audience" />

7. Klicken Sie auf **Anwenden**, um den Punkt zu speichern, oder auf **Abbrechen**, um ohne Speichern zu schließen.

8. Schließen Sie die Konfiguration der Journey ab und starten Sie sie dann.

<img src="/integrations-meta-ads-integration-9.webp" alt="Panel für die Zielgruppen-Synchronisierung mit Schrittname, Benutzer hinzufügen oder entfernen, Meta Ads-Konto, Zielgruppe, Anwenden und Abbrechen" />

Wenn diese Benutzer die **Zielgruppen-Synchronisierung** erreichen, werden sie aus der **Webinar**-Zielgruppe in Meta entfernt, sodass sie die Webinar-Anzeige dort nicht mehr sehen.

## Verhalten und Fehlerbehandlung

Die Journey-Verarbeitung hängt von der Verfügbarkeit des Meta-Kontos und der Zielgruppe ab:

* Meta aktualisiert die Zielgruppe nur, wenn der Benutzer anhand der von Pushwoosh bereitgestellten Daten abgeglichen werden kann. Wenn Meta den Benutzer nicht abgleichen kann, ändert sich die Zielgruppe für diesen Benutzer nicht, und er setzt die Journey fort.
* Wenn ein Profil den Punkt **Zielgruppen-Synchronisierung** erreicht, während das verbundene Werbekonto getrennt ist, stoppt die Journey für dieses Profil und Pushwoosh sendet System- und E-Mail-Benachrichtigungen.
* Wenn eine ausgewählte Zielgruppe in Meta nicht gefunden wird und die API einen Fehler zurückgibt, stoppt die Journey für dieses Profil und Pushwoosh sendet System- und E-Mail-Benachrichtigungen.

## Statistiken zur Zielgruppen-Synchronisierung
Öffnen Sie nach dem Start die Statistiken für den Schritt **Zielgruppen-Synchronisierung**, um das Eintrittsvolumen, Hinzufügungen und Entfernungen sowie übersprungene Profile anzuzeigen. Details zu den Metriken finden Sie unter [**Zielgruppen-Synchronisierung**](/de/product/statistics-and-analytics/journey-statistics/journey-element-statistics/#audience-sync) in den **Customer Journey-Statistiken**.

<img src="/integrations-meta-ads-integration-11.webp" alt="Statistiken zur Zielgruppen-Synchronisierung mit Gesamteintritten, Zur Meta-Zielgruppe hinzugefügt, Aus Meta-Zielgruppe entfernt, Übersprungen (nicht synchronisiert) geht zum nächsten Schritt, Benutzer exportieren und Meta Ads-Konto für die Synchronisierung" />