คู่มือนักพัฒนาซอฟต์แวร์ 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 หัวข้อ โดยแต่ละหัวข้อสำหรับ 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 (เช่น ขนาดการจัดหมวดหมู่ จำนวนหัวข้อที่คำนวณต่อสัปดาห์และจำนวนหัวข้อที่แสดงผลต่อการเรียก 1 ครั้ง) อาจมีการเปลี่ยนแปลงเมื่อเรารวมความคิดเห็นของระบบนิเวศและทำซ้ำใน API

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

ก่อนใช้ API โปรดตรวจสอบว่าเบราว์เซอร์รองรับ 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} หมายความว่าการเรียกเมธอดจะไม่ทำให้หน้าปัจจุบันรวมอยู่ในการคำนวณหัวข้อ

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

คุณสามารถเข้าถึงหัวข้อและทำเครื่องหมายการเข้าชมหน้าเว็บเป็นสังเกตการณ์ได้ ด้วยความช่วยเหลือจาก request และ ส่วนหัวการตอบกลับ

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

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

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

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

  • fetch(): เพิ่ม {browsingTopics: true} ลงในพารามิเตอร์ตัวเลือกสำหรับคำขอ fetch() การสาธิตส่วนหัวของ Topics แสดงตัวอย่างให้ดูเข้าใจง่าย
  • แอตทริบิวต์ 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 จะแสดงข้อผิดพลาดหากคุณพยายามใส่ "/" ในฟิลด์โฮสต์

ดูข้อมูล 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
ค่าเริ่มต้น: เปิดใช้
เปิดใช้ Ads API: Attribution Reporting, Protected Audience, Topics, Fenced Frame

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 วินาทีอาจเป็น 15 วินาทีแทนค่าเริ่มต้น 7 วัน

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

BrowsingTopics:use_random_topic_probability_percent
ค่าเริ่มต้น: 5
ความน่าจะเป็นที่แต่ละหัวข้อภายใน Epoch จะเป็น 1 ผลลัพธ์ที่ได้จากการสุ่ม การจัดหมวดหมู่ทั้งหมด ในหัวข้อ การสุ่มเป็นแบบยึดติดกับ 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 การค้นหาจะเกิดขึ้น 1 ครั้งต่อ Epoch ในการคำนวณหัวข้อ จุดประสงค์คือการกำหนดขีดจำกัดการใช้งานหน่วยความจำสูงสุด

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

BrowsingTopics:config_version
ค่าเริ่มต้น: 1
เข้ารหัสพารามิเตอร์การกำหนดค่า Topics API หมายเลขเวอร์ชันแต่ละหมายเลขควรเป็น จับคู่กับชุดการกำหนดค่า 1 ชุดแล้ว การอัปเดตพารามิเตอร์การกำหนดค่าโดยไม่อัปเดต 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")

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

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

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