SDK für Messenger-Erweiterungen hinzufügen

Das SDK für Messenger-Erweiterungen bietet nützliche Messenger-spezifische Features für jede Webseite 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, Zahlungen akzeptieren, Inhalte in Messenger-Unterhaltungen teilen und eine tief gehende Integration in die Messenger-UI vornehmen.

Inhalt

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.

FunktionBeschreibung

getContext()

Rufe Unterhaltungskontext wie z. B. die seitenspezifische Nutzer-ID der Person ab, die die Webansicht geöffnet hat.

requestCloseBrowser()

Schließe die Webansicht und kehre zur Messenger-Unterhaltung zurück.

beginShareFlow()

Teile Inhalte aus der Webansicht in Messenger-Unterhaltungen.

askPermission()

Fordere Berechtigungen an, um beispielsweise Profilinformationen einer Person abzurufen.

getGrantedPermissions()

Überprüfe aktuell gewährte Berechtigungen.

PaymentRequest

Basisobjekt zur Durchführung von Zahlungen in der Webansicht.

getSupportedFeatures

Überprüfe, welche Features, wie z. B. Zahlungen oder Teilen, 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. Hinzufügen von Domänen zu einer Whitelist

Um die Messenger-Erweiterungen in deinem Bot nutzen zu können, musst du aus Sicherheitsgründen zunächst die Domain, über die die Seite bereitgestellt wird, zu einer Whitelist hinzufügen. Weitere Informationen hierzu findest du in der Referenzdokumentation zu Whitelists.

Mit der folgenden API kannst du eine Domäne programmgesteuert zu einer Whitelist hinzufügen:

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

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

{"result":"success"}

2. Binde das JS-SDK für Messenger-Erweiterungen ein

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. Warte auf das SDK-Lade-Event

Wenn das Laden von Messenger Extensions JS SDK abgeschlossen ist, wird window.extAsyncInit() aufgerufen. 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

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

Zulassen des Ladens von iframes in Messenger- und Facebook-Domains

Die Messenger- und Facebook-Web-Clients öffnen deine Seiten in einem iframe. Dazu muss dein Web-Server den X-Frame-Options-Header in der HTTP-Antwort zurückgeben: Beispiel:

X-Frame-Options: ALLOW-FROM https://www.messenger.com/
X-Frame-Options: ALLOW-FROM https://www.facebook.com/

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.

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 true gesetzt ist. Wenn Nutzer 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 eine Whitelist 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.