พรีวิวที่ได้รับอนุญาต

ภาพรวม

พรีวิวที่ได้รับอนุญาตช่วยแสดงพรีวิวเนื้อหาของคุณบน Workplace ได้อย่างถูกต้อง โดยจะมีการรองรับเมตาดาต้าพรีวิวที่ได้รับอนุญาตในรูปแบบที่ Workplace กำหนด ดังนั้น เมื่อมีการแชร์ URL เนื้อหาของคุณ Workplace จะสามารถดึงเมตาดาต้านั้นมาสร้างพรีวิวได้ กระบวนการนี้มักเรียกกันว่าการขยายลิงก์ (Link Unfurling)

แม้ว่า Facebook จะสามารถรับเมตาดาต้าเพื่อขยาย URL สาธารณะผ่านโปรโตคอล Open Graph และครอว์เลอร์ Facebook ได้ แต่กระบวนการนี้ไม่สามารถดำเนินการกับ URL ส่วนตัว ซึ่งมีการแชร์ลงใน Workplace บ่อยครั้งกว่าได้ เมื่อมีผู้ใช้แชร์ URL ส่วนตัวลงใน Workplace ระบบจะส่ง Webhook ไปยัง URL การเรียกกลับที่คุณกำหนด และคุณจะสามารถตอบกลับด้วยเพย์โหลดเมตาดาต้าที่อธิบาย URL ดังกล่าวสำหรับผู้ใช้ที่แชร์เพื่อแสดงพรีวิวลิงก์

กระบวนการเดียวกันนี้จะเกิดขึ้นซ้ำกับผู้ใช้แต่ละรายที่ดู URL ที่แชร์บน Workplace ทำให้คุณสามารถควบคุมการมองเห็นพรีวิวตามผู้ใช้ได้

พรีวิวที่ได้รับอนุญาตสำหรับ Workplace ช่วยให้ผู้ใช้แชร์ข้อมูลบน Workplace ได้ง่ายและปลอดภัยโดยที่เคารพความเป็นส่วนตัวของเนื้อหาต้นทาง การรองรับพรีวิวที่ได้รับอนุญาตช่วยให้คุณมั่นใจได้ว่าเนื้อหาของคุณจะแสดงพรีวิวบน Workplace ได้อย่างถูกต้องในลักษณะที่เคารพความเป็นส่วนตัว

การแชร์ URL ส่วนตัว

ผู้ใช้บน Workplace มักแชร์ลิงก์ไปยังแหล่งข้อมูลภายในของบริษัท ซึ่งควรจะมีผู้ใช้บางรายเท่านั้นที่ดูได้ กรณีนี้แตกต่างจาก Facebook ที่ผู้ใช้มักแชร์เนื้อหาสาธารณะ เช่น บทความข่าวหรือบล็อกโพสต์

URL สาธารณะและส่วนตัวบน Workplace

Workplace จะต้องมีเมตาดาต้าบางรายการ เพื่อให้สามารถสร้างพรีวิวเนื้อหาส่วนตัวของบริษัทได้ ในฐานะผู้ให้บริการ คุณสามารถเลือกมอบเมตาดาต้าให้ผู้ชมปัจจุบันบน Workplace ได้ โดยขึ้นอยู่กับว่าผู้ชมได้รับอนุญาตให้ดูเนื้อหานั้นหรือไม่

ในเอกสารฉบับนี้

เอกสารฉบับนี้อธิบายองค์ประกอบของการเปิดใช้งานพรีวิวที่ได้รับอนุญาตดังต่อไปนี้

• พรีวิวที่ได้รับอนุญาต
• การจับคู่ข้อมูลระบุตัวตน

การกำหนดค่า

ในการเปิดใช้งานพรีวิวที่ได้รับอนุญาต คุณจำเป็นต้องกำหนดค่าแอพของคุณดังต่อไปนี้

• ติดตั้งแอพในชุมชน Workplace หรือในกลุ่มอย่างน้อย 1 กลุ่ม
• สิทธิ์การอนุญาตการขยายลิงก์ (Link Unfurling)
• โดเมนหรือชุดโดเมน ซึ่งประกอบด้วย URL ที่จะขยายด้วยการผสานการทำงานของคุณ
• การสมัครรับข้อมูล Webhook หัวข้อ Link สำหรับพรีวิวในช่อง และ URL การเรียกกลับสำหรับมอบเมตาดาต้า

Webhooks

การรับ Webhooks

มีหลายกรณีที่เราจะส่งคำขอไปยังผู้ให้บริการ ได้แก่

1. หากมีการแชร์ URL ใหม่ที่เรายังไม่เคยเห็นมาก่อน (มาจากช่องเขียนข้อความเสมอ)
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: แสดงผลแก่ผู้ใช้ปัจจุบัน แต่อาจต้องมีการจับคู่ข้อมูลระบุตัวตนผู้ใช้สำหรับผู้ใช้รายอื่นๆ
   ผู้ให้บริการทราบว่าผู้ใช้รายนี้ได้รับอนุญาตให้เห็นเนื้อหาดังกล่าว แต่ไม่ได้หมายความว่าคนอื่นๆ จะต้องเห็นเนื้อหาเดียวกันนั้นด้วย เราจะแสดงพรีวิว แต่จะยังคงส่ง Webhook สำหรับผู้ใช้รายอื่นต่อไป
3. inaccessible: ไม่แสดงผลแก่ผู้ใช้
   ผู้ให้บริการรู้จักผู้ใช้ และทราบว่าผู้ใช้รายดังกล่าวไม่ได้รับอนุญาตให้ดูเนื้อหา เราจะแสดงประกาศเกี่ยวกับความเป็นส่วนตัว (ไม่พร้อมใช้งาน, เนื้อหาส่วนตัว ฯลฯ)

ข้อมูลเพิ่มเติม

หากต้องการเพิ่มข้อมูลบนพรีวิวลิงก์ คุณสามารถส่งรายการข้อมูลเพิ่มเติมได้สูงสุด 3 รายการ รายการข้อมูลเพิ่มเติมประกอบด้วยชุดองค์ประกอบคีย์-ค่า แต่ค่าอาจมีรูปแบบต่างกัน

ปัจจุบันระบบรองรับทั้งหมด 4 รูปแบบ ได้แก่

• text: จะแสดงผลค่าตามจริง ค่าต้องเป็นสตริง ในรูปแบบนี้ ข้อมูลเพิ่มเติมยังสามารถมีพร็อพเพอร์ตี้ color ซึ่งต้องเป็นค่าใดค่าหนึ่งจาก blue, green, yellow, orange หรือ red หากมีค่าดังกล่าว ระบบจะแสดงผลค่าเป็นสีพื้นหลัง
• date: จะแยกวิเคราะห์ค่าเป็นรูปแบบวันที่ ISO-8601 โดยไม่ระบุเวลา และแสดงผลโดยไม่มีการระบุเวลา
• datetime: จะแยกวิเคราะห์ค่าเป็นรูปแบบวันที่ ISO-8601 โดยระบุเวลาและโซนเวลา และแสดงผลโดยมีการระบุเวลาในโซนเวลาของผู้ใช้
• user: จะแยกวิเคราะห์ค่าเป็น ID ผู้ใช้ และแสดงผลชื่อของผู้ใช้

ระบบจะไม่สนใจพารามิเตอร์ download_url หากมีการตั้งค่าข้อมูลเพิ่มเติม

การแสดงผลพรีวิวไฟล์ (ไม่บังคับ)

หากโหมดความเป็นส่วนตัวของเอกสารมีการระบุว่าเป็น organization หรือ accessible และมี URL สำหรับดาวน์โหลด เราจะส่งคำขอเพิ่มเติมเพื่อดาวน์โหลดข้อมูล

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 กรณีดังกล่าวมีการใช้งานกันโดยทั่วไปเมื่อแสดงพรีวิวลิงก์ไปยังอินทราเน็ตที่ใช้กันทั้งบริษัท หรือบริการใดๆ ที่อ็อบเจ็กต์ทั้งหมด (หรืออย่างน้อยที่สุดก็คือ เมตาดาต้าของบริการ) ปรากฏให้เห็นทั้งบริษัท

เมื่อติดตั้งการผสานการทำงานของคุณบนชุมชน Workplace แล้ว คุณสามารถตรวจสอบ ID ชุมชนได้ผ่านทางตำแหน่งข้อมูล /community โดยใช้โทเค็นการเข้าถึงที่ได้รับเมื่อทำการติดตั้ง คุณสามารถจัดเก็บ ID ชุมชนนี้ไว้กับโทเค็น และจับคู่กับตัวระบุผู้ใช้หรือองค์กรภายในบริการของคุณได้ ซึ่งจะเป็นการจับคู่ระหว่างชุมชน Workplace กับองค์กรในบริการของคุณ

จากนั้น เมื่อตอบกลับคำขอ Webhook พรีวิวที่ได้รับอนุญาต คุณจะสามารถตรวจสอบว่า ID ชุมชนของเพย์โหลด Webhook นั้นตรงกับ ID ชุมชนที่ลิงก์กับองค์กรหรือไม่ แล้วจึงตัดสินใจว่าปลอดภัยพอที่จะส่งคืนเพย์โหลดเมตาดาต้าหรือไม่ การระบุความเป็นส่วนตัวของเพย์โหลดเป็น ORGANIZATION ช่วยให้แน่ใจว่า เราจะไม่ต้องส่ง Webhook เพิ่มเติมให้ผู้ใช้แต่ละรายในชุมชน Workplace นั้น

การจับคู่รายผู้ใช้

หากจำเป็นต้องแบ่งระดับสิทธิ์การอนุญาตให้ละเอียดยิ่งขึ้นขึ้น คุณสามารถใช้การจับคู่รายผู้ใช้ ซึ่งช่วยให้คุณสามารถเลือกแสดงผลเมตาดาต้าแก่ผู้ชมแต่ละรายบน Workplace แยกกันได้ โดย Workplace จะส่ง ID ผู้ใช้ในแต่ละเพย์โหลด Webhook เพื่อขอพรีวิวที่ได้รับอนุญาต หากต้องการใช้การจับคู่รายผู้ใช้ คุณจะต้องทราบรายการข้อมูลผู้ใช้ในระบบของคุณที่จับคู่อยู่กับ ID ผู้ใช้ Workplace ที่ส่งมาในเพย์โหลด Webhook

หากคุณเพิ่งเคยเจอ ID ผู้ใช้ Workplace ดังกล่าวเป็นครั้งแรก คุณสามารถตอบกลับด้วยช่องบูลีน linked_user ที่ตั้งค่าเป็น false ได้ ระบบจะแจ้งให้ Workplace แสดงปุ่มเปิดใช้งานพรีวิว เพื่อแจ้งให้ผู้ใช้ลิงก์บัญชีของตน

เมื่อผู้ใช้กดปุ่มดังกล่าว Workplace จะเปิดกล่องโต้ตอบไปยังตำแหน่งข้อมูลการลิงก์บัญชีที่คุณกำหนด ซึ่งคุณสามารถตรวจสอบความถูกต้องของเซสชั่นผู้ใช้ในบริการของคุณได้ Workplace จะเปิด URL นี้ผ่านคำขอ POST และจะส่งต่อพารามิเตอร์คำขอที่ลงชื่อ ซึ่งประกอบด้วย ID ผู้ใช้ปัจจุบันและ ID ชุมชน

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 ส่วน คั่นด้วยอักขระ "."
2. ถอดรหัสส่วนที่ 1 - รายการลงชื่อ - จาก base64url
3. ถอดรหัสส่วนที่ 2 - เพย์โหลด - จาก base64url แล้วถอดรหัสได้ผลลัพธ์เป็นอ็อบเจ็กต์ JSON
4. ตรวจสอบยืนยันว่ารายการลงชื่อตรงกับ HMAC ของเพย์โหลดที่ถอดรหัส โดยอิงจากข้อมูลลับของแอพของคุณ

เพย์โหลดนี้ประกอบด้วยช่องต่อไปนี้

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

ในตอนนี้ คุณจะมี ID ผู้ใช้ Workplace และ ID ชุมชน พร้อมเซสชั่นผู้ใช้ที่ได้รับการตรวจสอบแล้วในบริการของคุณ และจะสามารถบันทึก ID ใน Workplace ของผู้ใช้รายนี้ข้าง ID ผู้ใช้ในบริการของคุณได้ เมื่อดำเนินการเสร็จแล้ว คุณจะเปลี่ยนเส้นทางไปยัง URL ที่ปรากฏในคำขอเดิมเป็นพารามิเตอร์การสืบค้น 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 และมอบเมตาดาต้าที่ Workplace ต้องการได้

คำถามที่พบบ่อย