ใช้ Topics API

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

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

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

ส่วนหัว HTTP

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

เริ่มคำขอ

คุณใช้หัวข้อกับส่วนหัวได้ 2 วิธีดังนี้

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

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

   fetch('<topics_caller_eTLD+1>', { browsingTopics: true })
    .then((response) => {
        // Process the response
    });
เริ่มคำขอด้วย iframe

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

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

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

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

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

หาก API ไม่แสดงผลหัวข้อใดๆ ส่วนหัวจะมีลักษณะดังนี้

   ();p=P0000000000000000000000000000000

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

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

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

   res.setHeader('Observe-Browsing-Topics', '?1');
ส่วนหัวของคำขอและการตอบกลับสำหรับการตั้งค่าและเรียกข้อมูลหัวข้อ
ส่วนหัวสำหรับ iframe และ fetch()

แชร์หัวข้อที่สังเกตกับพาร์ทเนอร์

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

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

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

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

เราขอแนะนำให้คุณ Fork JavaScript API Demo ของ 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');
 }

ฝัง 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() วิธีการนี้ยังทำให้เบราว์เซอร์บันทึกการเข้าชมหน้าเว็บปัจจุบันตามที่ผู้เรียกสังเกตเห็น เพื่อให้สามารถใช้ในการคำนวณ Topics ในภายหลังได้ คุณส่งอาร์กิวเมนต์ที่ไม่บังคับไปยังเมธอดเพื่อข้ามการบันทึกการเข้าชมหน้าเว็บได้โดยใช้ {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': 2,
 'topic': 309,
 'version': chrome.2:2:4
}]
  • configVersion: สตริงที่ระบุเวอร์ชันการกำหนดค่าอัลกอริทึม Topics ของเบราว์เซอร์
  • modelVersion: สตริงที่ระบุตัวแยกประเภทแมชชีนเลิร์นนิงที่ใช้ในการอนุมานหัวข้อ
  • taxonomyVersion: สตริงที่ระบุชุดหัวข้อที่เบราว์เซอร์ใช้
  • topic: หมายเลขที่ระบุหัวข้อในการจัดหมวดหมู่
  • version: สตริงที่ต่อกันของ configVersion, taxonomyVersion และ modelVersion พารามิเตอร์ที่อธิบายไว้ในคู่มือนี้และรายละเอียดของ API (เช่น ขนาดอนุกรมวิธาน จำนวนหัวข้อที่คำนวณต่อสัปดาห์ และจำนวนหัวข้อที่แสดงผลต่อการเรียก) อาจมีการเปลี่ยนแปลงเมื่อเรารวมความคิดเห็นจากระบบนิเวศและทำการวนซ้ำใน API

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

Next steps

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

ดูเพิ่มเติม

ดูแหล่งข้อมูลของเราเพื่อทำความเข้าใจเกี่ยวกับ Topics API บนเว็บให้ดียิ่งขึ้น