Bản xem trước đã xác thực

Tổng quan

Bản xem trước đã xác thực giúp nội dung hiển thị trước chính xác trên Workplace. Điều này đòi hỏi bạn phải hỗ trợ siêu dữ liệu bản xem trước đã xác thực theo định dạng mà Workplace yêu cầu, để khi người dùng chia sẻ URL dẫn đến nội dung của bạn, Workplace có thể tìm nạp siêu dữ liệu đó và tạo bản xem trước. Quy trình này thường được gọi là tạo bản xem trước liên kết.

Dù có thể lấy siêu dữ liệu để tạo bản xem trước cho URL công khai qua giao thức Open Graph và Trình thu thập dữ liệu trên Facebook, nhưng Facebook không thể áp dụng quy trình này đối với URL riêng tư (thường được chia sẻ trong Workplace hơn). Khi một người chia sẻ URL riêng tư vào Workplace, hệ thống sẽ gửi webhook đến URL gọi lại mà bạn xác định, đồng thời bạn sẽ có thể phản hồi bằng phần tải dữ liệu có chứa siêu dữ liệu mô tả URL nêu trên dành riêng cho người chia sẻ, từ đó hiển thị bản xem trước liên kết.

Quy trình này sẽ lặp lại với mỗi người dùng truy cập URL đã chia sẻ trên Workplace, giúp bạn kiểm soát khả năng hiển thị bản xem trước theo từng người dùng.

Với Bản xem trước đã xác thực dành cho Workplace, mọi người có thể chia sẻ thông tin theo cách an toàn và dễ dàng trên Workplace mà vẫn tôn trọng quyền riêng tư của tài liệu nguồn. Bằng việc hỗ trợ Bản xem trước đã xác thực, bạn có thể đảm bảo rằng nội dung hiển thị trước chính xác trên Workplace, theo cách đảm bảo quyền riêng tư.

Chia sẻ URL riêng tư

Trên Workplace, mọi người thường chia sẻ liên kết đến các tài nguyên nội bộ công ty mà chỉ một số người xem được. Còn Facebook là nền tảng mà mọi người thường chia sẻ nội dung công khai như tin bài hoặc bài viết trên blog.

URL công khai và riêng tư trên Workplace

Workplace cần một số siêu dữ liệu thì mới tạo được bản xem trước cho nội dung riêng tư của công ty. Với vai trò nhà cung cấp, bạn có thể chọn cung cấp hoặc không cung cấp siêu dữ liệu cho người xem hiện tại trên Workplace, tùy vào việc họ có được phép xem nội dung đó hay không.

Nội dung trong tài liệu này

Tài liệu này trình bày các thành phần cần thiết để hỗ trợ Bản xem trước đã xác thực, bao gồm:

• Bản xem trước đã xác thực
• Ánh xạ danh tính

Cấu hình

Để hỗ trợ bản xem trước đã xác thực, bạn sẽ cần đặt cấu hình ứng dụng của mình như sau:

• Được cài đặt trên cộng đồng Workplace hoặc trong một hay nhiều nhóm
• Quyền Tạo bản xem trước liên kết
• Khai báo một miền hoặc tập hợp miền, chứa những URL sẽ được tiện ích tích hợp của bạn tạo bản xem trước
• Đăng ký chủ đề webhook Link cho trường preview và đặt cấu hình URL gọi lại để cung cấp siêu dữ liệu

Webhooks

Nhận webhook

Chúng tôi sẽ gửi yêu cầu đến nhà cung cấp trong nhiều trường hợp:

1. Nếu một URL mới được chia sẻ mà chúng tôi chưa từng thấy trước đây (luôn từ khung soạn thảo).
2. Nếu một người dùng mới xem nội dung và chúng tôi không biết liệu người dùng đó có quyền truy cập hay không (luôn từ bảng feed).
3. Một nội dung hiện có được chia sẻ lại hoặc đã hết hạn (từ khung soạn thảo hoặc bảng feed).

Định dạng yêu cầu webhook

Trong bất kỳ trường hợp nào nêu trên, hệ thống sẽ gửi một webhook dưới dạng yêu cầu POST ở định dạng sau đây:

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

Phần tải dữ liệu này chứa các trường sau đây:

Ví dụ

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"
            }
        }]
    }]
}
    

Định dạng phản hồi webhook

Khi nhận được yêu cầu webhook, bạn sẽ cần cung cấp một phần tải dữ liệu có chứa siêu dữ liệu ở định dạng phản hồi cụ thể:

{
  "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
}

Phần tải dữ liệu này sẽ cần chứa các trường sau đây:

Phản hồi mẫu đầy đủ

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
}
    

Chế độ quyền riêng tư

Chế độ quyền riêng tư xác định khả năng hiển thị, cũng như việc chúng tôi có yêu cầu xác thực người dùng đối với người dùng hiện tại và người dùng sau này hay không.

1. organization: Hiển thị với người dùng, không cần xác thực người dùng
   Nếu nội dung hiển thị với người dùng, chúng tôi có thể hiển thị nội dung trực tiếp. Chế độ này áp dụng trong trường hợp nội dung được cho là hiển thị với tất cả mọi người trong cùng miền (công ty). Chúng tôi sẽ không gửi webhook mỗi khi có người dùng mới xem nội dung mới.
2. accessible: Hiển thị với người dùng hiện tại, nhưng có thể cần ánh xạ danh tính người dùng đối với những người khác.
   Nhà cung cấp biết rằng người dùng cụ thể này được phép xem nội dung, nhưng điều đó không có nghĩa là bất cứ ai khác cũng xem được. Chúng tôi sẽ hiển thị bản xem trước, nhưng vẫn tiếp tục gửi webhook đối với bất kỳ người dùng nào khác.
3. inaccessible: Không hiển thị với người dùng
   Nhà cung cấp biết rõ người dùng cũng như việc người dùng này không được phép xem nội dung. Chúng tôi sẽ hiển thị thông báo về quyền riêng tư (ví dụ: không thể truy cập, nội dung riêng tư, v.v.).

Dữ liệu bổ sung

Để hiển thị thêm thông tin trong bản xem trước liên kết, bạn có thể gửi tối đa 3 mục dữ liệu bổ sung. Mỗi mục dữ liệu bổ sung bao gồm một tập hợp các thành phần khóa giá trị. Tuy nhiên, giá trị có thể được định dạng theo nhiều cách.

Hiện có 4 định dạng được hỗ trợ:

• text: Sẽ hiển thị giá trị nguyên trạng, giá trị phải là chuỗi. Đối với định dạng này, dữ liệu bổ sung cũng có thể chứa thuộc tính color - phải là một trong các giá trị blue, green, yellow, orange hoặc red. Nếu có, giá trị sẽ được hiển thị với màu nền.
• date: Sẽ phân tích cú pháp giá trị ở định dạng ngày theo tiêu chuẩn ISO-8601 (không kèm thời gian) và hiển thị không kèm thời gian.
• datetime: Sẽ phân tích cú pháp giá trị ở định dạng ngày theo tiêu chuẩn ISO-8601 (có kèm thời gian cùng múi giờ) và hiển thị kèm thời gian theo múi giờ của người dùng.
• user: Sẽ phân tích cú pháp giá trị ở dạng ID người dùng và hiển thị tên người dùng.

Hệ thống sẽ bỏ qua thông số download_url nếu bạn không đặt dữ liệu bổ sung.

Hiển thị bản xem trước file (không bắt buộc)

Nếu chế độ quyền riêng tư của tài liệu được đánh dấu là organization hoặc accessible và có cung cấp URL tải xuống, chúng tôi sẽ gửi thêm một yêu cầu để tải dữ liệu xuống.

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

Sau đó, Workplace sẽ lấy file này và chuyển đổi thành ảnh để tạo thành bài viết có nhiều ảnh.

Ánh xạ danh tính

Như trình bày ở trên, để hiển thị bản xem trước đã xác thực, bạn cần thiết lập hình thức ánh xạ danh tính nào đó. Ánh xạ danh tính giúp kiểm soát việc người dùng Workplace có quyền xem nội dung đang được xem trước hay không, đồng thời đảm bảo việc tuân thủ quy tắc truy cập nội dung của bạn trên Workplace.

Ánh xạ toàn tổ chức

Hình thức ánh xạ danh tính đơn giản nhất là ánh xạ toàn tổ chức, trong đó người dùng chỉ cần là thành viên của một cộng đồng Workplace thì sẽ thấy bản xem trước trên Workplace. Trường hợp này thường áp dụng khi xem trước liên kết đến mạng nội bộ công ty hay bất kỳ dịch vụ nào mà toàn công ty đều xem được hết đối tượng (hoặc tối thiểu là siêu dữ liệu của đối tượng).

Khi cài đặt tiện ích tích hợp của mình trên một cộng đồng Workplace, bạn có thể kiểm tra ID của cộng đồng đó qua điểm cuối /community, sử dụng mã truy cập mà bạn nhận được khi cài đặt. Bạn có thể lưu trữ ID cộng đồng này cùng với mã truy cập và ánh xạ đến thông tin nhận dạng của một đối tượng thuê hoặc tổ chức trong hệ thống dịch vụ của mình. Việc này tạo ra một ánh xạ giữa cộng đồng Workplace và tổ chức trong hệ thống dịch vụ của bạn.

Sau đó, khi phản hồi các yêu cầu webhook bản xem trước đã xác thực, bạn có thể kiểm tra để đảm bảo rằng ID cộng đồng trong phần tải dữ liệu của webhook khớp với ID cộng đồng đã liên kết với tổ chức, rồi quyết định xem có nên trả về phần tải dữ liệu có chứa siêu dữ liệu hay không. Việc đánh dấu quyền riêng tư của phần tải dữ liệu nêu trên là ORGANIZATION sẽ đảm bảo rằng chúng tôi không cần gửi thêm webhook cho từng người dùng trong cộng đồng Workplace đó.

Ánh xạ theo từng người dùng

Nếu cần kiểm soát quyền truy cập chi tiết hơn, bạn có thể hỗ trợ ánh xạ theo từng người dùng, từ đó có thể chọn có hiển thị siêu dữ liệu cho từng người xem trên Workplace hay không. Workplace sẽ gửi kèm một ID người dùng trong mỗi phần tải dữ liệu webhook cho bản xem trước đã xác thực. Để hỗ trợ ánh xạ theo từng người dùng, bạn cần biết hồ sơ người dùng nào trong hệ thống của mình ánh xạ đến ID người dùng Workplace được gửi trong phần tải dữ liệu webhook.

Nếu đây là lần đầu tiên bạn tiếp nhận ID người dùng Workplace cụ thể, bạn có thể phản hồi với trường boolean linked_user được đặt là false. Việc này sẽ yêu cầu Workplace hiển thị nút Bật bản xem trước, nhắc người dùng liên kết tài khoản của họ.

Khi người dùng nhấn nút này, Workplace sẽ mở ra một hộp thoại đến điểm cuối liên kết tài khoản mà bạn xác định, tại đó bạn có thể xác thực phiên của người dùng trong hệ thống dịch vụ của mình. Workplace sẽ mở URL này thông qua yêu cầu POST và sẽ chuyển một thông số yêu cầu đã ký có chứa ID người dùng hiện tại và ID cộng đồng.

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
    

Phần tải dữ liệu có một thông số tên là signed_request, có chứa thông tin về người dùng này. Bạn có thể giải mã yêu cầu này như sau:

1. Tách nội dung thành 2 phần được phân cách bằng ký tự ".".
2. Giải mã phần đầu tiên - chữ ký - từ base64url.
3. Giải mã phần thứ hai - phần tải dữ liệu - từ base64url rồi giải mã đối tượng JSON thu được.
4. Xác minh để đảm bảo rằng chữ ký khớp với HMAC của phần tải dữ liệu đã mã hóa, dựa trên Khóa bí mật của ứng dụng.

Phần tải dữ liệu này chứa các trường sau đây:

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

Tại thời điểm này, bạn sẽ có ID người dùng Workplace và ID cộng đồng, cùng với phiên người dùng đã xác thực trong hệ thống dịch vụ của mình, đồng thời sẽ ghi lại được ID Workplace cho người dùng này bên cạnh ID của họ trong hệ thống dịch vụ đó. Sau khi hoàn tất, bạn nên chuyển hướng đến URL được cung cấp dưới dạng thông số truy vấn redirect_uri trong yêu cầu ban đầu.

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
...
    

Sau đó, Workplace sẽ nhận ra rằng quá trình ánh xạ danh tính đã hoàn tất và sẽ tìm cách yêu cầu siêu dữ liệu cho bản xem trước đã xác thực lần nữa. Lần này, bạn có thể phản hồi với linked_user được đặt là true và cung cấp siêu dữ liệu cần thiết.

Câu hỏi thường gặp