Conversions API Gateway für mehrere Konten – Control Plane API

Partnerintegration

Übersicht

Die Control Plane API des Conversions API Gateway für mehrere Konten besteht aus einer Reihe von GraphQL APIs, die über die Gateway-Instanz verfügbar gemacht werden. Mit dieser API können Entwickler*innen Konten, Datenquellen und andere Konfigurationen einer Gateway-Instanz programmgesteuert verwalten. Partner können die API integrieren, um sie in ihre UI für Werbetreibende einzubauen und ihren Werbetreibenden einen nahtlosen Freischaltungs- und Management-Flow zu bieten.

Mögliche Anwendungsfälle:

Werbetreibende nutzen die UI des Partners für das Freischaltung im Gateway und führen weiterführende Handlungen über die Admin-Einstellungen des Gateways durch. Dies erfordert eine teilweise Integration der Control Plane API.
Werbetreibende führen alle Handlungen in der UI des Partners aus, einschließlich Freischaltung im Gateway und weiterführende Handlungen. Dies kann ein guter Anwendungsfall für Partner sein, die die Gateway-UI nicht zur Verfügung stellen, aber dennoch das Gateway als Service für die Werbetreibenden anbieten möchten. Dies erfordert die vollständige Integration der Control Plane API.

Weitere Informationen zu den Integrationsschritten findest du im nachfolgenden Abschnitt.

Die Begriffe Control Plane API des Conversions API Gateway für mehrere Konten oder Gateway werden in diesem Dokument synonym verwendet.

Integrationsleitfaden

Je nach Anwendungsfall sind zwei Integrationspfade möglich (wie im folgenden Diagramm dargestellt):

Teilweise Integration der Control Plane API. Dies erfordert keine Authentifizierung von Werbetreibenden.
Vollständige Integration mit Control Plane API. Dies erfordert eine Authentifizierung von Werbetreibenden, entweder über die Meta Business Extension (MBE) oder durch manuelle Generierung von Token.

Voraussetzungen

Für beide Integrationspfade muss der Partner zunächst die folgenden Schritte ausführen:

Schritt 1: Sich als Host der Gateway-Instanz freischalten lassen

Schritt 2: API-Kontonamen und API Secret Key generieren

Gehe zu:

https://<Conversions API Gateway Endpoint>/hub/

Navigiere zu Hosteinstellungen, wähle die Seite API-Konten verwalten aus und klicke auf den Button API-Konto hinzufügen.

Gib dein Passwort erneut ein. Klicke auf Weiter.

Gib den Namen des API-Kontos ein. Klicke auf Weiter.

Der Kontoname darf nur aus Buchstaben und Zahlen bestehen und darf keine Leerzeichen enthalten. Die maximale Länge beträgt 20 Zeichen.

Kopiere und speichere den generierten Secret Key. Er kann nicht erneut angezeigt werden.

Um ein API-Konto zu entfernen, klicke auf API-Konto löschen. Bitte beachte, dass dieser Vorgang nicht rückgängig gemacht werden kann und möglicherweise Störungen in Anwendungen oder Dienstleistungen von Werbetreibenden verursacht, die die API verwenden.

Teilweise Integration

Ein Anwendungsfall für die teilweise Integration:

Der Werbetreibende meldet sich über die UI des Partners für den Gateway-Service an.
Der Partner generiert einen Einladungslink, der vom Werbetreibenden verwendet werden kann, um ein Passwort einzurichten und das Gateway-Konto zu erstellen.
Der Werbetreibende nutzt Funktionen in der Gateway-UI, um Datenquellen, Kontonutzer*innen, Domains und Routing zu verwalten oder andere Handlungen durchzuführen.
Der Partner ruft die Kontonutzung des Werbetreibenden ab und stellt sie entsprechend in Rechnung.

Ein allgemeiner User-Flow kann wie im Folgenden dargestellt aussehen:

Zur Umsetzung des vorstehenden Flows kann der Partner eine Untermenge der Control Plane API integrieren, einschließlich:

API-Zugriffsschlüssel abrufen
Konto für Werbetreibende erstellen
Informationen zur Kontonutzung abrufen, zum Beispiel für Abrechnungszwecke

Vollständige Integration

Ein Anwendungsfall für die vollständige Integration:

Der Werbetreibende meldet sich über die UI des Partners für den Gateway-Service an.
Der Partner schaltet das Gateway-Konto des Werbetreibenden frei und erhält die Berechtigung, das Konto zu verwalten. Der Werbetreibende autorisiert den Partner mithilfe der Meta Business Extension (MBE) oder durch manuelle Generierung eines Token.
Der Werbetreibende kann Datenquellen sowie Kontonutzer*innen, Domains und Routing in der UI des Partners verwalten.
Der Partner ruft die Kontonutzung des Werbetreibenden ab und stellt sie entsprechend in Rechnung.

Ein allgemeiner User-Flow kann wie im Folgenden dargestellt aussehen:

Für diesen Integrationspfad müssen Partner eine Autorisierung anfordern und Systemnutzer-Zugriffsschlüssel per Authentifizierung abrufen, um Events im Namen der Werbetreibenden zu senden.

Authentifizierung

Partner haben die folgenden zwei Authentifizierungsoptionen für Meta-Pixel, die nicht von ihnen verwaltet werden:

Option 1 – Meta Business Extension (MBE)

Bevor du beginnst, ist Folgendes erforderlich:

Du musst alle Voraussetzungen für die Implementierung von MBE erfüllen.
Du musst deine*n gewählte*n Meta-Vertreter*in kontaktieren, um deine App zur Positivliste für eine private Berechtigung hinzuzufügen: open_bridge_configuration_management

MBE stellt einen Endpunkt für den Abruf von Systemnutzer-Zugriffsschlüsseln bereit, die im Business Manager des Werbetreibenden erstellt wurden. Partner können mit Schritt 4 des MBE-Integrationsleitfadens fortfahren. Stelle Folgendes sicher:

Der Wert des Kanalparameters im Setup-Konfigurationsobjekt ist auf CONVERSIONS_API_GATEWAY_ADVERTISER festgelegt.
Du kannst die Webhook-Antwort nach Abschluss der Freischaltung erhalten.
Verwende den Zugriffsschlüssel, der über MBE zurückgegeben wird, und konvertiere ihn in einen Systemnutzer-Zugriffsschlüssel, indem du einen zusätzlichen API-Aufruf tätigst.
Speichere eine Kopie von external_business_id, pixel_id, business_id und des Systemnutzer-Zugriffsschlüssels in deinem System.

Option 2 – Systemnutzer-Zugriffsschlüssel des Kunden

Mit dieser Option können Partner den Werbetreibenden Folgendes ermöglichen:

Manuell einen Systemnutzer-Zugriffsschlüssel über die Conversions API innerhalb der Einstellungen in Events Manager (EM) erstellen
pixel_id, business_id und Systemnutzer-Zugriffsschlüssel mit dem Partner teilen und eine Kopie davon speichern

Integration

Partner können den kompletten Satz der Control Plane API integrieren. Weitere Einzelheiten findest du in der API-Referenz.

API- und UI-Parität

Wir setzen die API- und UI-Parität durch, indem wir dieselben API-Endpunkte verfügbar machen, die in der Gateway-UI verwendet werden. Allerdings kann sich jeder API-Endpunkt, der nicht in der API-Referenz abgedeckt ist, während der zukünftigen Entwicklung ändern. Um die unerwarteten Auswirkungen auf das Minimum zu beschränken, geben diese nicht abgedeckten API-Endpunkte Fehlercode: 418 zurück. Du kannst die API weiterhin nutzen, aber auf eigene Gefahr.