Offline Conversions API

Versende mit der Offline Conversions API Offline-Conversion-Events und finde heraus, wie viele Kund*innen Meta-Werbeanzeigen vor der Conversion angesehen oder angeklickt haben.

Bevor du beginnst

Für diese API benötigst du Folgendes:

1. Meta Business Manager

Falls du noch keinen hast, erstelle einen.

2. Meta-App-ID

Für den Zugriff auf die Marketing API. Zum Erstellen einer Meta-App:

• Rufe Business Manager > Unternehmenseinstellungen auf.
• Wähle Apps aus.
• Klicke auf Neue App hinzufügen und befolge die Anweisungen.

3. App-Review und Berechtigungen

Die Regeln im Zusammenhang mit App-Review und Berechtigungen richten sich danach, wie du unsere API implementierst:

4. Systemnutzer und Schlüssel für den Business Manager

Mit Systemnutzerzugriff kann deine App Daten über die API an Meta senden. So erstellst du ihn:

• Rufe Business Manager > Unternehmenseinstellungen auf.
• Wähle Systemnutzer aus.
• Klicke auf Neuen Systemnutzer hinzufügen.
• Wähle Admin-Systemnutzer als Rolle für den Systemnutzer aus.

Ein Zugriffsschlüssel liefert den Zugriff auf Meta-Daten. So erstellst du Systemnutzer-Zugriffsschlüssel:

• Rufe Business Manager > Unternehmenseinstellungen auf.
• Wähle Systemnutzer aus.
• Wähle den Systemnutzer aus und klicke auf Neuen Schlüssel generieren.
• Wähle deine App aus > wähle für Geltungsbereichads_management.

5. Werbekonto

Du brauchst ein Werbekonto, um Werbekampagnen auf Meta schalten zu können. Informationen zum Erstellen eines Werbekontos findest du unter Marketing API oder Hilfebereich für Werbetreibende, Einrichten von Personen, Seiten und Werbekonten im Business Manager.

6. Systemnutzerzugriff für Werbekonto

Erteile deinem Werbekonto Systemnutzerzugriff.

• Rufe Business Manager > Unternehmenseinstellungen auf.
• Wähle Systemnutzer aus.
• Wähle den Systemnutzer aus und klicke auf Assets zuweisen.
• Wähle dein Werbekonto aus.

7. Offline Event Set

Dabei handelt es sich um hochgeladene Dateien mit Offline-Conversion-Daten. Setze beim Erstellen einer Werbeanzeige tracking_spec auf die Offline-Event-Gruppen-ID, damit Events richtig zugeordnet werden. Dann kannst du Event-Gruppen erstellen, Statistiken zu deinen Importen ansehen und diese Daten im Business Manager löschen und ändern.

Beachte, dass du bei älteren Implementierungen CRUD-Vorgänge für Offline-Event-Gruppen auf Business Manager-Ebene ausführen könntest, um Event-Gruppen mit anderen Objekten und Einheiten zu teilen.

Event-Daten hochladen

Du benötigst spezifischen Zugriff, um Offline-Event-Gruppen zu erstellen oder Daten für eine Event-Gruppe hochzuladen oder anzuzeigen. Dieser Zugriff ist auch erforderlich, wenn du diese Berechtigungen einem Werbekonto zuweisen möchtest. Du musst eine der folgenden Rollen innehaben:

• Business Manager-Admin
• Admin-Systemnutzer, der die Offline-Event-Gruppe erstellt hat
• Admin für den ad_account, der mit der Offline-Event-Gruppe verbunden ist

Mehr dazu erfährst du unter Offline-Conversion-Event-Gruppe, Referenz.

1. Erstelle eine Offline-Event-Gruppe

curl 
  -F 'access_token=<SYSTEM_USER_ACCESS_TOKEN>' 
  -F 'name=offline_event_set',
  -F 'description=conversion data used for superbowl campaign',
  https://graph.facebook.com/<API_VERSION>/<BUSINESS_MANAGER_ID>/offline_conversion_data_sets

Sende eine HTTP POST-Anfrage:

POST /<BUSINESS_MANAGER_ID>/offline_conversion_data_sets HTTP/1.1
Host: graph.facebook.com

curl -X POST \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<BUSINESS_MANAGER_ID>/offline_conversion_data_sets

Die Antwort enthält eine Event-Gruppen-id:

{
  "id": <OFFLINE_EVENT_SET_ID>
}

Parameter

2. Weise Werbekontoberechtigungen zu

So weist du Tracking- und Leseberechtigungen für ein Werbekonto zu:

POST /<OFFLINE_EVENT_SET_ID>/adaccounts HTTP/1.1
Host: graph.facebook.com

curl -X POST \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<OFFLINE_EVENT_SET_ID>/adaccounts

Parameter

3. Lege das Tracking von Werbeanzeigen fest

Wenn du tracking_spec aktualisierst, überschreiben wir dies. Sende zunächst eine GET-Anfrage und hänge dann den zugehörigen String für die Offline-Event-Gruppe an die bestehende tracking_spec an. Lies dir das Thema Verwaltung von Werbeanzeigen durch oder verwende den Werbeanzeigenmanager. Gib beispielsweise eine passende Tracking-Spezifikation an:

curl \
  -F 'tracking_spec=[{action.type:"offline_conversion", dataset:["123"]}]' \
  -F 'access_token=<SYSTEM_USER_ACCESS_TOKEN>' \
  https://graph.facebook.com/<API_VERSION>/<AD_ID>

So aktualisierst du die Tracking-Spezifikation deiner Werbeanzeigen:

POST /<AD_ID>/?tracking_specs=[{"action.type":"offline_conversion","dataset": <OFFLINE_EVENT_SET_ID>}] HTTP/1.1
Host: graph.facebook.com

curl -X POST \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<AD_ID>/?tracking_specs=[{"action.type":"offline_conversion","dataset": <OFFLINE_EVENT_SET_ID>}]

Parameter

4. Lade Offline-Events hoch

Du solltest die Transaktion innerhalb von 62 Tagen nach der Conversion hochladen. So lädst du die Conversion-Daten hoch:

curl \
  -F 'access_token=SYSTEM_USER_ACCESS_TOKEN' \
  -F 'upload_tag=store_data' \
  -F 'data=[ \
    { 
      match_keys: {"phone": ["HASH1","HASH2"], "email": ["HASH3","HASH4"]}, 
      currency: "USD", 
      value: 16,
      event_name: "Purchase",
      event_time: 1456870902,
      contents: [
        {id: "A", quantity: 1},
        {id: "B", quantity: 2},
        {id: "C", quantity: 1}
      ]
      custom_data: {             
      },
    }, 
    { 
      match_keys: {"lead_id": "12345"}, 
      event_name: "Lead",
      event_time: 1446336000,
      contents: [
        {id: "A", quantity: 1},
        {id: "B", quantity: 2},
        {id: "C", quantity: 1}
      ]
      custom_data: {
        event_source: "email",
        action_type: "sent_open_click",
        email_type: "email_type_code", 
        email_provider: "gmail_yahoo_hotmail",
      }
    }, 
  ]'
  https://graph.facebook.com/VERSION/OFFLINE_EVENT_SET_ID/events

Führe eine HTTP POST-Anfrage durch, um Conversions zu senden:

POST /<OFFLINE_EVENT_SET_ID>/events HTTP/1.1
Host: graph.facebook.com

curl -X POST \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<OFFLINE_EVENT_SET_ID>/events

Parameter

Verwende dasselbe upload_tag für alle Upload-API-Aufrufe in einem Batch, um diese zu gruppieren. So kannst du Event-Uploads einfacher debuggen. Du solltest bei allen Event-Uploads in mehreren API-Aufrufen so vorgehen.

Parameter in data:

Du kannst Informationen beispielsweise mit dem Feld data hochladen:

{
  match_keys: MATCH_KEYS,
  event_time: EVENT_TIME,
  event_name: "Purchase",
  value: 400,
  currency: "USD",
  contents: [
    {
        id: "A",
        quantity: 1,
        brand: "brand_of_A",
        category: "Apparel & Accessories | Clothing",
        price: 100,
    },
    {
        id: "B",
        quantity: 2,
        brand: "brand_of_B",
        category: "Apparel & Accessories | Shoes",
        price: 50,
    },
    {
        id: "C",
        quantity: 1,
        brand: "brand_of_C",
        category: "Apparel & Accessories | Jewelry | Watches",
        price: 200,
    }
  ],
}

Verwende dasselbe upload_tag für alle Upload-API-Aufrufe in einem Batch, um diese zu gruppieren. So kannst du Event-Uploads einfacher debuggen. Du solltest bei allen Event-Uploads in mehreren API-Aufrufen so vorgehen.

Abgleichsschlüssel

match_keys ist eine Gruppe von IDs für den Abgleich von Personen zur Attribution. Infos zum Normalisieren und Hashing deiner Daten findest du unter Custom Audiences aus CRM-Daten. Nur SHA256 wird unterstützt, und wir akzeptieren ausschließlich gehashte Daten.

Die Antwort:

Bei Fehlern erscheint eine Ausnahmemeldung mit ungültigen Einträgen und dem Grund, warum diese ungültig sind. Behebe die Fehler oder überspringe die Datenzeilen mit Fehlern und wiederhole den API-Aufruf.

Upload-Statistiken anzeigen

Ein Business Manager-Administrator oder Systemnutzer, der das Offline Event Set erstellt hat, kann Upload-Statistiken abrufen. Diese Daten sind auch für jeden Administrator des ad_account verfügbar, das mit der Offline-Event-Gruppe verbunden ist.

So zeigst du Statistiken zu Offline Event Sets an, wie gültige Einträge und abgeglichene Einträge:

GET /<OFFLINE_EVENT_SET_ID>/uploads HTTP/1.1
Host: graph.facebook.com

curl -X GET -G \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<OFFLINE_EVENT_SET_ID>/uploads

Sieh dir tägliche Aufschlüsselungen von Offline-Events im Offline Events Manager im Business Manager an. Tätige diesen Aufruf, um genauere Aufschlüsselungen zu erhalten:

GET /<OFFLINE_EVENT_SET_ID>/stats HTTP/1.1
Host: graph.facebook.com

curl -X GET -G \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<OFFLINE_EVENT_SET_ID>/stats

Parameter

Offline-Custom Conversions erstellen

Für selbstdefinierte Offline-Conversions ist derzeit kein Backfill möglich. Wir ordnen keine Daten von Events zu, die du vor dem Erstellen der selbstdefinierten Conversion hochgeladen hast. Du kannst keine Daten zu selbstdefinierten Offline-Conversions für die Optimierung der Anzeigenauslieferung verwenden. Mehr dazu erfährst du unter Selbstdefinierte Conversion, Referenz.

Um eine Custom Conversion anhand deiner Offline-Events zu erstellen, tätige eine POST-Anfrage:

POST /act_<ACCOUNT_ID>/customconversions HTTP/1.1
Host: graph.facebook.com

curl -X POST \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/act_<ACCOUNT_ID>/customconversions

Parameter

Die Antwort bei Erfolg:

{
  "id": <CUSTOM_CONVERSION_ID>
}

Mit selbstdefinierten Daten messen

Mit dem custom_data-Feld kannst du Regeln erstellen, die später bestimmen, ob eine Conversion zählt. Das ist ähnlich wie Offline-Custom Audiences. Du kannst maximal 40 Custom Conversions pro Werbekonto verwenden.

So nimmst du beispielsweise die Produktkategorie in Uploads mit custom_data auf:

data=[
  {
    match_keys: {"phone": ["<HASH>","<HASH>"], "email": ["<HASH>","<HASH>"]}, 
    currency: "USD", 
    value: 16,
    event_name: "Purchase",
    event_time: 1456870902,
    custom_data: {
      product_category: "ICECREAM",
    },
  },
]

Verwende dann custom_data.{YOUR_CUSTOM_PARAM}, um eine Custom Conversion-Regel zu erstellen:

curl \
  -F 'name=Ice Cream Purchasers' \
  -F 'custom_event_type=Purchase' \
  -F 'event_source_id=<OFFLINE_EVENT_SET_ID>' \
  -F 'rule={"and": [{"event_name":{"eq":"Purchase"}},{"custom_data.product_category":{"i_contains":"ICECREAM"}}]}' \
  -F 'access_token=<ACCESS_TOKEN>' \

"https://graph.facebook.com/<API_VERSION>/act_<ACCOUNT_ID>/customconversions"

Offline-Conversions für Partner

Führe die folgenden Schritte aus, um Offline-Conversion-Events der Werbeanzeige deines Kunden zuzuordnen. Die API-Aufrufe für die meisten dieser Schritte sind genau so wie beim Verwalten der eigenen Offline Event Sets und Kampagnen.

1. Partner – Offline Event Set erstellen
2. Partner – Event-Gruppe mit dem Business Manager des Kunden teilen
3. Kunde – Berechtigung zum Offline-Tracking für das Werbekonto zuweisen
4. Kunde – Offline-Tracking für Werbeanzeigen festlegen
5. Partner – Offline-Events hochladen, Statistiken anzeigen
6. Partner – Werbeanzeigen-Insights für Kunden anzeigen

Diese Schritte variieren abhängig davon, wie deine Partner- oder Agenturberechtigungen bei Werbekonten von Kunden eingerichtet sind:

• Du kannst Eigentümer*in aller Werbekonten, Event-Gruppen und anderer Elemente deines Kunden sein.
• Du kannst dazu berechtigt sein, bestimmte Handlungen mit den Elementen deines Kunden auszuführen.

Informationen zum Einrichten dieser Berechtigungen findest du unter Business Manager-Elemente.

Partner – Event-Gruppe teilen

Teile die Event-Gruppe mit dem Business Manager deines Kunden. Dann kann dein Kunde die Event-Gruppe zum Tracking von Werbeanzeigen verwenden.

GET /<OFFLINE_EVENT_SET_ID>/agencies HTTP/1.1
Host: graph.facebook.com

curl -X GET -G \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<OFFLINE_EVENT_SET_ID>/agencies

Parameter

Kunde – Berechtigung zum Offline-Tracking für das Werbekonto zuweisen

Teile Offline Event Sets, die von einem Partner erstellt wurden, mit dem Kunden. Du musst der Business Manager-Administrator oder der Admin-Systemnutzer sein, der das Offline Event Set erstellt hat, um das Tracking für Werbeanzeigen unter einem Werbekonto zu aktivieren. Wenn du Administrator für das Werbekonto bist, das mit dem Offline Event Set verbunden ist, kannst du das ebenfalls machen. Für diesen API-Aufruf benötigt das Unternehmen Zugriff auf das Offline Event Set.

Mit dem folgenden Aufruf kannst du Berechtigungen für das Tracking und Anzeigen von Offline-Events einem Werbekonto zuweisen:

POST /<OFFLINE_EVENT_SET_ID>/adaccounts HTTP/1.1
Host: graph.facebook.com

curl -X POST \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<OFFLINE_EVENT_SET_ID>/adaccounts

Parameter

Externe IDs angeben

Es kann vorkommen, dass du deine eigene externe ID für einen Kunden angibst und diesen einer Person zuordnest. Verwende dazu extern_id gemäß den folgenden Richtlinien.

Datenpartner, die den Abgleichsprozess durchlaufen haben, können die Partner-ID als Namespace-ID und extern_id als deine tpid verwenden.

Gib nur match_keys an.

Wir nutzen match_keys, um zu ermitteln, ob die von dir geteilten Conversion-Daten einem*einer Meta-Nutzer*in zugeordnet werden können. Wenn du match_keys bereitstellst, kannst du keinen namespace_id-Parameter bereitstellen.

Gib sowohl match_keys als auch extern_id an

Wir nutzen match_keys, um Personen auf Meta zu finden und Zuordnungen von {dataset_id, extern_id} zu {facebook_user_id} weiterzuleiten. Wenn du match_keys und extern_id bereitstellst, kannst du keine namespace_id bereitstellen.

Gib nur extern_id an.

Wenn du bereits Daten mit match_keys und extern_id gesendet hast, nutzt Meta {dataset_id, extern_id} zum Abrufen einer {facebook_user_id}.

Gib namespace_id an

Der namespace_id-Parameter gilt für den gesamten API-Aufruf. Damit kannst du ein anderes Offline Event Set referenzieren, das für eine Business- oder eine Partnerprofil-ID zugänglich oder in deren Besitz ist. Wenn du bereits Daten mit match_keys und extern_id gesendet hast, nutzt Meta {namespace_id, extern_id} zum Abrufen einer {facebook_user_id}. Du solltest nur eine extern_id pro Datenzeile angeben.

Insights und Attribution

Sieh dir Offline-Events an, die einer Werbeanzeige zugeordnet sind, die jemand angesehen oder angeklickt hat. Wir ordnen Offline-Conversions nach mehr als einem Tag zu. Das bedeutet, dass du dein Attributionsfenster auf 28d_view setzen oder action_attribution_windows=['28d_view']' festlegen musst. Andernfalls siehst du keine Conversions in Berichten. Mehr dazu erfährst du unter Insights API und Insights-Leitfaden.

GET /act_<ADACCOUNT_ID>/insights HTTP/1.1
Host: graph.facebook.com

curl -X GET -G \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/act_<ADACCOUNT_ID>/insights

Parameter

Ergebnisse sehen wie folgt aus:

{
  "data": [
    {
      "date_start": "2015-12-01",
      "date_stop": "2015-12-01",
      "actions": [
        {
          "action_type": "offline_conversion.purchase",
          "value": 1
        },
        {
          "action_type": "offsite_conversion.lead",
          "value": 3
        },
      ],
      ...
    }
  ]
}

So zeigst du beispielsweise die Attribution an:

curl -G \
  -d 'access_token=<SYSTEM_USER_ACCESS_TOKEN>' \
  -d 'fields=unique_actions,action_values' \
  https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/insights

Das Ergebnis sieht wie folgt aus:

{
  "data": [
    {
      "unique_actions": [
        {
          "action_type": "link_click",
          "value": 94
        },
        {
          "action_type": "offline_conversion",
          "value": 1
        },
        {
          "action_type": "offline_conversion.purchase",
          "value": 1
        },
        {
....
          "value": 1
        }
      ],
      "action_values": [
        {
          "action_type": "offline_conversion.purchase",
          "value": 27.5
        },
        {
          "action_type": "offline_conversion",
          "value": 27.5
        }
      ],
      "date_start": "2016-06-06",
      "date_stop": "2016-06-07"
    }
  ],
  "paging": {
    "cursors": {
      "before": "MAZDZD",
      "after": "MAZDZD"
    }
  }
}

Datenverarbeitungsoptionen für Nutzer*innen in den USA

{
    "data": [
        {
            "event_name": "Purchase",
            "event_time": <EVENT_TIME>,
            "user_data": {
                "em": "<EMAIL>"
            },
            "custom_data": {
                "currency": "<CURRENCY>",
                "value": "<VALUE>"
            },
            "data_processing_options": []
        }
    ]
}

{
    "data": [
        {
            "event_name": "Purchase",
            "event_time": <EVENT_TIME>,
            "user_data": {
                "em": "<EMAIL>",
                "client_ip_address": "256.256.256.256"
            },
            "custom_data": {
                "currency": "<CURRENCY>",
                "value": "<VALUE>"
            },
            "data_processing_options": ["LDU"],
            "data_processing_options_country": 0,
            "data_processing_options_state": 0
        }
    ]
}

{
    "data": [
        {
            "event_name": "Purchase",
            "event_time": <EVENT_TIME>,
            "user_data": {
                "em": "<EMAIL>"
            },
            "custom_data": {
                "currency": "<CURRENCY>",
                "value": "<VALUE>"
            },
            "data_processing_options": ["LDU"],
            "data_processing_options_country": 1,
            "data_processing_options_state": 1000
        }
    ]
}

Erfahre mehr über Datenverarbeitungsoptionen.