ใช้ 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 เป็นสัญญาณเพิ่มเติมเพื่อให้โฆษณาเกี่ยวข้องมากขึ้น

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

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

ดูเพิ่มเติม

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