คู่มือนักพัฒนาซอฟต์แวร์ Topics API

ดูวิธีทำงานกับ API รวมถึงวิธีใช้ Chrome Flag สำหรับการทดสอบ

สถานะการใช้งาน

  • Topics API ได้เข้าสู่ช่วงการสนทนาแบบสาธารณะแล้ว และขณะนี้พร้อมให้บริการแก่ผู้ใช้ 99 เปอร์เซ็นต์ ซึ่งขยายได้สูงสุดถึง 100 เปอร์เซ็นต์
  • หากต้องการแสดงความคิดเห็นเกี่ยวกับ Topics API โปรดแจ้งปัญหาในคำอธิบาย Topics หรือเข้าร่วมการสนทนาในการปรับปรุงกลุ่มธุรกิจการโฆษณาบนเว็บ คำถามอธิบายมีคําถามที่ยังไม่ได้หลายข้อซึ่งยังต้องการคําจํากัดความเพิ่มเติม
  • ไทม์ไลน์ Privacy Sandbox แสดงลําดับเวลาการติดตั้งใช้งาน Topics API และข้อเสนออื่นๆ ของ Privacy Sandbox
  • Topics API: อัปเดตล่าสุด มีรายละเอียดการเปลี่ยนแปลงและการปรับปรุง Topics API และการใช้งาน

ลองใช้เดโม

มีการสาธิต Topics API 2 รายการที่ให้คุณลองใช้ Topics ในฐานะผู้ใช้รายเดียว

คุณเรียกใช้ colab ของ Topics เพื่อลองใช้โมเดลตัวแยกประเภทของ Topics ได้เช่นกัน

ใช้ JavaScript API เพื่อเข้าถึงหัวข้อและบันทึกตามหัวข้อ

Topics JavaScript API มี 1 วิธีคือ document.browsingTopics() โดยมีจุดประสงค์ 2 ประการ ได้แก่

  • บอกเบราว์เซอร์ให้บันทึกการเข้าชมหน้าเว็บปัจจุบันตามที่สังเกตได้สำหรับผู้โทร เพื่อสามารถใช้ข้อมูลนี้ในการคำนวณหัวข้อสำหรับผู้ใช้ (สำหรับผู้โทร) ในภายหลัง
  • เข้าถึงหัวข้อสำหรับผู้ใช้ที่ผู้โทรสังเกตการณ์

เมธอดจะส่งกลับคำสัญญาที่แปลงค่าเป็นอาร์เรย์สูงสุด 3 หัวข้อ โดยแสดงผล 1 หัวข้อต่อ Epoch 3 รายการล่าสุดตามลำดับแบบสุ่ม Epoch เป็นช่วงเวลาหนึ่งในการติดตั้งใช้งาน Chrome เป็น 1 สัปดาห์

ออบเจ็กต์หัวข้อแต่ละรายการในอาร์เรย์ที่ document.browsingTopics() แสดงผลมีพร็อพเพอร์ตี้ต่อไปนี้

  • configVersion: สตริงที่ระบุการกำหนดค่า Topics API ปัจจุบัน เช่น chrome.2
  • modelVersion: สตริงที่ระบุตัวแยกประเภทแบบแมชชีนเลิร์นนิงที่ใช้ในการอนุมานหัวข้อสำหรับเว็บไซต์ เช่น 4
  • taxonomyVersion: สตริงที่ระบุชุดหัวข้อที่เบราว์เซอร์ใช้ เช่น 2
  • topic: ตัวเลขที่ระบุหัวข้อในการจัดหมวดหมู่ เช่น 309
  • version: สตริงที่เชื่อมต่อ configVersion, taxonomyVersion และ modelVersion เช่น chrome.2:2:4

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

ตรวจหาการรองรับ document.browsingTopics

ก่อนใช้ API โปรดตรวจสอบว่าเบราว์เซอร์รองรับและพร้อมใช้งานในเอกสารหรือไม่

'browsingTopics' in document && document.featurePolicy.allowsFeature('browsing-topics') ?
 console.log('document.browsingTopics() is supported on this page') :
 console.log('document.browsingTopics() is not supported on this page');

เข้าถึงหัวข้อด้วย JavaScript API

ต่อไปนี้เป็นตัวอย่างพื้นฐานของการใช้ API ที่เป็นไปได้เพื่อเข้าถึงหัวข้อสำหรับผู้ใช้ปัจจุบัน

try {
  // Get the array of top topics for this user.
  const topics = await document.browsingTopics();
  
  // Request an ad creative, providing topics information.
  const response = await fetch('https://ads.example/get-creative', {
   method: 'POST',
   headers: {
     'Content-Type': 'application/json',
   },
   body: JSON.stringify(topics)
  })
  
  // Get the JSON from the response.
  const creative = await response.json();
  
  // Display ad.

} catch (error) {
  // Handle error.
}

เข้าถึงหัวข้อโดยไม่แก้ไขสถานะ

document.browsingTopics() แสดงผลหัวข้อที่ผู้โทรสังเกตสำหรับผู้ใช้ปัจจุบัน โดยค่าเริ่มต้น วิธีการนี้จะทำให้เบราว์เซอร์บันทึกการเข้าชมหน้าเว็บปัจจุบันตามที่ผู้โทรสังเกต เพื่อให้สามารถนำมาใช้ในการคำนวณหัวข้อได้ในภายหลัง จาก Chrome 108 คุณสามารถส่งเมธอดด้วยอาร์กิวเมนต์ที่ไม่บังคับเพื่อไม่ให้ระบบบันทึกการเข้าชมหน้าเว็บ: {skipObservation:true}

กล่าวคือ {skipObservation:true} หมายความว่าการเรียกใช้เมธอดจะไม่ทำให้หน้าปัจจุบันรวมอยู่ในการคำนวณหัวข้อ

ใช้ส่วนหัวเพื่อเข้าถึงหัวข้อและทำเครื่องหมายเป็นสังเกตการณ์

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

คุณสามารถเข้าถึงหัวข้อได้จากส่วนหัว Sec-Browsing-Topics ของคําขอ fetch() หรือ XHR

การตั้งค่าส่วนหัว Observe-Browsing-Topics: ?1 ในการตอบสนองต่อคำขอทำให้เบราว์เซอร์บันทึกการเข้าชมหน้าปัจจุบันตามที่ผู้โทรสังเกตได้ เพื่อใช้ในการคำนวณหัวข้อในภายหลัง

ผู้ใช้สามารถเข้าถึงและสังเกตหัวข้อด้วยส่วนหัว HTTP ได้ 2 วิธี ดังนี้

  • fetch(): เพิ่ม {browsingTopics: true} ลงในพารามิเตอร์ตัวเลือกของคําขอ fetch() การสาธิตส่วนหัวของหัวข้อแสดงตัวอย่างง่ายๆ
  • แอตทริบิวต์ iframe: เพิ่มแอตทริบิวต์ browsingtopics ลงในองค์ประกอบ <iframe> หรือตั้งค่าพร็อพเพอร์ตี้ JavaScript ที่เทียบเท่า iframe.browsingTopics = true โดเมนที่ลงทะเบียนได้ของแหล่งที่มาของ iframe คือโดเมนของผู้เรียกใช้ เช่น สำหรับ <iframe src="https://example.com" browsingtopics></iframe>: ผู้เรียกใช้คือ example.com

หมายเหตุเพิ่มเติมเกี่ยวกับส่วนหัว

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

แก้ปัญหาการใช้งาน API

หน้า chrome://topics-internals จะพร้อมใช้งานใน Chrome บนเดสก์ท็อปเมื่อเปิดใช้ Topics API แล้ว คอลัมน์นี้จะแสดงหัวข้อสำหรับผู้ใช้ปัจจุบัน หัวข้อที่อนุมานสำหรับชื่อโฮสต์ และข้อมูลทางเทคนิคเกี่ยวกับการใช้งาน API เรากำลังปรับปรุงและปรับปรุงการออกแบบหน้าเว็บตามความคิดเห็นของนักพัฒนาแอป โปรดเพิ่มความคิดเห็นของคุณที่ bugs.chromium.org

ดูหัวข้อที่คำนวณสำหรับเบราว์เซอร์ของคุณ

ผู้ใช้จะดูข้อมูลเกี่ยวกับหัวข้อที่สังเกตในเบราว์เซอร์ระหว่าง Epoch ปัจจุบันและก่อนหน้าได้โดยดู chrome://topics-internals

หน้า chrome://topics-internals ที่เลือกแผงสถานะหัวข้อ
แผงสถานะหัวข้อของหน้า chrome://topics-internals แสดงรหัสหัวข้อ การกำหนดหัวข้อแบบสุ่มและจริง รวมทั้งเวอร์ชันการจัดหมวดหมู่และโมเดล

ภาพหน้าจอนี้แสดงให้เห็นว่าเว็บไซต์ที่เข้าชมล่าสุดรวมถึง topics-demo-cats.glitch.me และ cats-cats-cats-cats.glitch.me การดำเนินการนี้จะทำให้ Topics API เลือก Pets และ Cats เป็น 2 หัวข้อยอดนิยมสำหรับ Epoch ปัจจุบัน หัวข้อที่เหลือ 3 หัวข้อได้รับการเลือกแบบสุ่มเนื่องจากมีประวัติการท่องเว็บ (ในเว็บไซต์ที่ดูหัวข้อ) ไม่เพียงพอที่จะระบุ 5 หัวข้อ

คอลัมน์โดเมนบริบทที่สังเกตได้ (แฮช) ระบุค่าที่แฮชของชื่อโฮสต์ที่มีการสังเกตหัวข้อ

ดูหัวข้อที่อนุมานสำหรับชื่อโฮสต์

คุณยังสามารถดูหัวข้อที่อนุมานโดยโมเดลตัวแยกประเภทหัวข้อสำหรับชื่อโฮสต์อย่างน้อย 1 รายการใน chrome://topics-internals ได้ด้วย

หน้า chrome://topics-internals ที่เลือกแผงตัวแยกประเภท
แผงตัวแยกประเภทของหน้า chrome://topics-internals จะแสดงหัวข้อที่เลือก โฮสต์ที่เข้าชม รวมถึงเวอร์ชันและเส้นทางของโมเดล

การใช้งาน Topics API ในปัจจุบันอนุมานหัวข้อจากชื่อโฮสต์เท่านั้น ไม่ใช่จากส่วนอื่นๆ ของ URL

ใช้ชื่อโฮสต์เท่านั้น (ไม่มีโปรโตคอลหรือเส้นทาง) เพื่อดูหัวข้อที่สรุปจากตัวแยกประเภท chrome://topics-internals chrome://topics-internals จะแสดงข้อผิดพลาดหากคุณพยายามใส่ "/" ในช่อง Host

ดูข้อมูล Topics API

คุณสามารถดูข้อมูลเกี่ยวกับการใช้งานและการตั้งค่า Topics API เช่น เวอร์ชันการจัดหมวดหมู่ และระยะเวลา Epoch ได้ใน chrome://topics-internals ค่าเหล่านี้แสดงการตั้งค่าเริ่มต้นสำหรับ API หรือพารามิเตอร์ที่ตั้งค่าเรียบร้อยแล้วจากบรรทัดคำสั่ง ซึ่งอาจเป็นประโยชน์ในการยืนยันว่าแฟล็กบรรทัดคำสั่งทำงานตามที่คาดไว้

ในตัวอย่างนี้ time_period_per_epoch ตั้งไว้ที่ 15 วินาที (ค่าเริ่มต้นคือ 7 วัน)

หน้า chrome://topics-internals ที่เลือกแผงฟีเจอร์และพารามิเตอร์
แผง chrome://topics-internals ฟีเจอร์และพารามิเตอร์ จะแสดงฟีเจอร์ที่เปิดใช้ เวลาที่ใช้ต่อ Epoch จำนวน Epoch ที่จะใช้เพื่อคำนวณหัวข้อ เวอร์ชันการจัดหมวดหมู่ และการตั้งค่าอื่นๆ

พารามิเตอร์ที่แสดงในภาพหน้าจอจะสอดคล้องกับแฟล็กที่ตั้งค่าได้เมื่อเรียกใช้ Chrome จากบรรทัดคำสั่ง ตัวอย่างเช่น การสาธิตที่ topics-fetch-demo.glitch.me แนะนำให้ใช้แฟล็กต่อไปนี้

--enable-features=BrowsingTopics,BrowsingTopicsParameters:time_period_per_epoch/15s/max_epoch_introduction_delay/3s,PrivacySandboxAdsAPIsOverride,PrivacySandboxSettings3,OverridePrivacySandboxSettingsLocalTesting

รายการต่อไปนี้อธิบายพารามิเตอร์แต่ละรายการ ค่าเริ่มต้น และวัตถุประสงค์

Chrome Flag

BrowsingTopics
ค่าเริ่มต้น: เปิดใช้แล้ว
ระบุว่ามีการเปิดใช้ Topics API หรือไม่

PrivacySandboxAdsAPIsOverride
ค่าเริ่มต้น: เปิดใช้
เปิดใช้ API โฆษณา: Attribution Reporting, กลุ่มเป้าหมายที่มีการป้องกัน, หัวข้อ, เฟรมที่มีการปิดกั้น

PrivacySandboxSettings4
ค่าเริ่มต้น: ปิดใช้อยู่
เปิดใช้การตั้งค่า UI ของ Privacy Sandbox รุ่นที่ 4

OverridePrivacySandboxSettingsLocalTesting
ค่าเริ่มต้น: เปิดใช้
หากเปิดใช้ เบราว์เซอร์จะไม่จําเป็นต้องเปิดใช้การตั้งค่าพื้นฐานเพื่อเปิดใช้ฟีเจอร์ Privacy Sandbox อีกต่อไป

BrowsingTopicsBypassIPIsPubliclyRoutableCheck
ค่าเริ่มต้น: ปิดใช้อยู่
หากเปิดใช้ ระบบจะข้ามการตรวจสอบว่าที่อยู่ IP กำหนดเส้นทางแบบสาธารณะได้หรือไม่ เมื่อพิจารณาการมีสิทธิ์รวมหน้าเว็บในการคำนวณหัวข้อ

BrowsingTopics:number_of_epochs_to_expose
ค่าเริ่มต้น: 3
จำนวน Epoch จากตำแหน่งที่จะคำนวณหัวข้อที่จะส่งไปยังบริบทที่ส่งคำขอ เบราว์เซอร์จะอัปเดต Epoch ภายใน N+1 ภายใน

BrowsingTopics:time_period_per_epoch
ค่าเริ่มต้น: 7d-0h-0m-0s
ระยะเวลาของแต่ละ Epoch สำหรับการแก้ไขข้อบกพร่อง ขอแนะนำให้ตั้งค่าเป็น (เช่น) 15 วินาทีแทนที่จะเป็น 7 วันตามค่าเริ่มต้น

BrowsingTopics:number_of_top_topics_per_epoch
ค่าเริ่มต้น: 5
จำนวนหัวข้อที่คำนวณต่อ Epoch

BrowsingTopics:use_random_topic_probability_percent
ค่าเริ่มต้น: 5
ความน่าจะเป็นที่แต่ละหัวข้อภายใน Epoch เป็นการแสดงผลหนึ่งแบบสุ่มจากการจัดหมวดหมู่ของหัวข้อทั้งหมด การสุ่มจะติดอยู่ที่ Epoch และเว็บไซต์

BrowsingTopics:number_of_epochs_of_observation_data_to_use_for_filtering
ค่าเริ่มต้น: 3
จำนวน Epoch ของข้อมูลการใช้งาน API (เช่น การสังเกตการณ์หัวข้อ) ที่จะใช้ในการกรองหัวข้อสำหรับบริบทการโทร

BrowsingTopics:max_number_of_api_usage_context_domains_to_keep_per_topic
ค่าเริ่มต้น: 1000
จำนวนสูงสุดของโดเมนตามบริบทที่สังเกตได้ที่จะเก็บไว้สำหรับแต่ละหัวข้อยอดนิยม โดยมีจุดประสงค์เพื่อ จำกัดหน่วยความจำที่ใช้งานอยู่

BrowsingTopics:max_number_of_api_usage_context_entries_to_load_per_epoch
ค่าเริ่มต้น: 100000
จำนวนรายการสูงสุดที่อนุญาตให้ดึงจากฐานข้อมูลสำหรับการค้นหาแต่ละรายการสำหรับบริบทการใช้งาน API การค้นหาจะเกิดขึ้นครั้งเดียวต่อ Epoch ในเวลาที่มีการคำนวณหัวข้อ โดยมีจุดประสงค์เพื่อจำกัดการใช้งานหน่วยความจำสูงสุด

BrowsingTopics:max_number_of_api_usage_context_domains_to_store_per_page_load
ค่าเริ่มต้น: 30
จำนวนโดเมนบริบทการใช้งาน API สูงสุดที่อนุญาตให้จัดเก็บได้ต่อการโหลดหน้าเว็บ

BrowsingTopics:config_version
ค่าเริ่มต้น: 1
เข้ารหัสพารามิเตอร์การกำหนดค่า Topics API หมายเลขเวอร์ชันแต่ละเวอร์ชันควรแมปกับชุดการกำหนดค่าเพียงชุดเดียวเท่านั้น โดยปกติแล้ว การอัปเดตพารามิเตอร์การกำหนดค่าโดยไม่อัปเดต config_version สามารถทำได้ง่ายๆ สำหรับการทดสอบภายในเครื่อง แต่ในบางกรณีอาจทำให้เบราว์เซอร์อยู่ในสถานะที่ไม่สอดคล้องกันและอาจส่งผลให้เบราว์เซอร์ขัดข้อง เช่น การอัปเดต number_of_top_topics_per_epoch

BrowsingTopics:taxonomy_version
ค่าเริ่มต้น: 1
เวอร์ชันการจัดหมวดหมู่ที่ API ใช้

เลือกไม่ใช้เว็บไซต์ของคุณ

คุณเลือกไม่ใช้การคำนวณหัวข้อสำหรับหน้าบางหน้าในเว็บไซต์ได้โดยรวมส่วนหัว Permissions-Policy: browsing-topics=() Permissions-Policy ไว้ในหน้าเว็บเพื่อไม่ให้มีการคำนวณหัวข้อสำหรับผู้ใช้ทั้งหมดในหน้านั้นเท่านั้น การเข้าชมหน้าอื่นๆ ในเว็บไซต์ในภายหลังจะไม่ได้รับผลกระทบ: หากคุณกำหนดนโยบายให้บล็อก Topics API ในหน้าหนึ่ง ก็จะไม่ส่งผลต่อหน้าอื่นๆ

คุณยังควบคุมว่าจะให้บุคคลที่สามรายใดเข้าถึงหัวข้อในหน้าเว็บได้โดยใช้ส่วนหัว Permissions-Policy เพื่อควบคุมการเข้าถึง Topics API ของบุคคลที่สาม ในฐานะพารามิเตอร์ของส่วนหัว ให้ใช้ self และโดเมนที่คุณต้องการอนุญาตให้เข้าถึง API เช่น หากต้องการปิดใช้ Topics API โดยสมบูรณ์ภายในบริบทการท่องเว็บทั้งหมด ยกเว้นต้นทางของคุณเองและ https://example.com ให้ตั้งค่าส่วนหัวการตอบกลับ HTTP ต่อไปนี้

Permissions-Policy: browsing-topics=(self "https://example.com")

ขั้นตอนถัดไป

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

มีส่วนร่วมและแชร์ความคิดเห็น