web & mobile DEVELOPER 02 / 2016 – Facebook API

wmd_02_2016

 

Facebook & PHP

Facebook bietet für PHP ein leistungsfähiges SDK an, über das man zahlreiche Facebook Features direkt ansprechen kann, wie beispielsweise die Open Graph API, Upload von Bildern und Videos, Batch Request und vieles andere mehr.

Von Patrick Lobacher

Es ist relativ einfach, mit der Facebook API direkt zu kommunizieren – neben SDKs für JavaScript und vielen anderen Sprachen, gibt es natürlich auch eine Version für PHP.

Das Facebook SDK für PHP in der Version 5.0.0 unterstützt vollständig PSR-4:Autoloader (http://www.php-fig.org/psr/psr-4/), was insbesondere bedeutet, dass es sich stark auf Namspaces verlässt, damit Klassendateien automatisch geladen werden können. Sollte man mit den Konzepten Namespaces und Autoloading noch nicht so viel anfangen können, so kann man sich unter obigem Links eine Auffrischung abholen.

Facebook Graph API

Bei der Facebook Graph API handelt es sich um eine sehr einfache HTTP-basierte API. Sie wurde nach dem Konzept des sogenannten „Social Graph“ benannt.

Der Social Graph ist eine Repräsentation der Informationen, die in Facebook existieren, sowie ihrer Struktur. Dabei besteht der Graph aus den folgenden Elementen zusammen:

  • Nodes (Knoten)
    Als Knoten werden alle direkt erreichbaren Ziele im Graph bezeichnet, z.B. ein User, ein Foto, eine Seite oder ein Kommentar
  • Edges (Kanten)
    Die Verbindung zwischen allen Dingen (z.B. der Besitz eines Albums, oder das Anhören eines Videos) bzw. die Aktionen zwischen Nodes werden als Edges bezeichnet (z.B. die Fotos eines Albums oder ein Like)
  • Fields (Felder)
    Die Eigenschaften einer Node werden als Fields bezeichnet, z.B. die Email-Adresse eines Users

Im Zentrum des Social Graphs (der eine Abbildung aus Nodes, Edges und Fields ist), steht der User (Node). Der User ist mit anderen Usern befreundet (Edges). Eventuell besitzt (Edge) der User ein Album (Node), das ggf. mehrere Bilder (Nodes) beinhaltet (Edges). Dies wurden vielleicht geliked (Edge).

Die richtigen Berechtigungen vorausgesetzt, können die Beziehungen und Daten über die Facebook Graph API abgerufen werden. Da die API auf HTTP basiert, kann für die Ansprache mit jeder beliebigen Programmiersprache erfolgen. Wir verwenden für den vorliegenden Artikel PHP und dafür eine speziell von Facebook entwickeltes PHP SDK.

Da die API auf HTTP beruht, könnten wir auch eine Abfrage über eine URL durchführen: https://graph.facebook.com/me. Dies liest die Eigenschaften des eigenen Users aus. Allerdings ist dies ohne ein sogenanntes Access Token nicht möglich, sodaß wir hier zunächst eine Fehlermeldung erhalten.

Wichtig ist aber der Teil /me der URL – dies wird als API-Endpoint bezeichnet. Davon gibt es in der API zahlreiche, hier einige Beispiele:

  • /me
    Der aktuelle User. Man kann hier auch stattdessen einen Usernamen angeben, um auf einen anderen User zuzugreifen
  • /me/feed
    Der Feed des aktuellen Users
  • /me/album
    Ein Fotoalbum
  • /me/comment
    Ein einzelner Kommentar auf einer Node
  • /me/message
    Eine einzelne Nachricht
  • /me/photo
    Ein einzelnes Foto
  • /user
    Ein spezieller User
  • /user/accounts
    Alle Accounts, die ein User verwaltet
  • u.v.a.m.

 

Installation des SDKs

Die Systemvoraussetzungen für das SDK sind recht gering:

  • PHP 5.4 oder höher
  • Die PHP-Extension „mbstring“
  • Composer (optional)

Wir starten in diesem Tutorial mit einem leeren Webprojekt – es ist aber natürlich auch jederzeit möglich, das SDK zu einem bestehenden Projekt hinzuzufügen.

Im folgenden verwenden wir die Installation via Composer – sollten Sie allerdings keinen Shell-Zugriff haben (z.B. bei Shared-Hosting Umgebungen), so können Sie das SDK natürlich auch manuell installieren: https://developers.facebook.com/docs/php/gettingstarted

Legen Sie im Document-Root eine Datei mit dem Namen composer.json und folgendem Inhalt an:

Listing 1: composer.json

Nun müssen Composer installieren, wenn Sie es noch nicht auf Ihrem System haben.

Unter Linux und Mac OS X reicht hierfür folgendes aus:

Listing 2: Composer installieren

Die zweite Zeile kopiert Composer ins ausführbare Verzeichnis um, sodaß ein Eingeben von composer reicht, um diesen auszuführen. Wenn Sie keine Root-Berechtigung haben, können Sie Composer mit ./composer.phar ausführen.

Entsprechende Anweisungen für Windows finden Sie hier: https://getcomposer.org/doc/00-intro.md.

Nun können Sie die Installation des SKDs ganz einfach starten:

Listing 3: SDK installieren

Nun reicht im PHP-Script die Angabe des Autoloaders:

Listing 4: Autoloader im PHP-Script index.php

Sollten Sie Composer nicht verwenden wollen, finden Sie unter der URL https://developers.facebook.com/docs/php/gettingstarted/5.0.0 eine Möglichkeit, das SDK über eine Download-Datei zu installieren.

Facebook App anlegen

Um das SDK zu verwenden, benötigen Sie eine Facebook App, die Sie unter der folgenden URL erstellen können: https://developers.facebook.com/apps

Klicken Sie zunächst rechts oben auf den grünen Button „+ Add a New App“. Es erscheint ein Overlay mit vier möglichen Plattformen (unter dem Link „advanced setup“ verstecken sich sogar noch weitere.

  • iOS (Integration in iOS)
  • Android (Integration in Android)
  • Facebook Canvas (Integration in Facebook)
  • Website (seperate Website mit Facebook Integration)

Wir entscheiden uns für den letzten Punkt „Website“ und geben im darauf folgenden Screen den Namen „phptest“ und klicken „Create New Facebook App ID“. Nun kann eine Kategorie gewählt werden – wir nehmen hier „Apps für Seiten“ und klicken „App-ID erstellen“.

facebook_php_lobacher_01

Wichtig ist nur der folgende Code (und dort vor allem die App-ID {app-id}), denn hier sind die Daten enthalten, die wir gleich zur Einbindung brauchen – speichern Sie diesen Code in einer Datei index.html ab, damit wir die Funktion der App testen können:

Listing 5: index.html – Basis

Als nächstes muss die URL der (späteren) Website festgelegt werden – dies ist insbesondere auch für das Testen notwendig.

Nun kopieren wir noch den folgenden Code zur index.html hinzu und testen die Seite im Browser.

Listing 6: index.html – Erweiterung

Erscheinen nun Like- und Share-Button, war die Einrichtung der App erfolgreich.

facebook_php_lobacher_02

Sobald Sie nun wieder zur URL https://developers.facebook.com/apps gehen, sehen Sie die App in der Auflistung und können diese durch Klick auf das Icon konfigurieren.

Wir benötigen hier noch das sogenannte „App-Secret“, welches Sie in der Konfiguration unter „App Secret > Show“ erhalten.

facebook_php_lobacher_03

 

Nun erweitern wir die Einbindung per Autoloader in der Datei index.php mit der Konfiguration – hier sind vor allem die App-ID und das App-Secret einzutragen. Der dritte Parameter ist die Open Graph API Version, die verwendet werden soll (hier 2.5, die seit Oktober 2015 im Einsatz ist):

Listing 7: index.php – Konfiguration

Authorisierung

Als ersten Beispiel wollen wir nun einen User bei Facebook Autorisieren und dann seine Profildaten auslesen.

Hierfür verwenden wir den sogenannten getRedirectLoginHelper, der eine Autorisierung über OAuth 2.0 rmöglicht. Der Login-Ablauf ist dabei wie folgt:

  • Über die Methode getLoginUrl(callback-url,permissions) am Ende des Listings wird ein Link zu Facebook generiert und diesem die URL mitgegeben, zu der gesprungen werden soll, wenn der Login erfolgreich war
  • Bei Klick auf den Link wird der User zu Facebook weitergeleitet, wo ein modaler Dialog den User auffordert, sich einzuloggen. Die Daten, die die App anfordert werden in diesem Dialog ebenfalls angezeigt (und sind vorher über die „permissions“ festgelegt worden)
  • Wenn der User sich erfolgreich eingeloggt hat oder aber die Autorisierung aktiv ablehnt, wird er zu der in „callback-url“ hinterlegten URL zurückgeleitet

facebook_php_lobacher_04

Listing 8: fb-login.php

Der Access Token wird dabei in einer Session gespeichert und anfangs über die Methode setDefaultAccessToken() ermittelt. Anschließend wird der kurzfristige in einen langfristigen Token über den OAuth-Client getOAuth2Client() verwandelt.

Das Auslesen der Profil-Informationen übernimmt die API-Funktion get(), welches mit dem Endpoint /me angefragt wird, dem als Parameter diejenigen Felder übermittelt werden, die man erhalten will – hier Name, Vorname, Nachname und Email.

Testen kann man die Graph-Abfrage auch im sogenannten Graph API Explorer unter: https://developers.facebook.com/tools/explorer

facebook_php_lobacher_05

Weitere Informationen, die man auslesen kann, sind z.B.:

  • age_range (Minimales und/oder maximales Alter)
  • birthday (Geburtstag)
  • devices (Geräte, die der User verwendet – nur iOS und Android)
  • currency (Währungseinstellung des Users inkl. Umrechnungskurs)
  • education (Ausbildungsinformationen)
  • favorite_athletes (Favoristierte Sportler)
  • favorite_teams (Favoristierte Sport-Teams)
  • gender (Geschlecht)
  • hometown (Heimat-Stadt)
  • inspirational_people (Inspirierende Personen)
  • link (Link zur Timeline)
  • location (Aktuelle eingegebene Position)
  • political (Politische Interessen)
  • religion (Religiöse Interessen)
  • sports (Sportliche Interessen)
  • quotes (Favorisierte Quotes)
  • website (Website)
  • u.v.a.w.

Eine komplette Übersicht darüber finden Sie hier: https://developers.facebook.com/docs/graph-api/reference/v2.5/user.

Das User Profil wird im Code-Beispiel lediglich mit print_r() ausgegen – kann aber dann natürlich programmatisch weiter verwendet werden.

Die Fehlerbehandlung ist zudem so aufgebaut, dass sowohl SDK Fehler (FacebookSDKException) wie auch Facebook Graph Fehler (FacebookResponseException) mittels getMessage() ermittelt und ausgegeben werden.

Das ist Grund genug für die Entwickler diesen Erfolg zu festigen und das schon etwas betagte Framework einer Generalüberholung zu unterziehen.

Profilphoto auslesen

Als nächstes wollen wir das Profilphoto des Users auslesen – dafür duplizieren wir die Datei und nennen das Duplikat fb-photo.php. Folgender Code wird zudem angepasst:

Listing 9: fb-photo.php

Hier wird über den Endpoint /me/picture das Bild ermittelt und über den Parameter height mit einer bestimmten Höhe als Link zurückgeliefert. Das Bild wird im unteren Teil schließend ausgegeben und auf dem Server abgespeichert.

Timeline auslesen

Wir wollen nun die Timeline des Users auslesen. Auch hierfür legen wir ein Duplikat der vorherigen Datei an und nennen diese fb-timeline.php. Folgende Veränderung nehmen wir hierin vor:

Listing 10: fb-timeline.php

Um die Timeline auszulesen ist es zunächst wichtig, dass diese auch in den Berechtigungen enthalten ist. Dafür muss der User aber die Berechtigungen erweitern, was nur geht, wenn es sich erneut einloggt. Um dies zu forcieren, können Sie ein session_destroy() am Anfang des Script positionieren, dieses erneut aufrufen und anschließend wieder entfernen. Beim wiederholten Aufrufen werden nun die Berechtigungen erneut aufgerufen. Verantwortlich dafür ist die Zeile $permissions im Script.

Nun werden über den Endpoint /me/posts die Posts (hier limitiert auf 50) aufgerufen und weiter unten ausgegeben, indem die Methode getGraphEdge() auf die Ausgabe angewendet und dann das Resultat in ein Array umgewandelt wird.

Fotos eines Users auslesen

Die Fotos eines Users sind im Endpoint /me/photos gespeichert. Dort allerdings befinden sich nur die IDs der Fotos, die man nun gezielt per /<id>?fields=images auslesen muss. Hier erhält man nur alle URLs auf die Fotos samt zugehöriger Meta-Daten.

 

Listing 11: fb-photos-of-user.php

Freundesliste ermitteln

Die Freundesliste lässt sich über den Endpoint /me/taggable_friends auslesen:

Listing 12: fb-friends-of-user.php

Im Feed posten

Bisher haben wir lediglich lesend auf die Facebook Graph Daten zugegriffen – nun wollen wir auch schreibend aktiv werden.

Sobald wir hier die Berechtigungen um publish_actions ergänzen, wird bei der Freigabe auch dediziert danach gefragt, ob man will, dass die App auch im eigenen Namen auf Facebook posten darf.

facebook_php_lobacher_07

Dafür posten wir eine Testnachricht im Feed des Users:

Listing 13: fb-post-in-feed.php

Hier verwenden wir als Methode auf dem Facebook Objekt post(), welche es ermöglicht, Daten zu schreiben.

Der Endpoint für den Feed lautet /me/feed und als Nachricht muss ein Array angegeben werden, welches den Nachrichtentext im Schlüssel message enthält.

facebook_php_lobacher_08

Post Link

Mit dem Wissen des vorherigen Beispiels können wir auch einen Link posten – hier muss lediglich ein Link im Data-Array zusätzlich angegeben werden:

Listing 14: fb-post-in-feed.php

facebook_php_lobacher_09

Zusätzlich kann man im Data-Array noch einen Schlüssel description angeben, mit dem der Link umschrieben wird (URL ist hier default).

Upload Foto

Nun wollen wir ein Bild in die Timeline posten – hier wird als Quelle das Bild lokal in der Eigenschaft source referenziert und per Post-Request an den Endpoint /me/photos geschickt. Zusätzlich wird über message noch ein Text mitgegeben:

Listing 15: fb-upload-photo.php

facebook_php_lobacher_10

Auf verwalteter Seite posten

Als vorletztes Beispiel wollen wir nun auf einer Seite posten, die der User verwaltet  – dazu muss der Name der verwalteten Seite (hier z.B. „Pluswerk AG“) bekannt sein und entprechend abgefragt werden. Die Liste der Seiten wiederum erhält man über den Endpoint /me/accounts:

Listing 16: fb-post-page.php

facebook_php_lobacher_11

Canvas App

Um Canvas-Apps zu verwenden (also in Facebook als iframe integrierte Apps), muss der Server SSL verstehen, da man nur sichere URLs mittels https referenzieren darf.

Wir legen nun eine neue App unter https://developers.facebook.com an, in dem wir bei „My Apps“ auf „Add a New App“ klicken und dann „Facebook Canvas“ wählen. Als Namen für die App wählen wir „phpcanvastest“.

Wir wählen nun „Skip Basic Setup“ und gehen in die Konfiguration der App unter „Settings“. Beim Eintrag „App Domains“ tragen wir die unsere Domain ein und wählen unter Plattform „Facebook Canvas“ aus. Als Namespace tragen wir ebenfalls „phpcanvastest“ ein. Bei den Einstellungen zu „Secure Canvas URL“ und „Mobile Site URL“ tragen Sie das Verzeichnis auf Ihrem Server ein, das die PHP-Datei enthält, die sie innerhalb der Canvas anzeigen wollen.

Nun können Sie die App-Id und das App-Secret in eine neue PHP-Datei kopieren, die wir von einer der vorherigen duplizieren:

Listing 13: fb-canvas.php

facebook_php_lobacher_12

Hier verwenden wir als einzigen großen Unterschied nun den sogenannten getCanvasHelper() um die Canvas-Funktionalität zu realisieren. Am Ende wiederum wird der Redirect zur Facebook-Seite realisiert.

Um die Funktionalität zu Teste, rufen wir die URL zu dem Script auf (mittels https!) und werden zu Facebook zurückgeleitet. Hier müssen wir die Berechtigung gewähren. Anschließend erhalten wir die Ausgabe des print_r() innerhalb von Facebook.

facebook_php_lobacher_13

 

Fazit

Wir haben mit den vorliegenden Beispielen nur an der Oberfläche der Möglichkeiten gekratzt, welche die Graph API bietet. Letztlich kann nahezu jeder Aktion, die innerhalb von Facebook möglich ist, auch programmatisch erstellt werden. Viel Spaß damit!

 

Links zum Thema

Facebook Developers Bereich
https://developers.facebook.com/docs/apps/changelog

Graph API Referenz
https://developers.facebook.com/docs/graph-api

Facebook Plattform Überblick
https://developers.facebook.com/docs/apps/changelog

Facebook SDK für PHP
https://developers.facebook.com/docs/reference/php

Graph API Explorer
https://developers.facebook.com/tools/explorer

 

 

 

Leave a Comment.