驗證預覽

總覽

驗證預覽可讓您在 Workplace 上正確預覽內容。其必須以 Workplace 所需的格式支援驗證預覽中繼資料，以便在分享內容的網址時，Workplace 可以擷取該中繼資料並建立預覽。此程序通常稱為連結展開。

雖然 Facebook 可以經由開放社交關係圖通訊協定和 Facebook 網路爬蟲取得中繼資料，展開公開網址，但由於私密網址較常分享至 Workplace，因此不適用此程序。有人將私密網址分享至 Workplace 時，系統會向您定義的回呼網址發出 Webhook，而您將能使用描述分享者網址的中繼資料裝載加以回覆，以顯示連結預覽。

每位用戶在 Workplace 查看分享網址時，這個程序會重複執行，讓您能針對各個用戶控制預覽能見度。

驗證 Workplace 允許用戶在 Workplace 上安全、輕鬆地分享資訊，同時尊重來源內容的隱私。透過支援驗證預覽，您可以確保在 Workplace 上以安全的隱私感知方式正確預覽內容。

分享私密網址

用戶經常會在 Workplace 上分享公司內部資源的連結，而這些資源應該只有特定用戶才能查看。這與 Facebook 形成明顯對比，因為用戶普遍會在 Facebook 上分享公開內容，例如新聞文章或部落格文章。

Workplace 上的公開和私密網址

為了讓 Workplace 產生公司私密內容的預覽，您需要提供一些中繼資料。您可以供應商的身分選擇是否為 Workplace 上的現有觀看者提供中繼資料，其取決於是否允許他們查看內容。

本文內容

本文件概述啟用驗證預覽的元件，包括：

• 驗證預覽
• 身分映射

配置

為了啟用驗證預覽，您需要針對以下項目配置應用程式：

• 安裝在 Workplace 社群中，或安裝在一或多個群組中
• 連結展開權限
• 一個網域或一組網域，組成將由整合展開的網址
• 訂閱 Webhook 主題連結（用於欄位預覽）和回呼網址（用於提供中繼資料）

Webhooks

接收 Webhooks

我們會在多種情況下向供應商傳送要求：

1. 如果分享我們以前從未見過的新網址（一律來自建立者）。
2. 如果新用戶正在查看一段內容，而我們不知道該用戶是否具有存取權限（一律來自動態消息）。
3. 現有內容經重新分享或已過期（來自建立者或動態消息）。

Webhook 要求格式

在上述任何一種情況下，系統都會將 Webhook 以 POST 要求傳送，格式如下：

{
  "object": "link",
  "entry": [
    {
      "time": int,
      "changes": [
        {
          "field": "preview",
          "value": {
            "community": {
              "id": string,
            },
            "user": {
              "id": string,
            },
            "link": string,
          }
        }
      ]
    }
  ]
}
    

此承載包含以下欄位：

範例

POST /callback HTTP/1.1
Host: third-party.com
Accept: application/json
Content-Type: application/json
User-Agent: Webhooks/1.0 (https://fb.me/webhooks)
X-Hub-Signature: sha1=bf3102e52efd0fd4bd26277030aa180d7b5cf587
...

{
    "object": "link",
    "entry": [{
        "time": 1501515097793,
        "changes": [{
            "field": "preview",
            "value": {
                "community": {
                    "id": "138169208138649"
                },
                "user": {
                    "id": "88575656148087"
                }
                "link": "https://company.third-party.com/document-about-this"
            }
        }]
    }]
}
    

Webhook 回應格式

當您收到 Webhook 要求時，需要以特定回應格式提供中繼資料承載：

{
  "data": [
    {
      "link": string,
      ?"canonical_link": string,
      ?"title": string,
      ?"description": string,
      ?"icon": string,
      ?"download_url": string,
      "privacy": 'organization' | 'accessible' | 'inaccessible',
      ?"type": 'document' | 'folder' | 'task' | 'link',
      ?"additional_data": [
        {
          "title" => string,
          "format" => 'text' | 'date' | 'datetime' | 'user',
          "value" => string | number,
          ?"color" => 'blue' | 'green' | 'yellow' | 'orange' | 'red',
        },
      ],
    }
  ],
  ?"linked_user": boolean
}

此承載應包含以下欄位：

完整回應範例

HTTP/1.1 200 OK
Content-Type: application/json
X-Hub-Signature: sha1=b5a6f32f084100ae5b355174b9bb8398f5fbe983
...

{
  "data": [
    {
      "link": "https://taaskly.herokuapp.com/task/4",
      "title": "Launch Workplace Integration for F8",
      "privacy": "organization",
      "type": "task",
      "additional_data": [
        {
          "title": "Owner",
          "format": "user",
          "value": "319922278498384"
        },
        {
          "title": "Created",
          "format": "datetime",
          "value": "2018-02-28T03:35:40.827Z"
        },
        {
          "title": "Priority",
          "format": "text",
          "value": "high",
          "color": "red"
        }
      ]
    }
  ],
  "linked_user": true
}
    

隱私模式

無論我們是否要求現有和後續用戶進行用戶驗證，隱私模式皆可決定能見度。

1. organization：用戶可查看，不需要用戶驗證
   如果用戶可查看，我們會直接顯示內容。此狀況會處理一段應該可讓網域（公司）中任何人查看的內容。我們不會在每當有新用戶看到新內容時皆傳送 Webhook。
2. accessible：現有用戶可查看，但其他人可能需要用戶身分映射。
   供應商知道此特定用戶獲允許查看該段內容，但不表示其他任何人都一定可以查看。我們會顯示預覽，但將繼續為任何其他用戶傳送 Webhooks。
3. inaccessible：用戶不可查看
   供應商認識用戶，且知道他們未獲允許查看內容。我們會顯示隱私聲明（不可用、隱私等）。

額外資料

若要在連接預覽中新增更多資訊，您最多可以傳送三個額外資料項目。額外資料項目是由一組索引鍵值元素組成。但是，該值可採用不同的方式進行格式化。

目前支援四種不同的格式：

• text：將以原來的樣式顯示，該值必須為字串。若是此格式，額外資料也可以包含 color 屬性，其值必須為 blue、green、yellow、orange 或 red 其中之一。如有設定，將顯示該顏色的值作為背景。
• date：將值解析為不含時間的 ISO-8601 日期格式，並在不含時間指示的情況下顯示。
• datetime：將值解析為包含時間和時區的 ISO-8601 日期格式，並在用戶時區中使用時間指示顯示。
• user：將該值解析為用戶編號並顯示用戶名稱。

如果設定額外資料，系統會忽略 download_url 參數。

顯示檔案預覽（選用）

如果文件的隱私模式標記為 organization 或 accessible，並且提供下載網址，我們將傳送額外要求來下載資料。

GET /download/super-fancy-document HTTP/1.1
Host: provider.com
Accept: <some mime types>
User-Agent: Webhooks/1.0 (https://fb.me/webhooks)
X-Hub-Signature: sha1=bf3102e52efd0fd4bd26277030aa180d7b5cf587

Workplace 接著會取得此檔案並將其轉換為相片，以製作多張相片的貼文。

身分映射

如上所述，提供驗證預覽需要某些身分映射。身分映射可控制 Workplace 用戶是否有權限查看正在預覽的內容，並確保在 Workplace 上遵守內容的存取規則。

組織範圍映射

最簡單的身分映射形式是組織範圍映射，其中 Workplace 社群的成員已足以允許在 Workplace 上向用戶顯示預覽。當預覽連結公司範圍 Intranet 或整個公司可查看所有物件（或至少其中繼資料）的任何服務時，此情況很常見。

在 Workplace 社群中安裝整合後，您就可以使用安裝時所擷取的存取權杖，經由 /community 端點檢查社群編號。您可以將此社群編號與權杖一起儲存，並將其映射至服務內的用戶或組織識別碼。如此可在 Workplace 社群和服務中的組織之間建立映射。

接著，當回覆驗證預覽 Webhook 要求時，您就可以檢查 Webhook 承載的社群編號是否與組織連結的社群編號相符，然後決定傳回中繼資料承載是否安全。將該承載的隱私標記為 ORGANIZATION 時，可確保我們不需為該 Workplace 社群中的每個用戶傳送額外的 Webhooks。

每用戶映射

如果需要更多權限資料粒度，您可以支援每用戶映射，確保您可以選擇是否個別向 Workplace 上的每個觀看者顯示中繼資料。Workplace 會在每個 Webhook 承載中傳送一個用戶編號，用於驗證預覽。若要支援每用戶映射，您需要知道系統中的哪個用戶記錄映射至 Webhook 承載中傳送的 Workplace 用戶編號。

如果這是您第一次遇到給定的 Workplace 用戶編號，可以使用設定為 false 的 linked_user 布林值欄位進行回覆。如此將指示 Workplace 顯示「啟用預覽」按鈕，提示用戶連結其帳號。

按下該按鈕後，Workplace 將開啟一個對話方塊，指向您定義的帳號連結端點，您可以在這裡驗證服務中的用戶連線階段。Workplace 將經由 POST 要求開啟此網址，並傳遞一個簽署要求參數，內容包含現有用戶編號和社群編號。

POST https://www.example.com/account_linking?redirect_uri=https%3A%2F%2Ffoxfabrics.facebook.com%2Flink_complete HTTP/1.1
Host: foxfabrics.third-party.com
Origin: http://www.facebook.com
Content-Type: application/x-www-form-urlencoded
User-Agent: Mozilla/5.0 Gecko/20100101 Firefox/57.0
...

signed_request=238fsdfsd.oijdoifjsidf899
    

承載中有一個 signed_request 參數，內容包含有關此用戶的資訊。此要求可依下列方式解碼：

1. 以分隔字元「.」為界，將內容分割成兩個部分。
2. 從 base64url 解碼第一部分 - 簽名。
3. 從 base64url 解碼第二部分 - 承載，然後解碼產生的 JSON 物件。
4. 根據應用程式密鑰驗證簽名是否與編碼承載的 HMAC 相符。

承載包含以下欄位：

{
  "algorithm": "HMAC-SHA256",
  "user_id": "88575656148087",
  "community_id": "138169208138649"
}
    

此時，您在服務中將擁有 Workplace 用戶編號和社群編號，以及經過驗證的用戶連線階段，並且能夠在服務中將此用戶的 Workplace 編號記錄在其編號旁邊。完成後，您應重新導向至原始要求所提供的網址，作為查詢參數 redirect_uri。

GET {$redirect_uri} HTTP/1.1
Host: foxfabrics.facebook.com
User-Agent: Mozilla/5.0 Gecko/20100101 Firefox/57.0
Referer: https://www.example.com/account_linking
...
    

接著，Workplace 將識別身分映射已完成，並嘗試再次要求驗證預覽中繼資料。此時，您可以將 linked_user 設為 true 進行回覆，並提供必要的中繼資料。

常見問題