Protected Audience API: hướng dẫn cho nhà phát triển

Hướng dẫn dành cho nhà phát triển về phiên đấu giá quảng cáo trên thiết bị để phân phát hoạt động tái tiếp thị và đối tượng tuỳ chỉnh mà không cần theo dõi bên thứ ba trên nhiều trang web.

Đối với những người mới sử dụng Protected Audience API, hãy đọc bài viết Tổng quan về Protected Audience API để biết thông tin giải thích tổng quan về API này.

Bài đăng này được viết cho nhà phát triển dưới dạng tài liệu tham khảo kỹ thuật cho phiên bản mới nhất của Protected Audience API thử nghiệm. Chúng tôi có bản minh hoạ về cách triển khai Protected Audience API cơ bản, cũng như tài liệu tham khảo API dành cho người mua và người bán quảng cáo.

Trạng thái triển khai

Để nhận thông báo về các thay đổi về trạng thái trong API, hãy tham gia danh sách gửi thư dành cho nhà phát triển.

Protected Audience API là gì?

Protected Audience API là một API Hộp cát về quyền riêng tư được thiết kế để phân phát các trường hợp sử dụng tái tiếp thị và đối tượng tuỳ chỉnh, được thiết kế để bên thứ ba không thể sử dụng API này để theo dõi hành vi duyệt web của người dùng trên các trang web. API này cho phép trình duyệt tổ chức phiên đấu giá trên thiết bị để chọn quảng cáo phù hợp cho những trang web mà người dùng đã từng truy cập.

Protected Audience API là thử nghiệm đầu tiên được triển khai trong Chromium trong nhóm đề xuất TURTLEDOVE.

Dùng thử Protected Audience API

Tài liệu tham khảo API hiện có

Tài liệu này cung cấp thông tin tổng quan về Protected Audience API. Nếu bạn đang tìm kiếm các phương thức và tham số API cụ thể:

Bạn cũng có thể đọc các phương pháp hay nhất về độ trễ của phiên đấu giá quảng cáo Protected Audience API.

Bản minh hoạ Protected Audience API

Bạn có thể xem hướng dẫn triển khai Protected Audience API cơ bản trên các trang web của nhà quảng cáo và nhà xuất bản tại protected-audience-demo.web.app/.

Xem quy trình triển khai toàn diện này để tìm hiểu cách hoạt động của mã minh hoạ Protected Audience API và cách sử dụng Chrome DevTools để gỡ lỗi.

Kiểm thử API này

Bạn có thể thử nghiệm Protected Audience API cho một người dùng trong Chrome Beta 101.0.4951.26 trở lên trên máy tính:

Hiển thị quảng cáo trong iframe hoặc khung được phân vùng

Quảng cáo có thể được kết xuất trong <iframe> hoặc <fencedframe>, tuỳ thuộc vào cờ được đặt.

Cách sử dụng <fencedframe> để hiển thị quảng cáo:

--enable-features=InterestGroupStorage,AdInterestGroupAPI,Fledge,FencedFrames

Cách sử dụng <iframe> để hiển thị quảng cáo:

--enable-features=InterestGroupStorage,AdInterestGroupAPI,Fledge,AllowURNsInIframes --disable-features=FencedFrames

Thêm cờ BiddingAndScoringDebugReportingAPI để bật các phương thức báo cáo tạm thời về việc thắng/thua trong quá trình gỡ lỗi.

Tính năng được hỗ trợ

Protected Audience API đằng sau cờ tính năng trong Chromium là thử nghiệm đầu tiên để kiểm thử các tính năng sau của Protected Audience API:

  • Nhóm mối quan tâm: do trình duyệt lưu trữ, cùng với siêu dữ liệu liên quan để định cấu hình tính năng đặt giá thầu và hiển thị quảng cáo.
  • Đặt giá thầu trên thiết bị của bên mua (DSP hoặc nhà quảng cáo): dựa trên các nhóm mối quan tâm và tín hiệu được lưu trữ của người bán.
  • Lựa chọn quảng cáo trên thiết bị do người bán (SSP hoặc nhà xuất bản) thực hiện: dựa trên giá thầu đấu giá và siêu dữ liệu của người mua.
  • Hiển thị quảng cáo trong phiên bản tạm thời nới lỏng của Khung được phân vùng: cho phép truy cập mạng và ghi nhật ký để hiển thị quảng cáo.

Hãy đọc thêm về các tính năng hỗ trợ và quy tắc ràng buộc trong tài liệu giải thích về Protected Audience API.

Quyền đối với nhóm đối tượng có cùng mối quan tâm

Chế độ mặc định để triển khai Protected Audience API hiện tại là cho phép gọi joinAdInterestGroup() từ bất kỳ vị trí nào trong trang, ngay cả từ các iframe trên nhiều miền.

Trong tương lai, sau khi chủ sở hữu trang web có thời gian cập nhật chính sách về quyền truy cập của iframe trên nhiều miền, chúng tôi sẽ không cho phép các lệnh gọi từ iframe trên nhiều miền.

Dịch vụ khoá/giá trị

Để hỗ trợ phiên đấu giá quảng cáo Protected Audience API, trình duyệt có thể truy cập vào dịch vụ khoá/giá trị để truy xuất thông tin theo thời gian thực hỗ trợ phiên đấu giá quảng cáo Protected Audience API. Bạn có thể sử dụng thông tin này theo một số cách:

  • Người mua có thể muốn tính toán ngân sách còn lại trong một chiến dịch quảng cáo.
  • Người bán có thể phải kiểm tra mẫu quảng cáo theo chính sách của nhà xuất bản.

Mã dịch vụ khoá/giá trị Protected Audience API hiện đã có. Hãy xem bài đăng thông báo trên blog để biết thông tin cập nhật về trạng thái.

Để kiểm thử ban đầu, chúng tôi đã giới thiệu mô hình "Tự cung cấp máy chủ". Về lâu dài, các công nghệ quảng cáo sẽ cần sử dụng các dịch vụ Khoá/Giá trị API Protected Audience nguồn mở chạy trong môi trường thực thi đáng tin cậy.

Hãy tham khảo bài đăng trên blog về các dịch vụ Protected Audience API để biết thông tin cập nhật về tiến trình. Chúng tôi sẽ thông báo đầy đủ để các nhà phát triển bắt đầu thử nghiệm và sử dụng trước khi quá trình chuyển đổi này diễn ra.

Phát hiện tính năng hỗ trợ

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

'joinAdInterestGroup' in navigator &&
  document.featurePolicy.allowsFeature('join-ad-interest-group') &&
  document.featurePolicy.allowsFeature('run-ad-auction') ?
  console.log('navigator.joinAdInterestGroup() is supported on this page') :
  console.log('navigator.joinAdInterestGroup() is not supported on this page');

Protected Audience API hoạt động như thế nào?

Trong ví dụ này, người dùng duyệt qua trang web của một nhà sản xuất xe đạp tuỳ chỉnh, sau đó truy cập vào một trang web tin tức và thấy quảng cáo về một chiếc xe đạp mới của nhà sản xuất xe đạp đó.

Các tính năng của Protected Audience API sẽ được thêm dần theo thời gian khi quá trình triển khai diễn ra.

1. Người dùng truy cập vào trang web của nhà quảng cáo

Một người truy cập vào trang web của nhà sản xuất xe đạp tuỳ chỉnh trong trình duyệt trên máy tính xách tay.

Hãy tưởng tượng một người dùng truy cập vào trang web của một nhà sản xuất xe đạp tuỳ chỉnh (trong ví dụ này là nhà quảng cáo) và dành chút thời gian trên trang sản phẩm của một chiếc xe đạp bằng thép thủ công. Điều này mang đến cho nhà sản xuất xe đạp cơ hội tiếp thị lại.

2. Trình duyệt của người dùng được yêu cầu thêm một nhóm mối quan tâm

Người dùng mở một trình duyệt trên máy tính xách tay và truy cập vào một trang web. Mã JavaScript để tham gia nhóm mối quan tâm về quảng cáo đang chạy trong trình duyệt.

Nền tảng bên cầu (DSP) của nhà quảng cáo (hoặc chính nhà quảng cáo) gọi navigator.joinAdInterestGroup() để yêu cầu trình duyệt thêm một nhóm mối quan tâm vào danh sách các nhóm mà trình duyệt là thành viên.

Trong ví dụ này, nhóm có tên là custom-bikes và chủ sở hữu là dsp.example. Chủ sở hữu nhóm mối quan tâm (trong trường hợp này là DSP) sẽ là người mua trong phiên đấu giá quảng cáo Protected Audience API. Trình duyệt lưu trữ thông tin về việc người dùng tham gia nhóm mối quan tâm trên thiết bị của người dùng và không chia sẻ thông tin này với nhà cung cấp trình duyệt hoặc bất kỳ ai khác.

Chỉ định quảng cáo cho một nhóm đối tượng có cùng mối quan tâm

Đối tượng ads và adComponents bao gồm một URL cho mẫu quảng cáo và siêu dữ liệu tuỳ ý (không bắt buộc) có thể được sử dụng tại thời điểm đặt giá thầu. Ví dụ:

{
  renderUrl: 'https://cdn.example/.../bikeAd1.html',
  metadata: bikeAd1metadata // optional
}

Người mua đặt giá thầu như thế nào?

generateBid() được gọi cho mỗi nhóm mối quan tâm mà trình duyệt là thành viên nếu chủ sở hữu của nhóm mối quan tâm được mời đặt giá thầu.

Đọc tài liệu dành cho nhà phát triển về generatedBid().

3. Người dùng truy cập vào một trang web bán không gian quảng cáo

Một người truy cập vào trang web tin tức trong trình duyệt trên máy tính xách tay. Trang web có vùng quảng cáo trống.

Sau đó, người dùng truy cập vào một trang web bán không gian quảng cáo, trong ví dụ này là một trang web tin tức. Trang web có khoảng không quảng cáo được bán theo phương thức lập trình bằng tính năng đặt giá thầu theo thời gian thực.

4. Phiên đấu giá quảng cáo được chạy trong trình duyệt

Một người xem trang web tin tức trong trình duyệt trên máy tính xách tay. Phiên đấu giá quảng cáo Protected Audience API sẽ chạy để chọn một quảng cáo cho không gian quảng cáo có sẵn.

Phiên đấu giá quảng cáo có thể do nhà cung cấp bên cung cấp (SSP) của nhà xuất bản hoặc chính nhà xuất bản chạy. Mục đích của phiên đấu giá là chọn quảng cáo phù hợp nhất cho một vùng quảng cáo có sẵn trên trang hiện tại. Phiên đấu giá tính đến các nhóm mối quan tâm mà trình duyệt là thành viên, cùng với dữ liệu từ người mua không gian quảng cáo và người bán từ dịch vụ Khoá/Giá trị.

5. Người bán và người mua tham gia yêu cầu dữ liệu theo thời gian thực từ dịch vụ Khoá/Giá trị

Người dùng xem một trang web tin tức trong trình duyệt trên máy tính xách tay. Một phiên đấu giá quảng cáo bằng Protected Audience API đang diễn ra, trong đó một người tham gia nhận dữ liệu từ dịch vụ Khoá/Giá trị.

Trong một phiên đấu giá quảng cáo, người bán có thể yêu cầu dữ liệu theo thời gian thực về các mẫu quảng cáo cụ thể bằng cách gửi yêu cầu đến Dịch vụ khoá/giá trị của họ. Người bán có thể yêu cầu thông tin này trong quá trình runAdAuction() bằng thuộc tính trustedScoringSignalsUrl, cùng với các khoá từ thuộc tính renderUrl của tất cả các mục nhập trong trường ads và adComponents của tất cả các nhóm quan tâm trong phiên đấu giá.

Người mua có thể yêu cầu dữ liệu theo thời gian thực từ dịch vụ Khoá/Giá trị bằng cách sử dụng các thuộc tính trustedBiddingSignalsUrl và trustedBiddingSignalsKeys của đối số nhóm mối quan tâm được truyền đến navigator.joinAdInterestGroup().

Khi runAdAuction() được gọi, trình duyệt sẽ gửi yêu cầu đến máy chủ đáng tin cậy của từng người mua quảng cáo. URL cho yêu cầu có thể có dạng như sau:

https://kv-service.example/getvalues?hostname=publisher.example&keys=key1,key2
  • URL cơ sở đến từ trustedBiddingSignalsUrl.
  • hostname do trình duyệt cung cấp.
  • Giá trị keys được lấy từ trustedBiddingSignalsKeys.

Phản hồi cho yêu cầu này là một đối tượng JSON cung cấp giá trị cho từng khoá.

6. Quảng cáo chiến thắng sẽ xuất hiện

Một người xem trang web tin tức trong trình duyệt trên máy tính xách tay. Một quảng cáo giảm giá 20% cho một chiếc xe đạp xuất hiện trong một khung an toàn.

Lời hứa do runAdAuction() trả về sẽ phân giải thành một đối tượng cấu hình khung được bảo vệ (FencedFrameConfig) khi cờ resolveToConfig được đặt thành true trong cấu hình phiên đấu giá. Cấu hình khung được khung được bảo vệ sử dụng để điều hướng khung đến quảng cáo chiến thắng, nhưng trình nhúng khung không thấy URL của quảng cáo.

Đối tượng cấu hình khung được khoanh vùng có sẵn bắt đầu từ M114. Để biết thêm về đối tượng FencedFrameConfig, hãy xem bài viết trên blog Chrome.

7. Kết quả phiên đấu giá được báo cáo

Kế hoạch dài hạn là cho phép trình duyệt báo cáo kết quả phiên đấu giá cho người bán và người mua bằng cách sử dụng API Tổng hợp riêng tư.

Là một cơ chế báo cáo tạm thời ở cấp sự kiện, mã triển khai reportResult() cho người bán và reportWin() cho bên đặt giá thầu giành chiến thắng có thể gọi hàm sendReportTo(). Phương thức này nhận một đối số duy nhất: một chuỗi đại diện cho URL được tìm nạp sau khi phiên đấu giá kết thúc, chuỗi này sẽ mã hoá thông tin cấp sự kiện cần báo cáo.

8. Lượt nhấp vào quảng cáo được báo cáo

Một người nhấp vào quảng cáo xe đạp được lồng trong một khung có hàng rào trên một trang web tin tức. Dữ liệu báo cáo được gửi đến người bán và người mua.

Lượt nhấp vào một quảng cáo được hiển thị trong khung được phân vùng sẽ được báo cáo. Để tìm hiểu thêm về cách hoạt động của tính năng này, hãy xem bài viết Báo cáo quảng cáo Khung được phân vùng.

Tổng quan về từng giai đoạn của phiên đấu giá quảng cáo Protected Audience API
Sơ đồ này trình bày từng giai đoạn của phiên đấu giá Protected Audience API.

Protected Audience API và TURTLEDOVE có gì khác nhau?

Protected Audience API là thử nghiệm đầu tiên được triển khai trong Chromium trong nhóm đề xuất TURTLEDOVE.

Protected Audience API tuân theo các nguyên tắc cấp cao của TURTLEDOVE. Một số quảng cáo trực tuyến dựa trên việc hiển thị quảng cáo cho một người có khả năng quan tâm, người này từng tương tác với nhà quảng cáo hoặc mạng quảng cáo. Trước đây, nhà quảng cáo đã nhận dạng được một người cụ thể khi họ duyệt qua các trang web, đây là mối lo ngại chính về quyền riêng tư trên web hiện nay.

Mục tiêu của dự án TURTLEDOVE là cung cấp một API mới để giải quyết trường hợp sử dụng này, đồng thời cung cấp một số tiến bộ quan trọng về quyền riêng tư:

  • Trình duyệt, chứ không phải nhà quảng cáo, lưu trữ thông tin về những gì nhà quảng cáo cho rằng một người quan tâm.
  • Nhà quảng cáo có thể phân phát quảng cáo dựa trên mối quan tâm, nhưng không được kết hợp mối quan tâm đó với thông tin khác về một người, cụ thể là họ là ai hoặc họ đang truy cập vào trang nào.

Protected Audience API phát triển từ TURTLEDOVE và một tập hợp các đề xuất liên quan để sửa đổi nhằm phục vụ tốt hơn cho các nhà phát triển sẽ sử dụng API:

  • Trong SPARROW: Criteo đề xuất thêm mô hình dịch vụ ("Cổng kiểm soát") chạy trong môi trường thực thi đáng tin cậy (TEE). Protected Audience API có phạm vi sử dụng TEE hạn chế hơn, để tra cứu dữ liệu theo thời gian thực và báo cáo tổng hợp.
  • Đề xuất TERN của NextRoll và PARRROT của Magnite mô tả các vai trò khác nhau mà người mua và người bán có trong phiên đấu giá trên thiết bị. Quy trình đặt giá thầu/đánh giá quảng cáo của Protected Audience API dựa trên công trình này.
  • Các sửa đổi TURTLEDOVE dựa trên kết quả và ở cấp sản phẩm của RTB House đã cải thiện mô hình ẩn danh và khả năng cá nhân hoá của phiên đấu giá trên thiết bị
  • PARAKEET là đề xuất của Microsoft về một dịch vụ quảng cáo giống như TURTLEDOVE, dựa trên một máy chủ proxy chạy trong TEE giữa trình duyệt và nhà cung cấp công nghệ quảng cáo, để ẩn danh các yêu cầu quảng cáo và thực thi các thuộc tính quyền riêng tư. Protected Audience API chưa áp dụng mô hình proxy này. Chúng tôi đang điều chỉnh các API JavaScript cho PARAKEET và Protected Audience API để hỗ trợ công việc trong tương lai nhằm kết hợp thêm các tính năng tốt nhất của cả hai đề xuất.

Protected Audience API chưa ngăn mạng quảng cáo của trang web tìm hiểu xem một người nhìn thấy quảng cáo nào. Chúng tôi dự kiến sẽ sửa đổi API để trở nên riêng tư hơn theo thời gian.

Có thể sử dụng Topics API với Protected Audience API không?

Có. Chủ đề được quan sát cho người dùng hiện tại (do Topics API cung cấp) có thể được người bán hoặc bên đặt giá thầu sử dụng làm thông tin theo ngữ cảnh. Chủ đề có thể được đưa vào các thuộc tính sau:

  • auctionSignals, một thuộc tính của đối tượng cấu hình phiên đấu giá được truyền đến navigator.runAdAuction()
  • userBiddingSignals, một thuộc tính của đối tượng cấu hình nhóm mối quan tâm được truyền đến navigator.joinAdInterestGroup()

Cấu hình trình duyệt có sẵn

Người dùng có thể điều chỉnh việc tham gia thử nghiệm Hộp cát về quyền riêng tư trong Chrome bằng cách bật hoặc tắt chế độ cài đặt cấp cao nhất trong chrome://settings/adPrivacy.

Trong giai đoạn thử nghiệm ban đầu, mọi người có thể sử dụng chế độ cài đặt Hộp cát về quyền riêng tư cấp cao này để chọn không sử dụng Protected Audience API. Chrome dự định cho phép người dùng xem và quản lý danh sách các nhóm mối quan tâm mà họ đã được thêm vào trên các trang web mà họ đã truy cập. Cũng giống như các công nghệ Hộp cát về quyền riêng tư, chế độ cài đặt của người dùng có thể phát triển dựa trên ý kiến phản hồi của người dùng, cơ quan quản lý và các bên khác.

Chúng tôi sẽ tiếp tục cập nhật các chế độ cài đặt hiện có trong Chrome dựa trên thử nghiệm và ý kiến phản hồi. Trong tương lai, chúng tôi dự định cung cấp các chế độ cài đặt chi tiết hơn để quản lý Protected Audience API và dữ liệu liên quan.

Phương thức gọi API không thể truy cập vào tư cách thành viên nhóm khi người dùng duyệt web ở Chế độ ẩn danh và tư cách thành viên sẽ bị xoá khi người dùng xoá dữ liệu trang web của họ.

Trình duyệt có lưu các worklet Protected Audience vào bộ nhớ đệm không?

Các tài nguyên chứa các công việc của Protected Audience (công việc tạo giá thầu và báo cáo của người mua, cũng như công việc tính điểm và báo cáo quảng cáo của người bán) sẽ được trình duyệt lưu vào bộ nhớ đệm. Bạn có thể sử dụng tiêu đề Cache-Control để kiểm soát hành vi lưu vào bộ nhớ đệm.

Tham gia và chia sẻ ý kiến phản hồi

Yêu cầu hỗ trợ

Cách đặt câu hỏi và yêu cầu hỗ trợ triển khai, bản minh hoạ hoặc tài liệu:

Để biết thêm câu hỏi chung về việc đáp ứng nhu cầu của bạn bằng Protected Audience API, hãy gửi vấn đề trên kho lưu trữ API. Bạn cũng có thể thảo luận về các trường hợp sử dụng trong ngành trong Nhóm kinh doanh cải thiện quảng cáo trên web của W3C.

Sử dụng biểu mẫu phản hồi của Hộp cát về quyền riêng tư để chia sẻ ý kiến phản hồi riêng tư với nhóm Chrome bên ngoài các diễn đàn công khai.

Chọn không sử dụng

Bạn muốn chọn không sử dụng Protected Audience API? Tìm hiểu cách chặn quyền truy cập vào Protected Audience API khi bạn là chủ sở hữu trang web hoặc người dùng cá nhân.

Nhận thông báo cập nhật