Authentifizierung von Business-Apps

Die auf Facebook-Benutzeroberflächen verfügbaren Business-Apps sind der Ort, an dem kleine Unternehmen externe Business-Apps entdecken und eine Verbindung herstellen können, um zu niedrigen Technikkosten Unternehmens-Tools einzurichten, die sie beim Wachstum und bei der Erreichung der Geschäftsziele unterstützen.

Im Gegensatz zum Unternehmens-Login gibt es, weil der Business-Apps-Vorgang von unseren Oberflächen aus gestartet wird, einen zusätzlichen Schritt, d. h., der Nutzer muss sich über einen Pop-up-Browser auf deiner Plattform anmelden, um sich zu authentifizieren und sein Unternehmen (das mit einem von dir festgelegten external_business_id identifiziert wird) für eine Verbindung auszuwählen. Nach einer erfolgreichen Authentifizierung wird der Nutzer wieder zum Vorgang weitergeleitet, um das Onboarding abzuschließen.

Wenn deine App auf unserer Business-Apps-Oberfläche angezeigt werden soll, musst du eine Authentifizierungs-URL und einen Webhook-Endpunkt erstellen und diese beiden über das Developer Panel einrichten und validieren lassen.

Für alle Apps muss eine Integrationsprüfung angefordert werden. Sobald die FBE-Integration genehmigt wurde, steht deine App öffentlichen Nutzern zur Verfügung.

Implementierung der Authentifizierungs-URL

Bei Business-Apps wird ein ähnlicher Vorgang wie beim Unternehmens-Login auf einer Facebook-Seiten-Oberfläche, auf Instagram und in der Facebook Business Suite gestartet. Um diesen Vorgang zu ermöglichen und deine App hier aufzuführen, musst du eine benutzerdefinierte Authentifizierungs-UI bereitstellen, über die der*die Nutzer*in auf deiner Website sein*ihr Unternehmen auswählen kann und dann wieder zum Facebook-, Instagram- oder Facebook Business Suite-Vorgang weitergeleitet wird.

So funktioniert’s

1. Stelle einen benutzerdefinierten URL-Endpunkt (Authentifizierungs-URL) zur Verfügung, der den Authentifizierungsvorgang deiner Plattform lädt.
• Deine Authentifizierungs-URL sollte den*die Nutzer*in (Unternehmensinhaber*in) zu einem Login-Vorgang auf deiner Plattform führen.
• Stelle die Möglichkeit zur Verfügung, ein neues Konto auf deiner Plattform zu registrieren (z. B. „Registrieren“). Der*die Nutzer*in sollte nach der Registrierung zurück zu Facebook weitergeleitet werden, um die Verknüpfung seines*ihres Kontos abzuschließen.
• Wenn du in deiner Plattform mehrere Unternehmen pro Konto unterstützt, sollte die Authentifizierungs-URL nach einem erfolgreichen Login dann eine UI anzeigen, über die der*die Nutzer*in auswählen kann, welches Unternehmen auf deiner Plattform mit seinen*ihren Facebook-Assets verknüpft werden soll.
Beispiel – Authentifizierungs-URL

https://yourwebsite.com/fbe-auth

2. Facebook lädt während des Onboarding-Vorgangs deine bereitgestellte Authentifizierungs-URL und hängt am Ende den Abfrageparameter redirect_uri an (dies ist eine Weiterleitungs-URI, die zusätzliche Abfrageparameter enthalten kann):

   https://yourwebsite.com/fbe-auth?redirect_uri=<an_encoded_redirect_uri_with_query_params>

   Beispiel – Eine codierte Weiterleitungs-URI, die möglicherweise an den Abfrageparameter redirect_uri angehängt wird:

   https://www.facebook.com/local/dev/transaction_tool_selector/redirect?app_id=<int_value>&app_name=<string_value>&page_id=<int_value>

   Am Ende dieses Schritts lädt Facebook deine Authentifizierungs-URL mit dem angehängten codierten Abfrageparameter redirect_uri, der folgendermaßen aussehen kann:

   https://yourwebsite.com/fbe-auth?redirect_uri=https%3A%2F%2Fwww.facebook.com%2Flocal%2Fdev%2Ftransaction_tool_selector%2Fredirect%3Fapp_id%3D123%26app_name%3DSample%26page_id%3D456

   Wichtiger Hinweis: Damit keine Nutzer*innendaten an andere weitergegeben werden, verwende nur dann eine Weiterleitung an die redirect_uri, wenn sie dem folgenden regulären Ausdruck entspricht:

   https?:\/\/(www\.|m\.|l\.|web\.|business\.)?(\d{4,5}\.od\.)?(business\.)?(facebook|instagram|whatsapp)\.com(\/.*)?

3. Nachdem der*die Nutzer*in den Login-/Registrierungsvorgang abgeschlossen und auf deiner Plattform ein Unternehmen ausgewählt hat (sofern zutreffend), leite ihn*sie zur URL aus „redirect_uri“ weiter, nachdem du ein codiertes extras-Objekt als Abfrageparameter angehängt hast (wie beim Unternehmens-Login), wobei business_config und setup darin definiert sind (abhängig von den Onboarding-Konfigurationen, die du implementieren möchtest):

   https://www.facebook.com/local/dev/transaction_tool_selector/redirect?app_id=<int_value>&app_name=<string_value>&page_id=<int_value>&extras=<an_encoded_json_string>

iframe-Authentifizierung

Um ein nahtloseres Nutzer*innenerlebnis innerhalb von Business-Apps zu ermöglichen und die Erstellung neuer Konten auf deiner Plattform besser zu unterstützen, solltest du das Laden deiner Authentifizierungs-URL in einem iframe auf einer Facebook-Oberfläche ermöglichen. Weitere Informationen findest du in den Implementierungsrichtlinien und den Spezifikationen zu „postMessage“ in der iframes-Dokumentation.

Webhook-Implementierung

Mit Webhooks erhältst du HTTP-Benachrichtigungen in Echtzeit, die dich über Änderungen an bestimmten Objekten im Facebook Social Graph informieren. Für FBE bedeutet das, dass du, nachdem ein Nutzer mit deiner App (z. B über Business-Apps) FBE installiert oder deinstalliert hat, über Webhooks Details zu dieser Aktion erhältst.

Du musst einen Endpunkt auf einem sicheren Server erstellen, der Anforderungen von Facebook verarbeiten kann. Diese Anforderung gilt für alle Plattformpartner, die ihre App bei den Business-Apps zur Verfügung stellen wollen. Details zur Erstellung dieses Endpunkts findest du im Webhook-Implementierungsleitfaden.

Webhook-Setup und -Validierung

Sobald dein Webhook-Endpunkt fertig ist, musst du für die Einrichtung und Validierung wie folgt vorgehen:

1. Verwende die Karte Webhooks im Abschnitt Facebook Business Extension -> Einrichtung des App-Dashboards, um den Endpunkt zu validieren und den Webhook fbe_install zu abonnieren. Weitere Details findest du im Webhook-Implementierungsleitfaden.
2. Sobald das Webhooks-Produkt richtig konfiguriert ist, wird der Kreis oben rechts auf der Karte grün und es wird ein Häkchensymbol angezeigt.

Setup und Validierung über das Developer Panel

Das Facebook Business Extension Developer Panel ist ein Produkt in deinem Developer App Dashboard. Sobald deine Apps über FBE-Funktionen verfügen, solltest du über das Developer Panel deine Authentifizierungs-URL und deinen Webhook-Endpunkt einrichten und validieren und Details zu den Vorteilen deiner App für ein Unternehmen hinzufügen.

Setup und Validierung der Authentifizierungs-URL

Sobald die Authentifizierungs-URL fertig ist, musst du für die Einrichtung und Validierung wie folgt vorgehen:

1. Gehe im Dashboard deiner App zum FBE Developer Panel. Hinweis: Wenn du es nicht konfiguriert hast, findest du hier Anweisungen, um es hinzuzufügen.
2. Klicke auf den Tab Setup und suche nach der Karte Business Apps-Oberfläche.
3. Aktiviere das Kontrollkästchen Meine App in der Business-Apps-Oberfläche anzeigen.
4. Gib im Feld Authentifizierungs-URL für App Store deine Authentifizierungs-URL ein.
5. Klicke auf den Button Authentifizierung testen.
• In einem Pop-up-Fenster wird deine URL geladen, damit du sehen kannst, wie sie auf Business-Apps-Oberflächen aussieht.
• Fahre mit dem Login und (gegebenenfalls) der Unternehmensauswahl fort.
• Nach der Weiterleitung wird das Pop-up-Fenster geschlossen. Wenn deine Implementierung Fehler enthält (z. B. ungültige Werte bei Ergänzungen), werden diese unten auf dieser Karte angezeigt, damit du weißt, was du korrigieren musst. Das Feature Authentifizierung testen validiert nur den Input unter redirect_uri und führt keine FBE-Installation durch.
6. Sobald die Implementierungsschritte und die zusätzliche Konfiguration wie erwartet implementiert wurden, wird dieser Schritt als gültig markiert (grünes Häkchen oben rechts auf der Karte). Dadurch kannst du diesen Onboarding-Vorgang direkt in Facebook vollständig testen (FBE installieren) (siehe Abschnitt unten).

Ende-zu-Ende-Tests

Sobald deine Authentifizierungs-URL und der Webhook-Endpunkt im Developer Panel erfolgreich eingerichtet und validiert wurden, kannst du, bevor du live gehst, über deine App den kompletten Onboarding-Vorgang testen. Dies ist direkt von der Facebook Business Suite oder der Facebook-Seiten-Oberfläche aus wie folgt möglich:

Von der Facebook Business Suite

1. Rufe die Facebook Business Suite auf.
2. Klicke auf der linken Leiste auf Weitere Tools und anschließend auf Business-Apps.
3. Alle verfügbaren Apps werden hier aufgeführt. Deine Apps werden unter der Kategorie aufgeführt, die du auf dem Tab „Setup“ für das Developer Panel als Branche(n) ausgewählt hast.
4. Deine App ist mit dem Label Nur Test - nicht öffentlich markiert. Das bedeutet, dass sie nur zu Testzwecken für die Nutzer, die eine Rolle in deiner App haben, und noch nicht für öffentliche Nutzer, zur Verfügung steht.
5. Klicke auf Verbinden und starte den Test des Erlebnisses von deiner Authentifizierungs-URL:
   • Der Onboarding-Vorgang umfasst reale FBE-Installationen und löst die Webhook-Benachrichtigungen aus.

Von der Facebook-Seiten-Oberfläche

1. Gehe auf eine Facebook-Seite, auf die du Administratorzugriff hast.
2. Klicke auf der linken Leiste deiner Facebook-Seite auf Business-Apps.
3. Alle verfügbaren Apps werden hier aufgeführt. Deine Apps werden unter der Kategorie aufgeführt, die du auf dem Tab „Setup“ für das Developer Panel als Branche(n) ausgewählt hast.
4. Deine App ist mit dem Label Nur Test - nicht öffentlich markiert. Das bedeutet, dass sie nur zu Testzwecken für die Nutzer, die eine Rolle in deiner App haben, und noch nicht für öffentliche Nutzer, zur Verfügung steht.
5. Klicke auf Verbinden und starte den Test des Erlebnisses von deiner Authentifizierungs-URL:
   • Der Onboarding-Vorgang umfasst reale FBE-Installationen und löst die Webhook-Benachrichtigungen aus.

Mehr dazu

• So nutzt du einen Unternehmens-Login für FBE
• extras
• business_config
• setup
• Deinstallation von FBE