Triển khai Topics API

Trang này giải thích thông tin chi tiết về việc triển khai để các phương thức gọi Topics API quan sát và truy cập vào các chủ đề. Trước khi bắt đầu triển khai giải pháp, hãy đảm bảo rằng trình duyệt của bạn đã được thiết lập đúng cách. Hãy xem phần tổng quan để tìm hiểu thêm về cách các phương thức gọi quan sát và truy cập vào các chủ đề của người dùng.

Quan sát và truy cập vào Topics

Có hai cách để quan sát và truy cập vào các chủ đề của người dùng: tiêu đề HTTP và JavaScript API.

Tiêu đề HTTP

Bạn nên sử dụng tiêu đề HTTP để quan sát và truy cập vào các chủ đề của người dùng. Phương pháp này có thể hiệu quả hơn nhiều so với việc sử dụng JavaScript API. Với tiêu đề HTTP, URL của yêu cầu cung cấp miền có thể đăng ký được ghi lại dưới dạng miền của phương thức gọi. Đây là miền được cho là đã quan sát thấy các chủ đề của người dùng.

Bắt đầu yêu cầu

Có 2 cách sử dụng Chủ đề có tiêu đề:

  • Bằng cách truy cập vào tiêu đề yêu cầu và phản hồi trên một yêu cầu fetch() có lựa chọn browsingTopics: true.
  • Bằng cách truy cập vào tiêu đề cho một phần tử iframe có thuộc tính browsingtopics.
Bắt đầu yêu cầu bằng một lệnh tìm nạp

Khi sử dụng lệnh tìm nạp, phương thức gọi API sẽ đưa ra một yêu cầu bao gồm {browsingTopics: true} trong tham số options. Nguồn gốc của tham số URL trong yêu cầu tìm nạp là nguồn gốc được xem là đã quan sát thấy các chủ đề.

   fetch('<topics_caller_eTLD+1>', { browsingTopics: true })
    .then((response) => {
        // Process the response
    });
Khởi tạo yêu cầu bằng iframe

Thêm thuộc tính browsingtopics vào phần tử <iframe>. Trình duyệt sẽ thêm tiêu đề Sec-Browsing-Topics vào yêu cầu của iframe, với nguồn gốc của iframe là phương thức gọi.

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

Diễn giải các giá trị tiêu đề của yêu cầu

Đối với cả hai phương pháp (tìm nạp và iframe), các chủ đề được quan sát cho một người dùng có thể được truy xuất trên máy chủ từ tiêu đề yêu cầu Sec-Browsing-Topics. Topics API sẽ tự động thêm các chủ đề của người dùng vào tiêu đề trên yêu cầu fetch() hoặc iframe. Nếu API trả về một hoặc nhiều chủ đề, thì yêu cầu tìm nạp đến nguồn mà từ đó các chủ đề được quan sát sẽ bao gồm một tiêu đề Sec-Browsing-Topics như sau:

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

Nếu API không trả về chủ đề nào, tiêu đề sẽ có dạng như sau:

   ();p=P0000000000000000000000000000000

Các lệnh chuyển hướng sẽ được tuân theo và các chủ đề được gửi trong yêu cầu chuyển hướng sẽ dành riêng cho URL chuyển hướng. Các giá trị tiêu đề Sec-Browsing-Topics được thêm khoảng đệm để giảm thiểu nguy cơ kẻ tấn công biết được số lượng chủ đề được giới hạn cho một phương thức gọi dựa trên độ dài tiêu đề.

Xử lý phản hồi phía máy chủ

Nếu phản hồi cho yêu cầu bao gồm tiêu đề Observe-Browsing-Topics: ?1, thì điều này báo hiệu rằng trình duyệt nên đánh dấu các chủ đề trong yêu cầu đi kèm là đã được quan sát và đưa lượt truy cập trang hiện tại vào tính toán chủ đề theo giai đoạn tiếp theo của người dùng. Thêm tiêu đề Observe-Browsing-Topics: ?1 vào phản hồi trong mã phía máy chủ:

   res.setHeader('Observe-Browsing-Topics', '?1');
Tiêu đề Yêu cầu và Phản hồi để đặt và truy xuất các chủ đề.
Tiêu đề cho iframe và fetch().

Chia sẻ chủ đề đã quan sát được với đối tác

Vì SSP chỉ xuất hiện ở phía nhà xuất bản, nên DSP có thể muốn chia sẻ các chủ đề mà họ quan sát được trên trang web của nhà quảng cáo với các SSP đối tác. Họ có thể làm như vậy bằng cách đưa ra yêu cầu fetch() có tiêu đề về chủ đề cho SSP từ bối cảnh cấp cao nhất của nhà quảng cáo.

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

Quan sát và truy cập vào Các chủ đề bằng JavaScript

Phương thức Topics JavaScript API document.browsingTopics() cung cấp một cách để vừa quan sát vừa truy xuất các chủ đề mà người dùng quan tâm trong môi trường trình duyệt: – Ghi lại hoạt động quan sát: Thông báo cho trình duyệt rằng phương thức gọi đã quan sát thấy người dùng truy cập vào trang hiện tại. Thông tin quan sát này góp phần vào việc tính toán chủ đề của người dùng cho phương thức gọi trong các khoảng thời gian bắt đầu tiếp theo của hệ thống. – Access Topics:Truy xuất các chủ đề mà phương thức gọi đã quan sát được trước đó cho người dùng. Phương thức này trả về một mảng gồm tối đa 3 đối tượng chủ đề, mỗi đối tượng cho một trong những khoảng thời gian bắt đầu gần đây nhất, theo thứ tự ngẫu nhiên.

Bạn nên phân nhánh bản minh hoạ Topics API bằng JavaScript và sử dụng bản minh hoạ này làm điểm bắt đầu cho mã của mình.

Khả năng sử dụng của API

Trước khi sử dụng API này, hãy đảm bảo rằng API được hỗ trợ và có sẵn:

 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');
 }

Nhúng iframe

Bạn phải dùng iframe trên nhiều nguồn gốc cho lệnh gọi này, vì ngữ cảnh mà API được gọi sẽ được dùng để đảm bảo trình duyệt trả về các chủ đề phù hợp với phương thức gọi. Thêm phần tử <iframe> vào HTML:

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

Bạn cũng có thể tạo iframe một cách linh hoạt bằng JavaScript:

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

Gọi API từ bên trong 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.
 }

Theo mặc định, phương thức document.browsingTopics() cũng khiến trình duyệt ghi lại lượt truy cập trang hiện tại mà phương thức gọi quan sát được, để sau này có thể dùng trong quá trình tính toán chủ đề. Phương thức này có thể được truyền một đối số không bắt buộc để bỏ qua việc ghi lại lượt truy cập trang: {skipObservation:true}.

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

Hiểu rõ câu trả lời

Hệ thống sẽ trả về tối đa 3 chủ đề: một hoặc không có chủ đề nào cho mỗi tuần trong 3 tuần gần nhất, tuỳ thuộc vào việc có chủ đề nào được quan sát hay không. Chỉ những chủ đề mà phương thức gọi quan sát thấy đối với người dùng hiện tại mới được trả về. Sau đây là ví dụ về nội dung mà API trả về:

 [{
'configVersion': chrome.2,
 'modelVersion': 4,
 'taxonomyVersion': 2,
 'topic': 309,
 'version': chrome.2:2:4
}]
  • configVersion: một chuỗi xác định phiên bản cấu hình thuật toán chủ đề của trình duyệt.
  • modelVersion: một chuỗi xác định thuật toán phân loại học máy được dùng để suy luận các chủ đề.
  • taxonomyVersion: một chuỗi xác định nhóm chủ đề mà trình duyệt đang sử dụng.
  • topic: một số nhận dạng chủ đề trong hệ thống phân loại.
  • version: một chuỗi nối configVersion, taxonomyVersion và modelVersion. Các tham số được mô tả trong hướng dẫn này và thông tin chi tiết về API (chẳng hạn như quy mô hệ thống phân loại, số lượng chủ đề được tính toán mỗi tuần và số lượng chủ đề được trả về cho mỗi lệnh gọi) có thể thay đổi khi chúng tôi kết hợp ý kiến phản hồi của hệ sinh thái và lặp lại trên API.

Hãy xem trang Thử nghiệm và phát hành để tìm hiểu phản hồi dự kiến và cách sử dụng Chủ đề làm tín hiệu bổ sung cho quảng cáo phù hợp hơn.

Các bước tiếp theo

Tìm hiểu cách triển khai, kiểm thử và mở rộng quy mô các giải pháp dựa trên Chủ đề.
Tìm hiểu về các công cụ có sẵn trong Chrome để xem thông tin về Topics API, hiểu cách chỉ định chủ đề và gỡ lỗi quá trình triển khai.

Xem thêm

Hãy xem các tài nguyên của chúng tôi để hiểu rõ hơn về Topics API trên web.