ดูวิธีทำงานกับ API รวมถึงวิธีใช้ Chrome Flag สำหรับการทดสอบ
สถานะการใช้งาน
- Topics API ได้เข้าสู่ช่วงการสนทนาแบบสาธารณะแล้ว และขณะนี้พร้อมให้บริการแก่ผู้ใช้ 99 เปอร์เซ็นต์ ซึ่งขยายได้สูงสุดถึง 100 เปอร์เซ็นต์
- หากต้องการแสดงความคิดเห็นเกี่ยวกับ Topics API โปรดแจ้งปัญหาในคำอธิบาย Topics หรือเข้าร่วมการสนทนาในการปรับปรุงกลุ่มธุรกิจการโฆษณาบนเว็บ คำถามอธิบายมีคําถามที่ยังไม่ได้หลายข้อซึ่งยังต้องการคําจํากัดความเพิ่มเติม
- ไทม์ไลน์ Privacy Sandbox แสดงลําดับเวลาการติดตั้งใช้งาน Topics API และข้อเสนออื่นๆ ของ Privacy Sandbox
- Topics API: อัปเดตล่าสุด มีรายละเอียดการเปลี่ยนแปลงและการปรับปรุง Topics API และการใช้งาน
ลองใช้
มีการสาธิต Topics API 2 รายการที่ให้คุณลองใช้ Topics ในฐานะผู้ใช้รายเดียว
- การสาธิต JavaScript API: topics-demo.glitch.me
- การสาธิตส่วนหัว: topics-fetch-demo.glitch.me
คุณเรียกใช้ 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 มาก เนื่องจาก API จำเป็นต้องสร้าง iframe แบบข้ามต้นทางและทำการเรียก document.browsingTopics()
จาก iframe (ต้องใช้ iframe แบบข้ามต้นทางสำหรับการเรียก เนื่องจากมีการใช้บริบทที่เรียกใช้ 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 ที่เลือกแผงสถานะหัวข้อ](https://developers.google.cn/static/privacy-sandbox/assets/images/the-chrometopics-inter-0a0a54332c409.png?authuser=3&hl=th)
ภาพหน้าจอนี้แสดงให้เห็นว่าเว็บไซต์ที่เข้าชมล่าสุดรวมถึง 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 ที่เลือกแผงตัวแยกประเภท](https://developers.google.cn/static/privacy-sandbox/assets/images/the-chrometopics-inter-680196727dbe8.png?authuser=3&hl=th)
การใช้งาน 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 ที่เลือกแผงฟีเจอร์และพารามิเตอร์](https://developers.google.cn/static/privacy-sandbox/assets/images/chrometopics-internals-a56a143c41aa1.png?authuser=3&hl=th)
พารามิเตอร์ที่แสดงในภาพหน้าจอจะสอดคล้องกับแฟล็กที่ตั้งค่าได้เมื่อเรียกใช้ 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")
ขั้นตอนถัดไป
- ดูข้อมูลเพิ่มเติมเกี่ยวกับหัวข้อและวิธีการทำงานของหัวข้อเหล่านั้น
- ทดลองใช้การสาธิต
ดูข้อมูลเพิ่มเติม
มีส่วนร่วมและแชร์ความคิดเห็น
- GitHub: อ่านคำอธิบายของ Topics API จากนั้นถามคำถามและติดตามการอภิปรายเกี่ยวกับปัญหาเกี่ยวกับที่เก็บ API
- W3C: พูดคุยเกี่ยวกับ Use Case ของอุตสาหกรรมในการปรับปรุงกลุ่มธุรกิจการโฆษณาบนเว็บ
- ประกาศ: เข้าร่วมหรือดูรายชื่ออีเมล
- การสนับสนุนสำหรับนักพัฒนาซอฟต์แวร์ Privacy Sandbox: ถามคำถามและเข้าร่วมการสนทนาในที่เก็บการสนับสนุนนักพัฒนาซอฟต์แวร์ของ Privacy Sandbox
- Chromium: รายงานข้อบกพร่องของ Chromium เพื่อถามคําถามเกี่ยวกับการติดตั้งใช้งานที่มีให้ทดสอบใน Chrome ในปัจจุบัน