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
- API Chủ đề đã hoàn tất giai đoạn thảo luận công khai và hiện khả dụng cho 99% người dùng, mở rộng lên tới 100%.
- Để cung cấp ý kiến phản hồi về API Chủ đề, hãy tạo một Vấn đề về Thông tin giải thích về chủ đề hoặc tham gia các cuộc thảo luận trong Nhóm kinh doanh quảng cáo trên web. Phần giải thích có một số câu hỏi mở vẫn cần được định nghĩa thêm.
- Tiến trình của Hộp cát về quyền riêng tư cung cấp tiến trình triển khai cho API Chủ đề và các đề xuất khác của Hộp cát về quyền riêng tư.
- API Chủ đề: bản cập nhật mới nhất trình bày chi tiết các thay đổi cũng như cải tiến đối với API Chủ đề và phương thức triển khai.
Xem bản minh hoạ
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 minh hoạ API JavaScript: topics-demo.glitch.me.
- Bản minh hoạ tiêu đề: topics-fetch-demo.glitch.me
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ốiconfigVersion
,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 sử dụng tiêu đề có thể hiệu quả hơn nhiều so với việc sử dụng API JavaScript, vì API này yêu cầu việc tạo một 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 cuộc gọi vì ngữ cảnh mà từ đó API được gọi được dùng để đảm bảo trình duyệt trả về chủ đề phù hợp với phương thức gọi.) Phần giải thích về Chủ đề sẽ thảo luận thêm về chủ đề: Có cách nào để gửi chủ đề bằng tính năng 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ủ đề 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ầufetch()
. 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 đươngiframe.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
.
Ả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
.
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).
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ậtnumber_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 về chủ đề là gì và cách hoạt động của chúng.
- Xem bản minh hoạ.
Tìm hiểu thêm
Thu hút và chia sẻ ý kiến phản hồi
- GitHub: Đọc tài liệu giải thích về API Chủ đề, cũng như đặt câu hỏi và theo dõi nội dung thảo luận về các vấn đề trên kho lưu trữ API.
- W3C: Thảo luận về các trường hợp sử dụng trong ngành trong bài viết Cải thiện Nhóm doanh nghiệp kinh doanh quảng cáo trên web.
- Thông báo: Tham gia hoặc xem danh sách gửi thư.
- Hỗ trợ nhà phát triển Hộp cát về quyền riêng tư: Đặt câu hỏi và tham gia thảo luận về Kho lưu trữ hỗ trợ dành cho nhà phát triển Hộp cát về quyền riêng tư.
- Chromium: Báo cáo lỗi Chromium để đặt câu hỏi về hoạt động triển khai hiện có sẵn để kiểm tra trong Chrome.