Asset-IDs und Zugriffsschlüssel abrufen

Nachdem der*die Nutzer*in die Facebook Business Extension installiert hat und du seinen*ihren Nutzer-Zugriffsschlüssel hast (der für API-Aufrufe für den Benutzer verwendet wird), musst du die Pixel-ID, Instagram Business-ID, Seiten-ID, Business Manager-ID, Werbekonto-ID, Katalog-ID (optional) oder den Zugriffsschlüssel von dem*der Nutzer*in abrufen, um die entsprechenden Features zu konfigurieren. Diese IDs werden für API-Endpunkte und Unternehmenskonfigurationen verwendet.

Mit der OBO-Lösung kann der Kunde den Zugriffsschlüssel abrufen, indem er auch den Zugriffsschlüssel des Admin-Systemnutzers des Business Managers des Partners verwendet, anstatt nur den des Administrators des Business Managers des Kunden.

IDs für API-Endpunkte und Unternehmenskonfigurationen sammeln

So gelangst du an diese Informationen:

• Webhook: erforderlich für alle Plattform-Partner, die im App Store aufgeführt werden möchten
• FBE Installs API-Endpunkt: empfohlen für selbst gehostete Unternehmen

Erstellung des Systemnutzers

Nachdem ein*e Nutzer*in FBE installiert hat, generiert die Erweiterung im Business Manager des Kunden einen Systemnutzer für Mitarbeiter*innen. Die Benennung dieses neuen Systemnutzers erfolgt nach folgendem Schema: {App Name} System User (FBE).

Systemnutzer stellen Server oder Software dar, die API-Aufrufe an Assets durchführen, die im Besitz eines Business Managers sind oder von diesem verwaltet werden.

Dieser Systemnutzer hat Berechtigungen für alle zugewiesenen FBE-Assets mit den folgenden Aufgabenberechtigungen:

1. Seite: 'MANAGE'
2. Werbekonto: 'MANAGE'
3. Katalog: 'MANAGE'
4. Pixel: 'EDIT'

Zugriffsschlüssel für Systemnutzer mit der API abrufen

Wenn du einen Zugriffsschlüssel für Nutzer*innen über einen Webhook oder den Unternehmens-Login nach einer FBE-Installation erhältst, kannst du denselben Zugriffsschlüssel verwenden, um den Systemnutzer-Zugriffsschlüssel des Business Managers abzurufen. Tätige hierfür den folgenden API-Aufruf:

curl -X POST \
  -F 'app_id={app_id}' \
  -F 'scope={permissions}' \ 
  -F 'access_token={access_token}' \
  -F 'fbe_external_business_id={fbe_external_business_id}' \
  https://graph.facebook.com/<API_VERSION>/<client_business_manager_id>/access_token

Verwende für das Feld scope die Berechtigung manage_business_extension. Je nach Anwendungsfall benötigst du möglicherweise auch ads_management oder catalog_management.

Für das Feld access_token kannst du einen Nutzer-Zugriffsschlüssel (user_access_token) oder den Zugriffsschlüssel des Admin-Systemnutzers im Business Manager des Partners (partner_bm_admin_system_user_token) übergeben. Erfahre mehr über Zugriffsschlüssel für Unternehmen.

Webhook

Um aktualisierte Eingabeaufforderungen zu Installationen, Deinstallationen und Neukonfigurationen von FBE zu erhalten, lösen wir jedes Mal Webhook-Events aus, wenn eines deiner Unternehmen FBE installiert, ändert oder deinstalliert.

Jedes Mal, wenn ein*eine Nutzer*in FBE installiert oder ändert, sollte deine App die Webhook-Konfiguration überprüfen, um zu verstehen, welche Assets der*die Nutzer*in geändert, hinzugefügt oder aus der Verbindung mit deiner App entfernt hat. Das Verhalten deiner App sollte auf der Grundlage der aktuell verbundenen Assets aktualisiert werden.

Setup-Anforderungen

1. Erstelle einen Endpunkt auf einem sicheren Server, der Anfragen von Facebook verarbeiten kann. Verifizierungsanfragen (GET) und Event-Benachrichtigungen (POST).
2. Konfiguriere das FBE-Webhooks-Abonnement im App-Dashboard:
   • Gehe im Abschnitt Facebook Business Extension des App-Dashboards zum Tab Setup, scrolle nach unten zur Karte Webhooks und klicke dann auf Edit Callback URL (Rückruf-URL bearbeiten).
   • Gib die URL deines Endpunkts im Feld Rückruf-URL und im Feld Verify Token (Token verifizieren) einen String ein. Wir schließen diesen String in alle Verifizierungsanfragen ein.
   • Wenn du auf Bestätigen und speichern klickst, senden wir an deinen Endpunkt eine Verifizierungsanfrage, die du validieren musst.
   • Der fbe_install-Webhook wird automatisch abonniert. Die Karte verfügt außerdem über einen Umschalter, mit dem das Abonnement im Bedarfsfall deaktiviert werden kann.

Analysieren von Webhook-Events

Jedes Mal, wenn ein Installations-Webhook empfangen wird, muss deine Anwendung die folgenden Aktionen durchführen.

Bei Neuinstallationen

1. Speichere den Zugriffsschlüssel und seinen Typ und protokolliere die Assets, auf die deine App Zugriff erhalten hat.
2. Aktiviere auf Basis der gewährten Assets den Satz von Funktionen.
3. Wenn ein für eine bestimmte Funktion erforderliches Asset fehlt, deaktiviere nur diese Funktion. Wenn deine App beispielsweise Zugriff auf einen Katalog, aber nicht auf ein Pixel erhalten hat, implementiere nur die kataloggesteuerte Funktion, nicht die pixelgesteuerte Funktion.
4. Informiere den*die Nutzer*in durch ein Update, wie sich deine App basierend auf den Assets verhält, auf die er*sie Zugriff hat.

Bei bestehenden Installationen

1. Aktualisiere den Zugriffsschlüssel, seinen Typ und deine Aufzeichnung der Assets, auf die deine App Zugriff erhalten hat.
2. Aktualisiere den Satz von Funktionen, die deine App für dieses Unternehmen implementiert, basierend auf den gewährten Assets.
3. Informiere den*die Nutzer*in durch ein Update, wie sich deine App basierend auf den Assets verhält, auf die er*sie Zugriff hat.

Analysieren des Webhooks bei der Deinstallation

Führe die folgenden Schritte bei der Deinstallation aus:

1. Deaktiviere Funktionen, die deine App für dieses Unternehmen implementiert.
2. Informiere das Unternehmen über die Änderung an seiner Konfiguration.

Im Webhook-Payload ist Folgendes enthalten

Antwortfelder

Beispiel: Payload mit booleschem onsite_commerce_eligible-Feld

{
  "data": [{
    "ad_account_id": "<ad_account_id>",
    "business_manager_id": "<business_manager_id>",
    "catalog_id": "<catalog_id>",
    "commerce_merchant_settings_id": "<commerce_merchant_settings_id>",
    "onsite_eligible": true,
    "profiles": [
      "<page_id>",
      "<instagram_profile_id>"
    ],
    "pages": [
      "<page_id>"
    ],
    "instagram_profiles": [
      "<instagram_profile_id>"
    ],
    "pixel_id": "<pixel_id>",
    "token_type": "<token_type>",
    "installed_features": [
        {
            "feature_instance_id": "<unique_id>",
            "feature_name" : string, 
            "feature_type": enum,
            "connected_assets": {
                "ad_account_id": "<ad_account_id>",
                "business_manager_id": "<business_manager_id>",
                "catalog_id": "<catalog_id>",
                "commerce_merchant_settings_id": "<commerce_merchant_settings_id>",
                "ig_profile_id": "<instagram_profile_id>"               
                "page_id": "<page_id>",
                "pixel_id": "<pixel_id>",
            },
            "additional_info": {
                            "onsite_commerce_eligible": bool
                        },
                        {
                        "shop_status": array
                        },
                        {
                        "shop_status_info": array
                        }
                }
         ]
    }]
}

FBE Installation API

Für alle Unternehmen mit installierter FBE kannst du grundlegende Installationsinformationen abfragen (pixel_id und eine Liste mit Profilen mit einer IG Business ID and/or Page ID) mit dem folgenden Endpunkt:

Beispiel

CURL -X GET 'https://graph.facebook.com/<API_VERSION>/fbe_business/fbe_installs?fbe_external_business_id=<fbe_external_business_id>&access_token=<access_token>'

Antwort

{
  "data": [{
    "token_type": "<token_type>"
    "installed_features": [
        {
            "feature_instance_id": "<unique_id>",
            “feature_name” : string, 
            "feature_type": enum,
            "connected_assets": {
                “ad_account_id”: "<ad_account_id>",
                “business_manager_id”: "<business_manager_id>",
                “catalog_id”: "<catalog_id>",
                “commerce_merchant_settings_id”: "<commerce_merchant_settings_id>",
                “ig_profile_id”: "<instagram_profile_id>"               
                "page_id": "<page_id>",
                "pixel_id": "<pixel_id>",
            },
            "additional_info": {
                            "onsite_commerce_eligible": bool
                        },
                        {
                        "shop_status": array
                        },
                        {
                        "shop_status_info": array
                        }
                }
         ]
    }]
}

Die Antwort enthält die folgenden Felder. Diese stellen nun die zentrale Informationsquelle in der Liste „installed_features“ der verbundenen Assets dar:

Feature Configuration API-Antwort

Das Modell enthält die ID der Feature-Instanz für jedes Feature und neue Felder, die aus einem Array aller Features desselben Typs bestehen, die das Unternehmen installiert hat (z. B. mehrere Seiten-CATs).

Für nicht anpassbare Features wird nur eine Feature-Instanz-ID und die Kennzeichnung „Aktiviert“ angezeigt. Du kannst nur die anpassbaren Features mit einer POST-Anfrage aktualisieren.

Dieses Modell unterscheidet sich von der FBE Installation API, da es zusätzliche Feature-Informationen bereitstellt, die über die verknüpften Assets hinausgehen und auch den Status „Aktiviert“ sowie bestimmte Feature-Anpassungen umfassen. Nachdem du die FBE Installation API aufgerufen hast, verwende diese API, wenn weitere Informationen über den Status „Aktiviert“ oder die Konfigurationen des Features erforderlich sind.

Lesen

Du kannst den aktuellen Feature-Konfigurationsstatus jedes Unternehmens lesen, indem du die folgende Anfrage stellst:

CURL -X GET 
'https://graph.facebook.com/<API_VERSION>/fbe_business/?fbe_external_business_id=<fbe_external_business_id>&access_token=<access_token>'

Aktualisieren

Um alle Features zu aktualisieren, stelle die folgende POST-Anfrage:

CURL -i -X POST \   
  -F 'fbe_external_business_id=<fbe_external_business_id>' \
  -F 'business_config={business_config object}' \
  -F 'access_token=<access_token>' 
  "https://graph.facebook.com/<API_VERSION>/fbe_business"

Antwort

{
  "page_cta": {
     "feature_instance_id": id1,
     "enabled": true,
     "cta_button_text": "Book Now",
     "cta_button_url": "https://partner-site.com/foo-business1",
     "below_button_text": "Powered by FBE Partner"
  },
  "page_ctas": [
    {
        "feature_instance_id": id1,
        "enabled": true,
        "cta_button_text": "Book Now",
        "cta_button_url": "https://partner-site.com/foo-business1",
        "below_button_text": "Powered by FBE Partner"
    },
    {
        "feature_instance_id": id2,
        "enabled": true,
        "cta_button_text": "Book Now",
        "cta_button_url": "https://partner-site.com/foo-business2",
        "below_button_text": "Powered by FBE Partner"
    }
  ],
  “ig_cta”: {...}
  "ig_ctas": [{...}, {...}],
  “ads”: [
    {
      "feature_instance_id": id3,
      “enabled”: true,
    },
    {
      "feature_instance_id": id4,
      “enabled”: true,
    },
  ],
  ...
}

Nächste Schritte

• Unternehmens-Features konfigurieren
• Pixel-Events auslösen
• Katalog aktualisieren