ใช้ Topics API

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

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

สังเกตและเข้าถึง Topics

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

ส่วนหัว HTTP

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

เริ่มคําขอ

การใช้ Topics กับส่วนหัวทำได้ 2 วิธีดังนี้

• โดยการเข้าถึงส่วนหัวคำขอและคำตอบในคำขอ fetch() ที่มีตัวเลือก browsingTopics: true
• โดยการเข้าถึงส่วนหัวขององค์ประกอบ iframe ที่มีแอตทริบิวต์ browsingtopics

เริ่มคําขอด้วยการดึงข้อมูล

เมื่อใช้การเรียกข้อมูล ผู้เรียก API จะส่งคำขอที่มี {browsingTopics: true} ในพารามิเตอร์ options ต้นทางของพารามิเตอร์ URL ของคําขอดึงข้อมูลคือต้นทางที่พบว่ามีหัวข้อที่สังเกตได้

   fetch('<topics_caller_eTLD+1>', { browsingTopics: true })
    .then((response) => {
        // Process the response
    });

ประเด็นสําคัญ: คําสั่ง CSP อาจไม่อนุญาตให้เรียกใช้โค้ดของบุคคลที่สามที่รวมอยู่ในหน้า เช่น การเรียกใช้ fetch() ในสคริปต์เทคโนโลยีโฆษณา

เริ่มคําขอด้วย iframe

เพิ่มแอตทริบิวต์ browsingtopics ลงในองค์ประกอบ <iframe> โดยเบราว์เซอร์จะใส่ส่วนหัว Sec-Browsing-Topics ไว้ในคําขอของ iframe โดยให้ต้นทางของ iframe เป็น Caller

   <iframe src="https://adtech.example" browsingtopics></iframe>

ตีความค่าส่วนหัวของคำขอ

สําหรับทั้ง 2 วิธี (การดึงข้อมูลและ iframe) ระบบจะดึงหัวข้อที่สังเกตได้สําหรับผู้ใช้ในเซิร์ฟเวอร์จากส่วนหัวคําขอ Sec-Browsing-Topics Topics API จะรวมหัวข้อของผู้ใช้ไว้ในส่วนหัวโดยอัตโนมัติในคำขอ fetch() หรือ iframe หาก API แสดงผล Topics อย่างน้อย 1 รายการ คำขอดึงข้อมูลไปยังต้นทางที่พบ Topics จะมีส่วนหัว Sec-Browsing-Topics ดังนี้

   (325);v=chrome.1:1:1, ();p=P000000000

หาก API แสดงหัวข้อไม่พบ หัวเรื่องจะมีลักษณะดังนี้

   ();p=P0000000000000000000000000000000

ระบบจะเปลี่ยนเส้นทางตาม และหัวข้อที่ส่งในคำขอเปลี่ยนเส้นทางจะเป็นหัวข้อเฉพาะสำหรับ URL เปลี่ยนเส้นทาง ระบบจะเติมค่าส่วนหัว Sec-Browsing-Topics เพื่อลดความเสี่ยงที่ผู้โจมตีจะทราบจํานวนหัวข้อที่มีขอบเขตไปยังผู้เรียกใช้ตามความยาวส่วนหัว

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

จัดการการตอบกลับฝั่งเซิร์ฟเวอร์

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

   res.setHeader('Observe-Browsing-Topics', '?1');

หมายเหตุ: เบราว์เซอร์จะดำเนินการตามส่วนหัวการตอบกลับ Observe-Browsing-Topics เฉพาะในกรณีที่คำขอที่เกี่ยวข้องมีส่วนหัว Sec-Browsing-Topics

ส่วนหัวสําหรับ iframe และ fetch()

แชร์หัวข้อที่สังเกตได้กับคนสนิท

เนื่องจาก SSP มีสถานะอยู่ฝั่งผู้เผยแพร่โฆษณาเท่านั้น DSP จึงอาจต้องการแชร์หัวข้อที่สังเกตเห็นในเว็บไซต์ของผู้ลงโฆษณากับ SSP ที่เป็นพาร์ทเนอร์ ซึ่งทำได้โดยส่งคําขอ fetch() ที่มีส่วนหัว Topics ไปยัง SSP จากบริบทระดับบนสุดของผู้ลงโฆษณา

const response = await fetch("partner-ssp.example", {
 browsingTopics: true
});

สังเกตและเข้าถึง Topics ด้วย JavaScript

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

เราขอแนะนำให้คุณแยก JavaScript API สาธิตของ Topics ออกมาและใช้เป็นจุดเริ่มต้นสำหรับโค้ดของคุณ

ความพร้อมใช้งานของ API

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

 if ('browsingTopics' in document && document.featurePolicy.allowsFeature('browsing-topics')) {
    console.log('document.browsingTopics() is supported on this page');
 } else {
    console.log('document.browsingTopics() is not supported on this page');
 }

ข้อควรระวัง: การรองรับ Topics API ในหน้าปัจจุบันไม่ได้รับประกันว่า API ใช้งานได้เนื่องจากผู้ใช้อาจปิดใช้ API จากการตั้งค่าเบราว์เซอร์ หรืออาจมีการตั้งค่าอื่นๆ ที่ป้องกันไม่ให้ใช้ API เพื่อเป็นการปกป้องความเป็นส่วนตัวของผู้ใช้ จึงไม่มีวิธีตรวจสอบการตั้งค่าอื่นๆ เหล่านี้แบบเป็นโปรแกรม

ฝัง iframe

ต้องใช้ iframe ข้ามแหล่งที่มาสำหรับการเรียก เนื่องจากระบบจะใช้บริบทที่เรียกใช้ API เพื่อให้มั่นใจว่าเบราว์เซอร์จะแสดงหัวข้อที่เหมาะสมกับผู้เรียก ใส่องค์ประกอบ <iframe> ใน HTML

<iframe src="https://example.com" browsingtopics></iframe>

คุณยังสร้าง iframe แบบไดนามิกโดยใช้ JavaScript ได้ด้วย โดยทำดังนี้

 const iframe = document.createElement('iframe');
 iframe.setAttribute('src', 'https://adtech.example/');
 document.body.appendChild(iframe);

เรียก API จากภายใน iframe

 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() ยังทําให้เบราว์เซอร์บันทึกการเข้าชมหน้าเว็บปัจจุบันตามที่ผู้เรียกใช้เห็นด้วย เพื่อใช้ในการคำนวณหัวข้อในภายหลัง วิธีการนี้สามารถส่งอาร์กิวเมนต์ที่ไม่บังคับเพื่อข้ามการบันทึกการเข้าชมหน้าเว็บได้ {skipObservation:true}

 // current page won't be included in the calculation of topics:
 const topics = await document.browsingTopics({skipObservation:true});

ทำความเข้าใจคำตอบ

ระบบจะแสดงผลลัพธ์หัวข้อได้สูงสุด 3 หัวข้อ ได้แก่ 1 หรือ 0 สำหรับแต่ละสัปดาห์ในช่วง 3 สัปดาห์ที่ผ่านมา โดยขึ้นอยู่กับว่ามีหัวข้อที่พบหรือไม่ ระบบจะแสดงเฉพาะหัวข้อที่ผู้เรียกใช้สังเกตเห็นสําหรับผู้ใช้ปัจจุบันเท่านั้น ต่อไปนี้คือตัวอย่างผลลัพธ์ที่ API แสดง

 [{
'configVersion': chrome.2,
 'modelVersion': 4,
 'taxonomyVersion': 4,
 'topic': 309,
 'version': chrome.2:2:4
}]

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

ดูหน้าทดสอบและเผยแพร่เพื่อดูการตอบกลับที่คาดหวังและวิธีใช้ Topics เป็นสัญญาณเพิ่มเติมสําหรับโฆษณาที่เกี่ยวข้องมากขึ้น

Next steps

Test & go live

Learn how to deploy, test and scale Topics based solutions.

Tooling

Learn about the tools available in Chrome to view Topics API information, understand how topics are assigned, and debug your implementation.

See also

Check out our resources to better understand the Topics API on the Web.

• Check out Topics demos, collab and walkthrough videos.
• See the list of Chrome flags that allow developers to customize the Topics API for testing.
• See how users and developers can control the API.
• Check out the resources for technical explainers and support. Ask questions, engage and share feedback.