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

Xem bản minh hoạ

Có 2 bản minh hoạ Topics API cho phép bạn dùng thử Topics API với tư cách một người dùng.

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

Topics JavaScript API 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 ghi nhận cho phương thức gọi, để sau này có thể sử dụng dữ liệu này để tính toán chủ đề cho người dùng (đối với phương thức gọi).
  • Truy cập vào các chủ đề của người dùng mà phương thức gọi đã quan sát thấy.

Phương thức này trả về một hứa hẹn phân giải thành một mảng gồm tối đa 3 chủ đề, một 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à 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ề đều có các thuộc tính sau:

  • configVersion: một chuỗi xác định cấu hình Topics API hiện tại, ví dụ: chrome.2
  • modelVersion: một chuỗi xác định thuật toán phân loại của công nghệ học máy dùng để suy ra các chủ đề cho trang web, chẳng hạn như 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ư quy mô 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 phản hồi về hệ sinh thái và lặp lại API này.

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

Trước khi sử dụng API, hãy kiểm tra xem API đó có được trình duyệt hỗ trợ và có xuất hiện 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 vào các chủ đề bằng API JavaScript

Dưới đây là một ví dụ cơ bản về cách sử dụng API để truy cập vào các chủ đề cho 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 các chủ đề mà không cần 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 cho 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 như được người gọi quan sát, do đó, sau này có thể sử dụng phương thức này khi tính toán chủ đề. Từ Chrome 108, 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}.

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

Dùng tiêu đề để truy cập vào các chủ đề và đánh dấu là đã quan sát được

Bạn có thể truy cập vào các chủ đề cũng như đánh dấu số lượt truy cập trang là đã quan sát được với sự trợ giúp của yêu cầu và tiêu đề phản hồi.

Phương pháp sử dụng tiêu đề có thể hiệu quả hơn nhiều so với sử dụng API JavaScript, vì API yêu cầu tạo iframe trên nhiều nguồn gốc và thực hiện lệnh gọi document.browsingTopics() từ đó. (Bạn phải sử dụng iframe trên nhiều nguồn gốc cho lệnh gọi vì ngữ cảnh mà API được gọi ra sẽ được dùng để đảm bảo trình duyệt sẽ trả về những chủ đề phù hợp với phương thức gọi.) Nội dung giải thích về Chủ đề sẽ thảo luận thêm: Có cách nào để gửi chủ đề thông qua Tìm nạp làm tiêu đề yêu cầu không? .

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

Đặt tiêu đề Observe-Browsing-Topics: ?1 vào phản hồi cho yêu cầu làm cho trình duyệt ghi lại lượt truy cập trang hiện tại như được người gọi quan sát, để sau này có thể dùng trong tính toán chủ đề.

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

  • fetch(): Thêm {browsingTopics: true} vào tham số tuỳ chọn của yêu cầu fetch(). Bản minh hoạ tiêu đề của Chủ đề là một ví dụ đơn giản cho 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 JavaScript tương đương thuộc tính 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 đề:

  • URL chuyển hướng sẽ được chuyển hướng, và chủ đề được gửi trong yêu cầu chuyển hướng sẽ dành riêng cho URL chuyển hướng.
  • Tiêu đề 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. Tức 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 là đã ghi nhận, do đó, không ảnh hưởng đến tính toán chủ đề của người dùng cho thời gian bắt đầu tiếp theo của hệ thống.
  • 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ý và miền này đượ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 sẽ 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, các chủ đề được dự đoá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 chủ đề được tính toán cho trình duyệt của bạn

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

Trang chrome://topics-internals có bảng điều khiển Trạng thái chủ đề được chọn.
Bảng điều khiển Trạng thái chủ đề trên trang chrome://topics-internals cho thấy mã chủ đề, các lượt chỉ định chủ đề thực và ngẫu nhiên, cũng như phiên bản hệ thống 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ố các chủ đề hàng đầu cho thời gian bắt đầu của hệ thống hiện tại. Ba chủ đề còn lại đã được chọn ngẫu nhiên, vì không có đủ nhật ký duyệt web (trên các trang web quan sát chủ đề) để cung cấp 5 chủ đề.

Cột Miền ngữ 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 các chủ đề được dự đoá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 luận cho một hoặc nhiều tên máy chủ trong chrome://topics-internals.

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

Việc triển khai Topics API hiện tại chỉ dự đoán chủ đề từ tên máy chủ; chứ không phải từ 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ủ đề được 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ố thêm "/" trong 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à chế độ 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 trên 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 đặt thành công từ dòng lệnh. Điều này có thể hữu ích khi xác nhận rằng 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 Tính năng và Thông số được chọn.
Bảng Tính năng và thông số chrome://topics-internals hiển thị các tính năng đã bật, thời gian mỗi khoảng thời gian bắt đầu của hệ thống, số lượng khoảng thời gian bắt đầu của hệ thống để 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 cờ có thể đặt khi chạy Chrome từ dòng lệnh. Ví dụ: bản minh hoạ tại topics-fetch-demo.glitch.me đề xuất 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 thông số đó.

Cờ Chrome

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

PrivacySandboxAdsAPIsOverride
Giá trị mặc định: bật
Bật các API quảng cáo: Attribution Reporting (Báo cáo phân bổ), Protected Audience (Đối tượng được bảo vệ), Topics (Chủ đề), Topics phạm vi bảo vệ.

PrivacySandboxSettings4
Giá trị mặc định: đã 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: bật
Nếu được bật, trình duyệt sẽ không còn yêu cầu bật các tùy chọn cài đặt cơ bản bật các tính năng Hộp cát về quyền riêng tư.

BrowsingTopicsBypassIPIsPubliclyRoutableCheck
Giá trị mặc định: đã tắt
Nếu được bật, thao tác 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 tính đủ điều kiện để một trang được đưa vào chủ đề phép tính.

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ính toán chủ đề cho yêu cầu ngữ cảnh. Trình duyệt sẽ lưu giữ nội bộ tối đa 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, có thể hữu ích khi đặt thời lượng này thành 15 giây (giả sử) thay vì 7 ngày mặc định.

BrowsingTopics:number_of_top_topics_per_epoch
Giá trị mặc định: 5
Số lượng chủ đề được tính trong mỗi khoảng 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 một 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 chủ đề. Sự ngẫu nhiên sẽ gắn liền với một thời gian bắt đầu của hệ thống và một 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à quan sát chủ đề) sẽ được dùng cho lọc các chủ đề để có ngữ cảnh gọi điện.

BrowsingTopics:max_number_of_api_usage_context_domains_to_keep_per_topic
Giá trị mặc định: 1000
Số lượng miền tối đa mà theo bối cảnh quan sát được cần giữ lại cho mỗi chủ đề hàng đầu. Ý định 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ố lượng 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 cho 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 khi tính toán chủ đề bất cứ lúc nào. 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 ngữ cảnh sử dụng API tối đa được phép lưu trữ cho 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. Mỗi số phiên bản chỉ được được ánh xạ tới một tập cấu hình. Bạn phải cập nhật các thông số cấu hình mà không cập nhật config_version thường tốt khi thử nghiệm cục bộ, nhưng trong một số trường hợp có thể khiến trình duyệt ở trạng thái không nhất quán và có thể dẫn đến sự cố trình duyệt, ví dụ: việc cập nhật number_of_top_topics_per_epoch.

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

Chọn không tham gia trang web của bạn

Bạn có thể chọn không tính toán 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 trên một trang để không cho phép tính toán chủ đề cho tất cả người dùng chỉ trên trang đó. Các lượt truy cập sau này 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ì các trang khác sẽ không bị ảnh hưởng.

Bạn cũng có thể kiểm soát những bên thứ ba nào 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 bạn muốn cho phép truy cập vào API. Ví dụ: để tắt hoàn toàn tính năng sử dụng Topics API trong tất cả ngữ cảnh duyệt web, ngoại trừ nguồn gốc của bạn và https://example.com, 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