Facebook oEmbed

Mithilfe von oEmbed-Endpunkten von Facebook kannst du den HTML-Einbettungscode und grundlegende Metadaten für Seiten, Beiträge und Videos abrufen, um sie auf einer anderen Website oder in einer anderen App anzuzeigen.

Häufige Anwendungsfälle

• Rendern von Facebook-Seiten, -Beiträgen und -Videos in Messaging-Apps
• Einbetten von Facebook-Seiten, -Beiträgen und -Videos in Websites und Blogs
• Rendern von Facebook-Seiten, -Beiträgen und -Videos in einem Content-Management-System

Endpunkte

Anforderungen

• Ein Facebook-Entwicklungskonto
• Eine Facebook-App im Live-Modus
• Ein Zugriffsschlüssel
• App-Review für das Feature oEmbed Read

Einschränkungen

oEmbed-Endpunkte von Facebook sind nur dazu gedacht, um Facebook-Inhalte in Websites und Apps einzubetten. Sie dürfen nicht für andere Zwecke verwendet werden. Es ist strengstens untersagt, Metadaten und Seiten-, Beitrags- oder Videoinhalte (oder deren Ableitungen) von den Endpunkten für andere Zwecke zu verwenden, als eine Frontend-Ansicht der Seite, des Beitrags oder des Videos bereitzustellen. Dieses Verbot umfasst das Verwenden, Bearbeiten, Extrahieren oder die dauerhafte Speicherung der Metadaten und Inhalte, insbesondere das Ableiten von Informationen über Seiten, Beiträge und Videos aus den Metadaten zu Analysezwecken.

App-Review

Um oEmbed nutzen zu können, muss deine App einer App-Review für das Feature oEmbed Read unterzogen werden.

Verwende für das Formularfeld zum Bereitstellen einer URL, unter der wir oEmbed Read testen können, die oEmbed-Endpunkte, um den HTML-Einbettungscode für alle öffentlichen Beiträge auf unserer offiziellen Facebook-Seite oder Instagram-Seite abzurufen (oder den HTML-Einbettungscode für eine der Seiten selbst abzurufen). Füge den zurückgegebenen HTML-Einbettungscode deiner eigenen Seite hinzu, auf der du oEmbed-Inhalt anzeigen möchtest und gib die URL dieser Seite in das Formularfeld ein.

Sobald du eine Genehmigung für das Feature oEmbed Read erhalten hast, kannst du deine eigenen Seiten, Posts oder Videos einbetten, indem du die entsprechenden URLs verwendest.

Zugriffsschlüssel

Für den oEmbed-Endpunkt von Facebook wird entweder ein App-Zugriffsschlüssel (empfohlen) oder ein Client-Zugriffsschlüssel benötigt.

App-Zugriffsschlüssel

Wenn deine App einen Backend-Server verwendet, empfehlen wir, beim Zugriff auf den oEmbed-Endpunkt einen App-Zugriffsschlüssel zu verwenden. Ratenbegrenzungen hängen von der Art des Zugriffsschlüssels ab, der in der Anfrage enthalten ist, und Ratenbegrenzungen für App-Zugriffsschlüssel erlauben bis zu 5 Millionen Anfragen pro Tag.

Eine Anleitung zur Generierung von App-Zugriffsschlüsseln findest du in unserer Dokumentation „Zugriffsschlüssel“ im Abschnitt „App-Zugriffsschlüssel“.

Beachte bitte, dass App-Zugriffsschlüssel niemals clientseitig verwendet werden sollen. Sie sollten immer sicher aufbewahrt und auf deinem Server gespeichert werden. Wenn deine App einen Zugriffsschlüssel clientseitig verwenden muss, verwende stattdessen einen Client-Zugriffsschlüssel.

Client-Zugriffsschlüssel

Wenn deine App über einen Nutzeragenten wie ein Mobilgerät oder einen Webbrowser auf den oEmbed-Endpunkt zugreifen muss, muss deine App einen Client-Zugriffsschlüssel verwenden und unterliegt Ratenbegrenzungen für Client-Zugriffsschlüssel.

Um einen Client-Zugriffsschlüssel zu erhalten, melde dich bei deinem App-Dashboard an und navigiere zu Einstellungen > Erweitert > Sicherheit > Client Token.

Im Gegensatz zu App-Zugriffsschlüsseln können Client-Zugriffsschlüssel nicht allein in oEmbed-Endpunktanfragen verwendet werden. Sie müssen mit deiner App-ID kombiniert werden. Hänge dazu deinen Zugriffsschlüssel an das Ende deiner App-ID an, getrennt durch einen Senkrechtstrich (|):

{app-id}|{client-token}

Beispiel:

access_token=1234|5678

Durchsatzratenbegrenzungen

Ratenbegrenzungen hängen von der Art des Zugriffsschlüssels ab, den deine App in der jeweiligen Anfrage enthält.

Ratenbegrenzungen für App-Zugriffschlüssel

Apps, die App-Zugriffsschlüssel verwenden, können innerhalb von 24 Stunden bis zu 5 Millionen Anfragen durchführen.

Ratenbegrenzungen für Client-Zugriffsschlüssel

Ratenbegrenzungen für Client-Zugriffsschlüssel sind erheblich niedriger als Ratenbegrenzungen für App-Zugriffschlüssel. Wir geben die tatsächliche Grenze nicht an, da sie sich je nach deinen App-Aktivitäten ändert. Du kannst jedoch davon ausgehen, dass deine App die Grenze nur dann erreicht, wenn sie sich wie ein Bot verhält und etwa Tausende von Anfragen im Batch sendet oder Tausende von Anfragen pro Agent oder App-Nutzer sendet.

Abrufen des HTML-Einbettungscodes

Um den HTML-Einbettungscode einer Seite, eines Beitrags oder eines Videos zu erhalten, sende eine Anfrage an den oEmbed-Endpunkt der entsprechenden Seite bzw. des entsprechenden Beitrags oder Videos:

Ersetze {url} durch die URL der Seite, des Beitrags oder des Videos, das du abfragen möchtest, und {access-token} durch deinen App- oder Client-Zugriffsschlüssel (oder übergib ihn in einem HTTP-Header an uns). Wenn du einen Client-Zugriffsschlüssel verwendest, denke daran, ihn unter Verwendung eines Senkrechtstrichs mit deiner App-ID zu kombinieren. Ansonsten schlägt die Anfrage fehl.

Ist die Anfrage erfolgreich, antwortet die API mit einem JSON-Objekt, das den HTML-Einbettungscode der Seite, des Beitrags oder des Videos und zusätzliche Daten zur Seite, zum Beitrag oder zum Video enthält. Der HTML-Einbettungscode wird der Eigenschaft html zugewiesen.

In der Referenz der einzelnen Endpunkte findest du eine Liste der Abfrage-String-Parameter, die du einschließen kannst, um die Abfrage zu erweitern. Du kannst in jeder Abfrage auch den Abfrage-String-Parameter fields einschließen, um anzugeben, welche Felder zurückgegeben werden sollen. Wird keine Angabe gemacht, sind in der Antwort alle Standardfelder enthalten.

• Oembed-Referenz zu Seiten
• Oembed-Referenz zu Beiträgen
• Oembed-Referenz zu Videos

Beispielanfrage für eine Seite

curl -i -X GET \
 "https://graph.facebook.com/v19.0/oembed_page?url=https%3A%2F%2Fwww.facebook.com%2FCDC&access_token=96481..."

Beispielantwort

Einige Werte sind zur besseren Lesbarkeit mit Auslassungszeichen (...) abgeschnitten.

{
  "provider_url": "https://www.facebook.com",
  "provider_name": "Facebook",
  "height": 500,
  "html": "<div id=\"fb-root\"></div><script async=\"1\" defer=...",
  "type": "rich",
  "version": "1.0",
  "width": 340
}

URL-Formate

Der Abfrage-String-Parameter url akzeptiert die folgenden URL-Formate:

Seiten

https://www.facebook.com/{page-name}
https://www.facebook.com/{page-id}

Beiträge

https://www.facebook.com/{page-name}/posts/{post-id}
https://www.facebook.com/{username}/posts/{post-id}
https://www.facebook.com/{username}/activity/{activity-id}
https://www.facebook.com/photo.php?fbid={photo-id}
https://www.facebook.com/photos/{photo-id}
https://www.facebook.com/permalink.php?story_fbid={post-id}&id={page-or-user-id}
https://www.facebook.com/media/set?set={set-id}
https://www.facebook.com/questions/{question-id}
https://www.facebook.com/notes/{username}/{note-url}/{note-id}

Videos

https://www.facebook.com/{page-name}/videos/{video-id}/
https://www.facebook.com/{username}/videos/{video-id}/
https://www.facebook.com/video.php?id={video-id}
https://www.facebook.com/video.php?v={video-id}

SDK JS

Der HTML-Einbettungscode enthält standardmäßig eine Referenz zur JavaScript-Bibliothek sdk.js. Um den HTML-Einbettungscode ohne die Referenz abzurufen, sodass du sie separat laden kannst, schließe den Abfrage-String-Parameter omitscript=true ein.

Übergeben von Zugriffsschlüsseln in einem Header

Wenn du deinen Zugriffsschlüssel nicht in den Abfrage-String deiner Anfrage einschließen möchtest, kannst du ihn stattdessen über einen Authorization-HTTP-Header an uns übergeben.

Authorization: Bearer {access-token}

Beispiel:

curl -i -X GET \
  "https://graph.facebook.com/v19.0/oembed_page?url=https%3A%2F%2Fwww.facebook.com%2FCDC" \
  --header "Authorization: Bearer 96481..."