裝置專用的 Facebook 登入

如果您想獲得有關 Facebook Portal 的協助，請瀏覽 Portal 幫助中心。

如要輸入裝置專用 Facebook 代碼以登入智能電視、相機、列印機及其他裝置，請瀏覽裝置專用 Facebook 專頁。

安裝裝置專用 Facebook 登入功能後，用戶便可透過他們的 Facebook 帳戶登入您的應用程式或服務。此功能可讓用戶在輸入或顯示功能有限的裝置（如智能電視、數碼相框或物聯網裝置）中登入帳戶。

有了裝置專用登入，您的裝置會顯示英數代碼，要求用戶在桌面電腦或智能手機的網頁上將之輸入。使用您應用程式或服務的用戶則可以授予權限。裝置在應用程式取得權限後會收到存取憑證，讓您的應用程式提出 Graph API 要求，以辨識用戶和取得資訊，將用戶的裝置體驗個人化。

如果您正在建立 Apple TV、Android TV 或 Fire TV 專用的電視應用程式，您應該分別使用 tvOS 專用 Facebook SDK 或 Android 專用 Facebook SDK。

本指南會介紹在不使用上述 SDK 的情況下，裝置專用登入的手動整合。

用戶體驗
建置裝置專用登入
解決疑難

用戶體驗

這些指南將描述如何在裝置和服務之間設計一個明確、安全且一致的登入體驗。

1.呼籲字句

首先考慮您想在用戶體驗的哪一部分要求用戶登入或連結 Facebook，部分裝置會立即作出要求，有些則可能會在稍後的體驗中提出要求。

若要確保提供最易用、一致且可靠的用戶體驗，請盡量將按鈕設計成像官方「Facebook 登入」按鈕。

從視覺設計觀點來看，這代表您應該

在按鈕加上「使用 Facebook 帳戶登入」或「連結至 Facebook」標籤。
使用白色和 Facebook 品牌官方藍色：#1877F2。
如果您的裝置支援圖形顯示，您也可以加入官方「f」標誌。根據 Facebook 品牌指南，標誌必須是白色或是 Facebook 藍 (#1877F2)。

如有需要，請說明登入的好處。例如：「看看你的朋友在看什麼」或「從你的 Facebook 相簿瀏覽照片」。

2.顯示代碼

當有人點擊呼籲字句時，您的裝置會對傳回程式碼的 Facebook 的 API 進行調用。

在您的介面中，告訴用戶要到訪網站，且輸入含以下訊息的代碼，例如「接下來請使用桌面電腦或智能手機前往 facebook.com/device（http://facebook.com/device），然後輸入這組代碼」。顯示從 Facebook 裝置登入 API 收到的完整代碼。這個代碼長度介乎 6 至 12 個字元。

您可以加入 Close 或 Cancel 按鈕，這樣用戶即可取消裝置登入流程。這個動作將會把用戶傳送回初始登入畫面。

當代碼顯示在螢幕上時，您的裝置會輪詢裝置登入 API，以了解是否有人授權您的應用程式。幾分鐘後，如果他們還未輸入代碼，裝置登入 API 將傳回 code_expired 錯誤。當您的裝置收到錯誤訊息後，您應該要取消登入流程，然後介面應該顯示呼籲字句。

您也可利用網址中的內嵌用戶代碼，以產生 QR 碼。如要做到這一點，請將 user_code 參數加入該網址：

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

3.授權

這是用戶在桌面電腦或流動瀏覽器瀏覽 facebook.com/device時所看到的流程。首先用戶會看到可輸入代碼的文字欄位：

輸入代碼並點擊 Continue 後，他們可以選擇要授予的權限：

這樣，用戶便可知道登入程序成功，接著他們會看到確認訊息：

4.確認登入成功

在裝置介面上，您也應顯示確認訊息。理想情況下，訊息應包含用戶的名稱，以及其 Facebook 個人資料相片（可以的話）。

裝置畫面應一直顯示這則確認消息，直至用戶點擊 Continue 按鈕為止。有些用戶可能需要在其他地點將代碼輸入電腦，因此在繼續操作前，他們需要時間返回到您的裝置，並查看確認訊息。

用戶點擊 Continue 後，裝置將展示卓越的個人化體驗。

5.登出或中斷連線

用戶應能夠從您的裝置登出，且裝置不得儲存他們與 Facebook 之間的連繫。若要執行此動作，請要在您的裝置選單提供 Log out from Facebook 或 Disconnect from Facebook 選項。

當用戶選擇這個選項之後，您的裝置須從記憶體中刪除儲存的存取憑證。如果您將存取憑證儲存於資料庫或雲端儲存空間，您也應該將這些存取憑證刪除。您不需要執行 API 調用，也能將存取憑證設定為無效。

當用戶登出後，您的裝置應顯示步驟 1 中的初始呼籲字句。

建置裝置專用登入

裝置專用的 Facebook 登入可以讓裝置透過網絡直接執行 HTTP 調用。以下是您的裝置可以執行的 API 調用和回應。

載入您的應用程式管理中心，然後將「產品」＞「Facebook 登入」＞「設定」＞「使用裝置登入」改為「是」。

2.產生代碼

當用戶點擊 Connect to Facebook 或 Log in with Facebook 呼籲字句時，裝置應執行 HTTP POST：

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>

scope 參數為可選項目，必須包含登入審查流程批准使用的登入權限逗號分隔清單。

您可以在「應用程式設定」 -> 「進階」中找到 CLIENT_TOKEN，該憑證應與您的應用程式編號（以管線隔開：|）一同使用，以形成完整的 access_token。

redirect_uri 是可選參數。若您有提供網址，用戶成功完成登入流程後，該用戶就會被重新導向至該網址。這樣您就可以將該用戶登入至您應用程式的網站，以便管理帳戶的更多內容。該網址必須為有效的 OAuth 重新導向網址，並與您「應用程式設定」 -> 「進階」中所配置的網址相同。回應形式如下：

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

這個回應代表：

在您的裝置顯示「A1NWZ9」字串
要求用戶前往「facebook.com/device」並輸入這個代碼
這個代碼將在 420 秒後過期。如果您在此時段內沒有收到存取憑證，則應取消登入流程。
您的裝置需要每 5 秒輪詢裝置登入 API 一次，以了解是否已經成功授權。

3.顯示代碼

您的裝置應該要顯示出 user_code，並要求用戶在電腦或智能手機瀏覽 verification_uri，例如 facebook.com/device。詳情請參閱用戶體驗。

4.輪詢授權

您的裝置應該要輪詢裝置登入 API，以了解用戶是否成功授權您的應用程式。您應該要每隔 interval 的時段就進行一次這項動作，以回覆您在步驟 1 的調用，而該間隔將為每 5 秒一次。您的裝置應該要輪詢：

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"

根據用戶在授權流程的進度對此 API 調用作出的回應。您將會收到存取憑證或一個擁有特定子代碼的錯誤物件以執行剖析：

錯誤子代碼	回應範例	意義
`N/A`	`{"access_token": "ABCD...", "expires_in" : 5183996 }`	用戶已成功授權裝置。裝置現可使用 `access_token` 值執行經授權的 API 調用。
`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."}}`	用戶尚未授權您的應用程式。依照步驟 1 回覆中指定的頻率持續輪詢。
`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."}}`	您裝置的輪詢頻率過高。請將輪詢頻率調降至首次 API 調用中指定的間隔。
`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."}}`	裝置代碼已到期。取消裝置登入流程，並將用戶導回初始畫面。

5.確認登入成功

當您收到存取憑證時，即代表這名用戶已經成功授權您的應用程式。您應該在裝置上保留這個存取憑證，

這樣，用戶便知道自己成功登入，而您的裝置亦應顯示用戶姓名和個人資料相片（如適用），直至他們點擊 Continue。若要取得用戶的名稱和個人資料相片，您的裝置便需要執行標準 Graph API 調用：

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

您將在表格內取得回應：

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

顯示用戶的名稱和個人資料相片，直至他們在您的裝置點擊 Continue。

6.儲存存取憑證

您的裝置應該要保留存取憑證，以便向 Graph API 提出其他要求。

裝置登入存取憑證有效期最長為 60 天，然而此存取憑證將於許多情況下變為無效。例如，當用戶更改 Facebook 密碼時，存取憑證就會變為無效。

當憑證無效時，您的裝置亦應從記憶體中將之刪除。使用您裝置的用戶必須再次由步驟 1 開始執行裝置登入流程，以取得有效的新憑證。

解決疑難

我可以透過 HTTP 提出裝置流程要求嗎？
OAuth 2 需要使用 TLS/HTTPS。

我可以透過 GET 方法提出裝置流程要求嗎？
所有裝置流程要求都必須為 POST 要求。

如何更新我的裝置登入存取憑證？
裝置登入存取憑證的有效期最長為 60 天。

當憑證無效時，您的裝置亦應從記憶體中將之刪除。使用您裝置的用戶必須再次依照步驟 1 的指示執行裝置登入流程，以取得有效的新憑證。

若要深入了解重新整理憑證，請參閱存取憑證。

我在提出 POST 要求時遇到了 Invalid API method 錯誤，問題出在哪裡？
如果您提出 POST 要求時遇到以下錯誤：

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

您可能需要在應用程式中啟用「使用裝置登入」。

載入您的應用程式管理中心，然後將「產品」＞「Facebook 登入」＞「設定」＞「使用裝置登入」設為「是」。

我的裝置登入存取憑證無效。我該怎麼辦？
如果存取憑證無效，您的裝置應從記憶體中刪除憑證，並獲取新的憑證。使用您裝置的用戶必須再次依照步驟 1 的指示執行裝置登入流程，以取得有效的新憑證。