Hướng dẫn dành cho nhà phát triển về Topics API

Tìm hiểu cách làm việc với API, bao gồm cả cách sử dụng cờ Chrome để kiểm thử.

Trạng thái triển khai

Dùng thử bản trình diễn

Có hai bản minh hoạ Topics API cho phép bạn dùng thử Chủ đề với tư cách là một người dùng duy nhất.

Bạn cũng có thể chạy colab Chủ đề để dùng thử mô hình phân loại Chủ đề.

Sử dụng API JavaScript để truy cập vào các chủ đề và ghi lại chúng dưới dạng đã quan sát

API JavaScript chủ đề có một phương thức: document.browsingTopics(). Việc này có hai mục đích:

  • Yêu cầu trình duyệt ghi lại lượt truy cập trang hiện tại đã được quan sát cho phương thức gọi, để sau đó thông tin này có thể được dùng để tính toán các chủ đề cho người dùng (cho phương thức gọi).
  • Các chủ đề truy cập của người dùng mà phương thức gọi đã quan sát.

Phương thức này trả về một lời hứa phân giải một mảng gồm tối đa 3 chủ đề, 1 chủ đề cho mỗi khoảng thời gian trong số 3 khoảng thời gian bắt đầu của hệ thống gần đây nhất, theo thứ tự ngẫu nhiên. Thời gian bắt đầu của hệ thống là một khoảng thời gian, được đặt thành một tuần trong quá trình triển khai Chrome.

Mỗi đối tượng chủ đề trong mảng do document.browsingTopics() trả về có các thuộc tính sau:

  • configVersion: một chuỗi xác định cấu hình API Chủ đề hiện tại, ví dụ: chrome.2
  • modelVersion: một chuỗi xác định thuật toán phân loại máy học dùng để suy ra các chủ đề cho trang web, ví dụ: 4
  • taxonomyVersion: một chuỗi xác định nhóm chủ đề mà trình duyệt sử dụng, ví dụ: 2
  • topic: một số xác định chủ đề trong hệ thống phân loại, ví dụ: 309
  • version: một chuỗi nối configVersion, taxonomyVersion và modelVersion, ví dụ: chrome.2:2:4

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ư kích thước 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.

Phát hiện hỗ trợ cho document.browsingTopics

Trước khi sử dụng API, hãy kiểm tra xem API này có được trình duyệt hỗ trợ và có trong tài liệu hay không:

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

Truy cập chủ đề bằng API JavaScript

Dưới đây là ví dụ cơ bản về việc có thể sử dụng API để truy cập vào các chủ đề của người dùng hiện tại.

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.
}

Truy cập vào chủ đề mà không sửa đổi trạng thái

document.browsingTopics() trả về các chủ đề mà phương thức gọi quan sát được đối với người dùng hiện tại. Theo mặc định, phương thức này 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 phương thức này khi tính toán chủ đề. Từ Chrome 108, bạn có thể truyền một đối số không bắt buộc vào phương thức này để bỏ qua việc ghi lại lượt truy cập trang: {skipObservation:true}.

Nói cách khác, {skipObservation:true} có nghĩa là lệnh gọi phương thức sẽ không khiến trang hiện tại được đưa vào quá trình tính toán chủ đề.

Sử dụng tiêu đề để truy cập vào các chủ đề và đánh dấu các chủ đề đó là đã quan sát

Bạn có thể truy cập vào các chủ đề cũng như đánh dấu các lượt truy cập trang là đã ghi nhận được, với sự trợ giúp của các tiêu đề yêu cầu và phản hồi. Việc sử dụng phương pháp tiếp cận tiêu đề có thể hiệu quả hơn nhiều so với việc gọi API JavaScript.

Bạn có thể truy cập vào các chủ đề qua tiêu đề Sec-Browsing-Topics của một yêu cầu fetch() hoặc XHR.

Việc đặt tiêu đề Observe-Browsing-Topics: ?1 trong phản hồi cho yêu cầu sẽ 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 để tính toán chủ đề.

Bạn có thể truy cập và quan sát các chủ đề bằng tiêu đề HTTP theo hai cách:

  • fetch(): Thêm {browsingTopics: true} vào tham số tuỳ chọn của một yêu cầu fetch(). Bản minh hoạ tiêu đề của Chủ đề trình bày một ví dụ đơn giản về vấn đề này.
  • Thuộc tính iframe: Thêm thuộc tính browsingtopics vào phần tử <iframe> hoặc đặt thuộc tính JavaScript tương đương iframe.browsingTopics = true. Miền có thể đăng ký của nguồn iframe là miền của phương thức gọi: ví dụ: đối với <iframe src="https://example.com" browsingtopics></iframe>: phương thức gọi là example.com.

Một số lưu ý bổ sung về tiêu đề:

  • Google sẽ theo dõi lệnh chuyển hướng và các chủ đề được gửi trong yêu cầu chuyển hướng sẽ được nêu cụ thể trong URL chuyển hướng.
  • Tiêu đề của yêu cầu sẽ không sửa đổi trạng thái cho phương thức gọi trừ phi có tiêu đề phản hồi tương ứng. Nghĩa là, nếu không có tiêu đề phản hồi, lượt truy cập trang sẽ không được ghi lại như đã quan sát, do đó sẽ không ảnh hưởng đến việc tính toán chủ đề của người dùng trong khoảng thời gian bắt đầu của hệ thống tiếp theo.
  • Tiêu đề phản hồi chỉ được chấp nhận nếu yêu cầu tương ứng có tiêu đề chủ đề.
  • URL của yêu cầu cung cấp miền có thể đăng ký được ghi lại là miền của phương thức gọi.

Gỡ lỗi triển khai API

Trang chrome://topics-internals có trong Chrome trên máy tính sau khi bạn bật Topics API. Trang này hiển thị các chủ đề cho người dùng hiện tại, chủ đề được suy luận cho tên máy chủ và thông tin kỹ thuật về việc triển khai API. Chúng tôi đang lặp lại và cải thiện thiết kế của trang dựa trên phản hồi của nhà phát triển: hãy thêm phản hồi của bạn tại bugs.chromium.org.

Xem những chủ đề được tính toán cho trình duyệt

Người dùng có thể xem thông tin về các chủ đề được ghi nhận trên trình duyệt trong khoảng thời gian bắt đầu của hệ thống hiện tại và trước đó bằng cách xem chrome://topics-internals.

Trang chrome://topics-internals, với bảng điều khiển Trạng thái chủ đề đã được chọn.
Bảng điều khiển Chủ đề Trạng thái chủ đề của trang chrome://topics-internals hiển thị mã chủ đề, chủ đề được chỉ định ngẫu nhiên và thực tế, cũng như các phiên bản phân loại và mô hình.

Ảnh chụp màn hình này cho thấy các trang web truy cập gần đây bao gồm topics-demo-cats.glitch.me và cats-cats-cats-cats.glitch.me. Điều này khiến Topics API chọn Pets và Cats làm hai trong số những chủ đề hàng đầu cho thời gian bắt đầu của hệ thống hiện tại. 3 chủ đề còn lại được chọn ngẫu nhiên do không có đủ nhật ký duyệt web (trên những trang web quan sát chủ đề) để cung cấp 5 chủ đề.

Cột Các miền theo bối cảnh được quan sát (đã băm) cung cấp giá trị đã băm của tên máy chủ mà một chủ đề được quan sát.

Xem chủ đề được suy luận cho tên máy chủ

Bạn cũng có thể xem các chủ đề do mô hình phân loại Chủ đề suy ra cho một hoặc nhiều tên máy chủ trong chrome://topics-internals.

Trang chrome://topics-internals, trong đó có bảng điều khiển Classifier (Trình phân loại) đã được chọn.
Bảng điều khiển Classifier của trang chrome://topics-internals hiển thị các chủ đề được chọn, máy chủ đã truy cập, phiên bản và đường dẫn của mô hình.

Cách triển khai Topics API hiện tại chỉ dự đoán chủ đề từ tên máy chủ chứ không qua bất kỳ phần nào khác của URL.

Chỉ sử dụng tên máy chủ (không có giao thức hoặc đường dẫn) để xem các chủ đề suy luận từ Trình phân loại chrome://topics-internals. chrome://topics-internals sẽ hiển thị lỗi nếu bạn cố gắng thêm "/" vào trường Máy chủ lưu trữ.

Xem thông tin về Topics API

Bạn có thể tìm thấy thông tin về cách triển khai và cài đặt Topics API, chẳng hạn như phiên bản hệ thống phân loại và khoảng thời gian bắt đầu của hệ thống trong chrome://topics-internals. Các giá trị này phản ánh chế độ cài đặt mặc định cho API hoặc các tham số được thiết lập thành công từ dòng lệnh. Việc này có thể hữu ích khi xác nhận rằng các cờ dòng lệnh đã hoạt động như mong đợi.

Trong ví dụ này, time_period_per_epoch được đặt thành 15 giây (mặc định là 7 ngày).

trang chrome://topics-internals với bảng điều khiển Tính năng và Thông số đã được chọn.
Bảng điều khiển chrome://topics-internals Tính năng và thông số cho thấy các tính năng đã bật, thời gian theo mỗi thời gian bắt đầu của hệ thống, số khoảng thời gian bắt đầu của hệ thống được dùng để tính toán chủ đề, phiên bản phân loại và các chế độ cài đặt khác.

Các tham số hiển thị trong ảnh chụp màn hình tương ứng với cờ có thể đặt khi chạy Chrome qua dòng lệnh. Ví dụ: bản minh hoạ tại topics-fetch-demo.glitch.me bạn nên sử dụng các cờ sau:

--enable-features=BrowsingTopics,BrowsingTopicsParameters:time_period_per_epoch/15s/max_epoch_introduction_delay/3s,PrivacySandboxAdsAPIsOverride,PrivacySandboxSettings3,OverridePrivacySandboxSettingsLocalTesting

Danh sách sau đây giải thích từng thông số, giá trị mặc định và mục đích của từng thông số.

Cờ Chrome

BrowsingTopics
Giá trị mặc định: được bật
Liệu API Chủ đề có được bật hay không.

PrivacySandboxAdsAPIsOverride
Giá trị mặc định: được bật
Bật các API quảng cáo: Báo cáo phân bổ, Đối tượng được bảo vệ, Chủ đề, Khung bảo vệ.

PrivacySandboxSettings4
Giá trị mặc định: bị tắt
Bật bản phát hành thứ tư của chế độ cài đặt giao diện người dùng cho Hộp cát về quyền riêng tư.

OverridePrivacySandboxSettingsLocalTesting
Giá trị mặc định: được bật
Nếu được bật, trình duyệt sẽ không yêu cầu bật các chế độ cài đặt cơ bản để bật các tính năng của Hộp cát về quyền riêng tư nữa.

BrowsingTopicsBypassIPIsPubliclyRoutableCheck
Giá trị mặc định: tắt
Nếu bạn bật chính sách này, thì hoạt động kiểm tra xem địa chỉ IP có thể định tuyến công khai hay không sẽ bị bỏ qua khi xác định điều kiện của một trang để đưa vào tính toán chủ đề.

BrowsingTopics:number_of_epochs_to_expose
Giá trị mặc định: 3
Số khoảng thời gian bắt đầu của hệ thống từ nơi tính toán chủ đề để cung cấp cho ngữ cảnh yêu cầu. Trình duyệt sẽ tuân theo thời gian bắt đầu của hệ thống N+1.

BrowsingTopics:time_period_per_epoch
Giá trị mặc định: 7d-0h-0m-0s
Thời lượng của mỗi khoảng thời gian bắt đầu của hệ thống. Để gỡ lỗi, bạn nên đặt thời lượng này là (giả sử) 15 giây, thay vì 7 ngày theo mặc định.

BrowsingTopics:number_of_top_topics_per_epoch
Giá trị mặc định: 5
Số chủ đề được tính theo thời gian bắt đầu của hệ thống.

BrowsingTopics:use_random_topic_probability_percent
Giá trị mặc định: 5
Xác suất một chủ đề riêng lẻ trong thời gian bắt đầu của hệ thống được trả về ngẫu nhiên từ toàn bộ hệ thống phân loại của chủ đề. Tính ngẫu nhiên cố định với một thời gian bắt đầu của hệ thống và trang web.

BrowsingTopics:number_of_epochs_of_observation_data_to_use_for_filtering
Giá trị mặc định: 3
Số lượng khoảng thời gian bắt đầu của dữ liệu sử dụng API (tức là số lượt quan sát chủ đề) sẽ được dùng để lọc chủ đề cho ngữ cảnh gọi.

BrowsingTopics:max_number_of_api_usage_context_domains_to_keep_per_topic
Giá trị mặc định: 1000
Số miền tối đa được quan sát theo bối cảnh cần giữ lại cho mỗi chủ đề hàng đầu. Mục đích là giới hạn bộ nhớ đang sử dụng.

BrowsingTopics:max_number_of_api_usage_context_entries_to_load_per_epoch
Giá trị mặc định: 100000
Số mục tối đa được phép truy xuất từ cơ sở dữ liệu đối với mỗi truy vấn đối với các ngữ cảnh sử dụng API. Truy vấn sẽ xảy ra một lần cho mỗi thời gian bắt đầu của hệ thống tại thời điểm tính toán chủ đề. Mục đích là để giới hạn mức sử dụng bộ nhớ cao nhất.

BrowsingTopics:max_number_of_api_usage_context_domains_to_store_per_page_load
Giá trị mặc định: 30
Số lượng miền theo bối cảnh sử dụng API tối đa được phép lưu trữ trong mỗi lượt tải trang.

BrowsingTopics:config_version
Giá trị mặc định: 1
Mã hoá các tham số cấu hình Topics API. Bạn chỉ nên liên kết mỗi số phiên bản với một tập hợp cấu hình. Thường thì bạn nên cập nhật các tham số cấu hình mà không cập nhật config_version để kiểm thử cục bộ, nhưng trong một số trường hợp, trình duyệt có trạng thái không nhất quán và có thể gây ra sự cố trình duyệt, chẳng hạn như cập nhật number_of_top_topics_per_epoch.

BrowsingTopics:taxonomy_version
Giá trị mặc định: 1
Phiên bản hệ thống phân loại mà API sử dụng.

Chọn không sử dụng trang web của bạn

Bạn có thể chọn không tính chủ đề cho các trang cụ thể trên trang web của mình bằng cách thêm tiêu đề Permissions-Policy: browsing-topics=() Permissions-Policy vào một trang để chỉ tính toán chủ đề cho tất cả người dùng trên trang đó. Các lượt truy cập sau đó vào các trang khác trên trang web của bạn sẽ không bị ảnh hưởng: nếu bạn đặt chính sách chặn Topics API trên một trang, thì việc này sẽ không ảnh hưởng đến các trang khác.

Bạn cũng có thể kiểm soát những bên thứ ba có quyền truy cập vào các chủ đề trên trang của bạn bằng cách sử dụng tiêu đề Permissions-Policy để kiểm soát quyền truy cập của bên thứ ba vào Topics API. Làm tham số cho tiêu đề, sử dụng self và bất kỳ miền nào mà bạn muốn cho phép truy cập vào API. Ví dụ: để tắt hoàn toàn việc sử dụng Topics API trong tất cả các ngữ cảnh duyệt web ngoại trừ nguồn gốc và https://example.com của riêng bạn, hãy đặt tiêu đề phản hồi HTTP sau đây:

Permissions-Policy: browsing-topics=(self "https://example.com")

Các bước tiếp theo

Tìm hiểu thêm

Thu hút và chia sẻ ý kiến phản hồi