Hinzufügen des SDK für Messenger-Erweiterungen

Das SDK für Messenger-Erweiterungen bietet nützliche Messenger-spezifische Features für jede Website oder Web-App, die in der Messenger-Webansicht geöffnet wird. Mit dem SDK kannst du Informationen zu der Person abrufen, die die Webansicht geöffnet hat, Inhalte in Messenger-Unterhaltungen teilen und eine tiefgehende Integration in die Messenger-UI vornehmen.

Verfügbare Features

Die folgenden Features stehen in der Messenger-Webansicht zur Verfügung, wenn du das SDK für Messenger-Erweiterungen hinzugefügt hast. Beachte, dass die tatsächliche Verfügbarkeit der Features von der Messenger-Version und dem Gerät abhängt.

Funktion	Beschreibung
getContext()	Rufe Unterhaltungskontext wie z. B. die seitenspezifische Nutzungs-ID der Person ab, die die Webansicht geöffnet hat.
requestCloseBrowser()	Schließe die Webansicht und kehre zur Messenger-Unterhaltung zurück.
askPermission()	Fordere Berechtigungen an, um beispielsweise Profilinformationen einer Person abzurufen.
getGrantedPermissions()	Überprüfe aktuell gewährte Berechtigungen.
getSupportedFeatures	Überprüfe, welche Features, wie z. B. Zahlungen, in der Webansicht auf dem aktuellen Gerät unterstützt werden.

Ausführliche Informationen zur Verwendung dieser Features findest du in der Referenz zum SDK für Messenger-Erweiterungen.

Installieren des SDK

1. Deine Domain auf die Positivliste setzen

Um Messenger-Erweiterungen in deinem Bot zu verwenden, musst du zunächst die Domains, von denen die Seite bereitgestellt wird, auf die Positivliste setzen. Aus Sicherheitsgründen müssen alle Domains auf deiner Webseite zu den Domains auf der Positivliste hinzugefügt werden. Weitere Informationen hierzu findest du in der Referenzdokumentation dazu, wie du Domains auf die Positivliste setzen kannst.

Mit der folgenden API kannst du eine Domain programmgesteuert zu einer Positivliste hinzufügen:

 
curl -X POST -H "Content-Type: application/json" -d '{
  "whitelisted_domains":[
    "https://petersfancyapparel.com"
  ]
}' "https://graph.facebook.com/v21.0/me/messenger_profile?access_token=PAGE_ACCESS_TOKEN"

Wenn der Vorgang erfolgreich ist, sendet die Messenger Profile API die folgende Antwort:

{"result":"success"}

2. Das JS-SDK für Messenger-Erweiterungen einbinden

Füge mit dem Code unten das Javascript-SDK für Messenger-Erweiterungen auf der Seite hinzu, die in der Webansicht geladen wird. Du solltest ihn direkt nach dem öffnenden body -Tag auf jeder Seite einfügen, auf der er geladen werden soll:

(function(d, s, id){
  var js, fjs = d.getElementsByTagName(s)[0];
  if (d.getElementById(id)) {return;}
  js = d.createElement(s); js.id = id;
  js.src = "//connect.facebook.net/en_US/messenger.Extensions.js";
  fjs.parentNode.insertBefore(js, fjs);
}(document, 'script', 'Messenger'));

3. Auf das SDK-Lade-Event warten

window.extAsyncInit() wird aufgerufen, wenn das Laden des JS-SDK für Messenger-Erweiterungen abgeschlossen ist. Du kannst dies als Trigger nutzen, um weitere im SDK verfügbare Funktionen aufzurufen.

window.extAsyncInit = function() {
  // the Messenger Extensions JS SDK is done loading 
};

Verwenden des SDK im Messenger-Web-Client

Das SDK für Messenger-Erweiterungen wird sowohl auf mobilen als auch auf Desktop-Messenger-Clients unterstützt. Du musst jedoch möglicherweise Folgendes bedenken, damit es funktioniert.

Außerdem kannst du mit der window.name -Eigenschaft den Ort des iframes aus deinem clientseitigen Code prüfen.

Wenn der iframe im Messenger für das Web ausgelöst wird, setzen wir window.name auf "messenger_ref"Andernfalls (beim Laden in Facebook-Chat-Tabs) lautet window.name"facebook_ref".

Nicht unterstützte Features

Die folgenden Einstellungen oder Features werden in Messenger-Web-Clients nicht unterstützt. Sie funktionieren weiterhin ordnungsgemäß auf Messenger-Mobile-Clients.

webview_height_ratio
webview_share_button
„Zurück“-Tasten zur Navigation
Dialogtitel
Schließen der Webansicht über URL-Weiterleitung

Problembehebung

Wenn du das SDK für Messenger-Erweiterungen nicht von deiner Seite aus aufrufen kannst, berücksichtige Folgendes:

Wenn du die Webansicht aus dem beständigen Menü oder über einen Button öffnest, stelle sicher, dass der messenger_extensions -Parameter auf truegesetzt ist. Wenn Nutzer*innen die Webansicht über eine geteilte Nachricht geöffnet haben, ist es nicht erforderlich, dass sie mit deinem Bot gesprochen haben, damit Messenger-Erweiterungen funktionieren.
Stelle sicher, dass du die Domain, auf der die Seite gehostet wird, auf die Positivliste gesetzt hast.
Stelle sicher, dass das JS-SDK auf jeder Seite, die Erweiterungen verwendet, enthalten ist.
Achte darauf, keine Funktionen aufzurufen, bevor das SDK fertig geladen wurde. Ermittle mit window.extAsyncInit (hier beschrieben), wann der Ladevorgang beendet ist.
Stelle sicher, dass die Seite über HTTPS bereitgestellt wird und nur Standardports enthält.