Facebook Login für Geräte

Falls du auf der Suche nach Hilfe zu deinem Facebook-Portal bist, findest du diese im Portal Help Center.

Besuche zur Eingabe deines Facebook für Geräte-Code zur Anmeldung bei deinem Smart TV, deiner Kamera, deinem Drucker und anderen Geräten die Facebook für Geräte-Seite.

Implementiere Facebook Login für Geräte, damit sich Nutzer mit ihrem Facebook-Konto bei deiner App oder deinem Dienst anmelden können. Mit dieser Funktion können sich Nutzer bei Geräten mit eingeschränkten Eingabe- oder Anzeigefähigkeiten, wie Smart-TVs, digitale Fotorahmen oder Internet-of-Things-Geräte, anmelden.

Bei der Geräteanmeldung wird auf deinem Gerät ein alphanumerischer Code angezeigt, den Nutzer auf einer Webseite oder über ihren Desktop-PC oder ihr Smartphone eingeben sollen. Nutzer, die deine App oder deinen Service nutzen, können dann die Berechtigungen gewähren. Nachdem deine App die Berechtigungen erhalten hat, wird ein Zugriffsschlüssel an das Gerät gesendet, über den deine App Graph API-Anfragen starten kann, um den Nutzer zu identifizieren und Informationen zu erhalten, mit denen die Nutzererfahrung auf dem Gerät personalisiert werden kann.

Wenn du eine TV-App für Apple TV, Android TV oder Fire TV entwickelst, solltest du dazu das Facebook-SDK für tvOS oder das Facebook-SDK für Android verwenden.

In diesem Leitfaden wird die manuelle Integration von Geräte-Login ohne Verwendung der genannten SDKs erläutert.

Nutzererfahrung

Diese Richtlinien beschreiben, wie du eine übersichtliche, sichere und einheitliche Anmeldeerfahrung für alle Geräte und Services entwickelst.

1. Call to Action

Überlege dir zuerst, wann du einen Nutzer dazu auffordern möchtest, sich anzumelden oder sich mit Facebook zu verbinden. Bei einigen Geräten kann das sofort der Fall sein, bei anderen solltest du das erst später machen.

Um die am besten geeignete, einheitlichste und zuverlässigste Nutzererfahrung zu gewährleisten, sollte der Button dem offiziellen Facebook Login-Button möglichst ähnlich sehen.

Das bedeutet designtechnisch Folgendes:

Der Text des Buttons muss „Mit Facebook anmelden“ oder „Mit Facebook verbinden“ lauten.
Verwende Weiß und das offizielle Facebook-Blau: #1877F2.
Wenn deine App eine graphische Anzeige unterstützt, kannst du auch das offizielle „f“-Logo einbinden. Gemäß der Facebook-Markenrichtlinien sollte das Logo immer entweder weiß oder Facebook-blau (#1877F2) sein.

Beschreibe gegebenenfalls die Vorteile einer Anmeldung, z. B. „Finde heraus, was sich deine Freunde ansehen“ oder „Schau dir Fotos aus deinen Facebook-Alben an“.

2. Zeige den Code an

Wenn ein Nutzer auf den „Call to Action“-Button klickt, ruft dein Gerät die Facebook-API auf, die einen Code zurücksendet.

Informiere Nutzer über die UI mit der folgenden Nachricht, dass sie eine Webseite aufrufen und dort den Code eingeben müssen: „Besuche als Nächstes facebook.com/device (http://facebook.com/device) über deinen Desktop-PC oder dein Smartphone und gib diesen Code ein.“ Zeige den vollständigen Code an, den du von der Facebook-Device Login API (Geräteanmeldungs-API) erhalten hast. Der Code ist zwischen 6 und 12 Zeichen lang.

Du kannst einen Close- oder Cancel-Button hinzufügen, damit Nutzer den Geräte-Login-Vorgang abbrechen können. Dadurch sollten sie wieder auf dem ursprünglichen Anmeldebildschirm landen.

Wenn der Code auf dem Bildschirm angezeigt wird, schickt dein Gerät eine Anfrage an die Device Login API, um zu prüfen, ob ein Nutzer deine App autorisiert hat. Wenn der Nutzer nach einigen Minuten den Code noch nicht eingegeben hat, sendet die Device Login API einen code_expired-Fehler zurück. Erhält dein Gerät diesen Fehler, solltest du den Login-Vorgang abbrechen, und auf der UI sollte erneut der „Call to Action“-Button angezeigt werden.

Es können auch QR-Codes generiert werden, bei denen der Nutzer-Code in die URL eingebettet ist. Hierzu fügst du den user_code-Parameter zur URL hinzu:

https://www.facebook.com/device?user_code=<USER_CODE>

3. Autorisierung

Nutzer sehen diesen Vorgang, wenn sie facebook.com/device über ihren Desktop- oder Mobilgerät-Browser aufrufen. Ihnen wird zuerst ein Textfeld angezeigt, in das sie den Code eingeben können:

Nachdem sie den Code eingegeben und auf Continue geklickt haben, können sie die Berechtigungen auswählen, die sie gewähren möchten:

Damit Nutzer wissen, dass der Login-Vorgang erfolgreich war, erhalten sie daraufhin eine Bestätigungsnachricht:

4. Bestätige die erfolgreiche Anmeldung

Du solltest auf der UI deines Geräts auch eine Bestätigungsnachricht anzeigen. Im besten Fall beinhaltet sie den Namen der Person und, falls möglich, ihr Facebook-Profilbild.

Zeige diese Bestätigung auf deinem Gerät an, bis der Nutzer auf den Continue-Button klickt. Ein Nutzer muss den Code unter Umständen an einem Computer eingeben, der sich an einem anderen Ort befindet. Es kann also eine Weile dauern, bis er wieder zu deinem Gerät zurückkehrt und die Bestätigung sieht, bevor er fortfährt.

Nachdem der Nutzer auf Continue geklickt hat, kannst du ihm auf deinem Gerät eine großartige Nutzererfahrung bieten.

5. Abmeldung oder Trennung

Nutzer sollten dazu in der Lage sein, sich von deinem Gerät abzumelden. Dein Gerät sollte die Verbindung mit Facebook nicht speichern. Stelle dazu im Gerätemenü die Optionen Log out from Facebook oder Disconnect from Facebook bereit.

Wenn ein Nutzer eine dieser Optionen auswählt, sollte dein Gerät den gespeicherten Zugriffsschlüssel aus dem Speicher löschen. Wenn du den Zugriffsschlüssel in einer Datenbank oder einem Cloud-Speicher gespeichert hast, solltest du ihn auch dort entfernen. Du musst keinen API-Aufruf starten, um die Validierung des Zugriffsschlüssels aufzuheben.

Nachdem sich ein Nutzer abgemeldet hat, sollte dein Gerät wieder den ursprüngliche „Call to Action“-Button aus Schritt 1 anzeigen.

Implementierung von Facebook Login für Geräte

Facebook Login für Geräte ist für Geräte gedacht, die direkte HTTP-Aufrufe über das Internet durchführen. Dein Gerät kann folgende API-Aufrufe und -Antworten durchführen und erhalten:

Lade dein App-Dashboard und wähle unter „Produkt > Facebook Login > Einstellungen > Anmeldung an Geräten“ „Ja“ aus.

2. Generiere einen Code

Wenn ein Nutzer auf die „Call to Action“-Buttons Connect to Facebook oder Log in with Facebook klickt, sollte dein Gerät einen HTTP-POST abschicken:

POST https://graph.facebook.com/v2.6/device/login
       access_token=<YOUR_APP_ID|CLIENT_TOKEN>
       scope=<COMMA_SEPARATED_PERMISSION_NAMES> // e.g. public_profile,user_likes
       redirect_uri=<VALID_OAUTH_REDIRECT_URL>

Der scope-Parameter ist optional und muss eine kommagetrennte Liste mit Anmeldeberechtigungen enthalten, die im Login Review zur Verwendung genehmigt wurden.

Der CLIENT_TOKEN befindet sich in den App-Einstellungen unter „Erweitert“ und sollte mit deiner App-ID kombiniert werden (durch ein Pipe-Zeichen | getrennt), um den vollständigen access_token zu bilden.

Der redirect_uri ist ein optionaler Parameter. Wenn du eine URL bereitstellst, wird die Person nach einer erfolgreichen Anmeldung an diese URL weitergeleitet. Auf diese Weise kann sich die Person bei der Webseite deiner App anmelden. Dies ist nützlich für Account-Verwaltungsvorgänge. Bei der URL muss es sich um eine gültige OAuth-Umleitungs-URL handelt, wie in deinen App-Einstellungen unter „Erweitert“ konfiguriert. Die Antwort hat folgende Form:

{
  "code": "92a2b2e351f2b0b3503b2de251132f47",
  "user_code": "A1NWZ9",
  "verification_uri": "https://www.facebook.com/device",
  "expires_in": 420,
  "interval": 5
}

Diese Antwort bedeutet Folgendes:

Zeige den String „A1NWZ9“ auf deinem Gerät an.
Fordere den Nutzer auf, „facebook.com/device“ aufzurufen und den Code einzugeben.
Der Code läuft nach 420 Sekunden ab. Du solltest den Login-Vorgang abbrechen, wenn du bis dahin keinen Zugriffsschlüssel erhalten hast.
Dein Gerät sollte die Device Login API alle 5 Sekunden abfragen, um zu prüfen, ob die Autorisierung erfolgreich war.

3. Zeige den Code an

Dein Gerät sollte den user_code anzeigen und den Nutzer auffordern, die verification_uri (z. B. facebook.com/device) über den PC oder das Smartphone aufzurufen. Siehe Nutzererfahrung.

4. Autorisierungsabfragen

Dein Gerät sollte die Device Login API abfragen, um zu prüfen, ob der Nutzer deine App erfolgreich autorisiert hat. Dies sollte im interval in der Antwort auf deinen Aufruf in Schritt 1 erfolgen, das 5 Sekunden beträgt. Dein Gerät sollte Folgendes abfragen:

POST https://graph.facebook.com/v2.6/device/login_status
       access_token=<YOUR_APP_ID|CLIENT_TOKEN>
       code=<LONG_CODE_FROM_STEP_1> // e.g. "92a2b2e351f2b0b3503b2de251132f47"

Die Antwort auf diesen API-Aufruf hängt davon ab, an welcher Stelle im Autorisierungsvorgang sich der Nutzer befindet. Du erhältst entweder einen Zugriffsschlüssel oder ein Fehlerobjekt mit einem zu parsenden Sub-Code:

Fehler-Sub-Code	Beispielantwort:	Bedeutung
`N/A`	`{"access_token": "ABCD...", "expires_in" : 5183996 }`	Der Nutzer hat das Gerät erfolgreich autorisiert. Das Gerät kann jetzt den `access_token`-Wert für autorisierte API-Aufrufe nutzen.
`1349174`	`{"error":{"message":"This request requires the user to take a pending action","code":31,"error_subcode":1349174,"error_user_title":"Device Login Authorization Pending","error_user_msg":"User has not yet authorized your application. Continue polling."}}`	Der Nutzer hat deine App noch nicht autorisiert. Führe weitere Abfragen in dem Intervall durch, das du in Schritt 1 festgelegt hast.
`1349172`	`{"error":{"message":"User request limit reached","code":17,"error_subcode":1349172,"error_user_title":"OAuth Device Excessive Polling","error_user_msg":"Your device is polling too frequently. Space your requests with a minium interval of 5 seconds."}}`	Dein Gerät stellt zu häufige Abfragen. Führe die Abfragen im Intervall durch, das im ersten API-Aufruf angegeben wurde.
`1349152`	`{"error":{"message":"The session has expired""code":463,"error_subcode":1349152, "error_user_title":"Activation Code Expired","error_user_msg":"The code you entered has expired. Please go back to your device for a new code and try again."}}`	Der Geräte-Code ist abgelaufen. Brich den Geräte-Login-Vorgang ab und leite den Nutzer zurück zum Startbildschirm.

5. Bestätige die erfolgreiche Anmeldung

Wenn du einen Zugriffsschlüssel erhältst, hat der Nutzer deine App erfolgreich autorisiert. Du solltest diesen Zugriffsschlüssel auf dem Gerät speichern.

Damit ein Nutzer weiß, dass die Anmeldung erfolgreich war, sollte dein Gerät seinen Namen und, falls möglich, sein Profilbild anzeigen, bis er auf Continue klickt. Um an den Namen und das Profilbild des Nutzers zu kommen, sollte dein Gerät einen herkömmlichen Graph API-Aufruf starten:

GET https://graph.facebook.com/v2.3/me?
      fields=name,picture&amp;
      access_token=<USER_ACCESS_TOKEN>

Die Antwort sieht folgendermaßen aus:

{
  "name": "John Doe", 
  "picture": {
    "data": {
      "is_silhouette": false, 
      "url": "https://fbcdn.akamaihd.net/hmac...ile.jpg"
    }
  }, 
  "id": "2023462875238472"
}

Zeige den Namen und das Profilbild des Nutzers auf deinem Gerät an, bis er auf Continue klickt.

6. Speichere Zugriffsschlüssel

Dein Gerät sollte den Zugriffsschlüssel speichern, um weitere Anfragen an die Graph API zu schicken.

Zugriffsschlüssel für die Geräteanmeldung können bis zu 60 Tage gültig sein, unter bestimmten Voraussetzungen aber ungültig gemacht werden. Wenn ein Nutzer beispielsweise sein Facebook-Passwort ändert, wird der Zugriffsschlüssel ungültig.

Dein Gerät sollte einen ungültigen Zugriffsschlüssel aus dem Speicher löschen. Der Nutzer, der dein Gerät verwendet, muss den Geräte-Login-Vorgang nochmals von Schritt 1 an durchlaufen, um einen neuen, gültigen Schlüssel zu erhalten.

Fehlerbehebung

Kann ich Gerätevorgangsanfragen über HTTP durchführen?
OAuth 2 erfordert TLS/HTTPS.

Kann ich Gerätevorgangsanfragen mit der GET-Methode durchführen?
Alle Gerätevorgangsanfragen sollten POST-Anfragen sein.

Wie kann ich den Zugriffsschlüssel für den Geräte-Login aktualisieren?
Zugriffsschlüssel für die Geräteanmeldung können bis zu 60 Tage gültig sein.

Weitere Informationen über das Aktualisieren von Schlüssel findest du unter Zugriffsschlüssel.

Ich erhalte einen Invalid API method-Fehler, wenn ich eine POST-Anfrage starte. Was ist das Problem?
Wenn du eine POST-Anfrage startest und den folgenden oder einen ähnlichen Fehler erhältst:

{"error":{"message":"Invalid API method","type":"OAuthException","code":3}}

Dann musst du eventuell „Anmeldung über Geräte“ in deiner App aktivieren.

Lade dein App-Dashboard und lege unter „Produkt > Facebook Login > Einstellungen > Anmeldung an Geräten“ „Ja“ fest.

Mein Zugriffsschlüssel für den Geräte-Login ist ungültig. Was kann ich tun?
Wenn dein Zugriffsschlüssel ungültig ist, sollte dein Gerät den ungültigen Zugriffsschlüssel aus dem Speicher löschen und einen neuen Schlüssel anfordern. Der Nutzer, der dein Gerät verwendet, muss den Geräte-Login-Vorgang nochmals von Schritt 1 an durchlaufen, um einen neuen, gültigen Schlüssel zu erhalten.