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 quảng cáo 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 Tổng quan về Protected Audience API để biết giải thích chung về API này.

Bài đăng này được viết cho các nhà phát triển dưới dạng tài liệu tham khảo kỹ thuật cho lần lặp lại gần đây nhất của Protected Audience API thử nghiệm. Có một bản minh hoạ về việc triển khai Protected Audience API cơ bản, cũng như các tài liệu tham khảo API 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ế sao cho các 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 cá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 đóng vai trò là 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 để giảm độ trễ trong 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 về việc 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 từ đầu đến cuối 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:

  • Bật tất cả các API Quyền riêng tư trong quảng cáo trong chrome://settings/adPrivacy.
  • Đặt cờ từ dòng lệnh. Bạn có thể xem danh sách đầy đủ các cờ Protected Audience API có sẵn trong Chromium Code Search.

Hiển thị quảng cáo trong iframe hoặc khung bảo vệ

Quảng cáo có thể được hiển thị trong <iframe> hoặc <fencedframe>, tuỳ thuộc vào cờ nào đượ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ề lượt thua/thắng gỡ lỗi.

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

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

  • Nhóm đối tượng có cùng mối quan tâm: được trình duyệt lưu trữ, có siêu dữ liệu liên kết để định cấu hình việc đặt giá thầu và hiển thị quảng cáo.
  • Hoạt động đặt giá thầu trên thiết bị của người mua (DSP hoặc nhà quảng cáo): dựa trên các nhóm lợi ích và tín hiệu đã lưu trữ từ người bán.
  • Lựa chọn quảng cáo trên thiết bị của người bán (SSP hoặc nhà xuất bản): dựa trên giá thầu và siêu dữ liệu trong phiên đấu giá 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 bảo vệ: cho phép truy cập vào mạng và ghi nhật ký để hiển thị quảng cáo.

Đọc thêm về các hạn chế và khả năng hỗ trợ tính năng 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

Theo mặc định, việc triển khai Protected Audience API hiện tại là cho phép gọi joinAdInterestGroup() từ mọi nơi trên một trang, ngay cả từ iframe 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 iframe trên nhiều miền, chúng tôi dự định 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 một 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. Thông tin này có thể được dùng theo nhiều 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 dựa trên chính sách của nhà xuất bản.

Mã dịch vụ khoá/giá trị Protected Audience API hiện đã có sẵn. Hãy xem bài đăng trên blog thông báo để 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 "Sử dụng máy chủ riêng". 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ị Protected Audience API nguồn mở chạy trong các 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 trước cho các nhà phát triển để họ bắt đầu thử nghiệm và áp dụng trước khi quá trình chuyển đổi này diễn ra.

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

Trước khi sử dụng API, hãy kiểm tra xem trình duyệt có hỗ trợ API này hay không và API này 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, một người dùng duyệt xem 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 bổ sung theo thời gian khi quá trình triển khai tiến triển.

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 rằ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 (nhà quảng cáo trong ví dụ này) và dành thời gian trên trang sản phẩm cho 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 đối tượng có cùng 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 các nhóm đối tượng có cùng 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 đối tượng có cùng 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 sẽ lưu trữ thông tin về việc tham gia nhóm đối tượng có cùng mối quan tâm trên thiết bị của người dùng và không chia sẻ 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

Các đối tượng ads và adComponents bao gồm một URL cho mẫu quảng cáo và (không bắt buộc) siêu dữ liệu tuỳ ý có thể 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 bằng cách nào?

generateBid() được gọi cho mỗi nhóm đối tượng có cùng 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 đối tượng có cùng mối quan tâm được mời đặt giá thầu.

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

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 một trang web tin tức trong trình duyệt trên máy tính xách tay. Trang web có một 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 này có khoảng không quảng cáo và bán khoảng không quảng cáo đó 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 diễn ra 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 được 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 bán (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á có tính đến các nhóm lợi ích mà trình duyệt là thành viên, cùng với dữ liệu từ người mua khoảng không 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. Phiên đấu giá quảng cáo sử dụ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 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 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 trong trường ads và adComponents của tất cả các nhóm mối 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ị của họ 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ở lấy 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 các 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 xe đạp xuất hiện trong một khung có hàng rào bảo mật.

Lệnh 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 phân vùng sử dụng để điều hướng khung đến quảng cáo thắng thầu, nhưng URL của quảng cáo không hiển thị cho trình nhúng khung.

Đối tượng cấu hình khung được phân vùng có sẵn từ M114. Để biết thêm thông tin 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ả của phiên đấu giá cho người bán và người mua bằng cách sử dụng Private Aggregation API.

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 người đặt giá thầu giành chiến thắng có thể gọi hàm sendReportTo(). Phương thức này sử dụng một đối số duy nhất: một chuỗi đại diện cho một URL được tìm nạp sau khi phiên đấu giá hoàn tất, mã hoá thông tin cấp sự kiện sẽ được 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 về xe đạp (được nhúng bằng khung có rào chắn) trên một trang web tin tức. Dữ liệu báo cáo được gửi cho 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 trong khung được phân vùng.

Thông tin 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 mô tả từng giai đoạn của phiên đấu giá Protected Audience API.

Protected Audience API khác gì với TURTLEDOVE?

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ó thể quan tâm đã từng tương tác với nhà quảng cáo hoặc mạng quảng cáo. Trước đây, điều này hoạt động bằng cách nhà quảng cáo nhận dạng 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ư đối với web ngày nay.

Nỗ lực 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 mang đến 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 giữ thông tin về những gì mà 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ột mối quan tâm, nhưng không thể kết hợp mối quan tâm đó với thông tin khác về một người, đặc biệt là họ là ai hoặc họ đang truy cập vào trang nào.

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

  • Trong SPARROW: Criteo đề xuất bổ sung một mô hình dịch vụ ("Gatekeeper") 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 của người mua và người bán trong phiên đấu giá trên thiết bị. Quy trình đặt giá thầu/chấm điểm quảng cáo của Protected Audience API dựa trên hoạt động này.
  • Các điểm sửa đổi dựa trên kết quả và cấp sản phẩm của TURTLEDOVE 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 tương tự 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 về quyền riêng tư. Protected Audience API chưa áp dụng mô hình uỷ quyền 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 hiện chưa ngăn được mạng quảng cáo của một trang web tìm hiểu xem một người dùng 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.

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

Có. Người bán hoặc bên đặt giá thầu có thể sử dụng một chủ đề được quan sát cho người dùng hiện tại (do Topics API cung cấp) làm thông tin theo bối cảnh. Một 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 mức độ tham gia vào các quy trình dùng thử 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, người dùng 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. Giống như chí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à những người 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 kết quả 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 kết.

Các đối tượng gọi API không thể truy cập vào tư cách thành viên của 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 Protected Audience worklet vào bộ nhớ đệm không?

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

Tương tác và chia sẻ ý kiến phản hồi

Yêu cầu hỗ trợ

Để đặt câu hỏi và được hỗ trợ về việc triển khai, bản minh hoạ hoặc tài liệu, hãy làm như sau:

Đối với các câu hỏi chung hơn 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 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 với tư cách 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