Trang này được dịch bởi Cloud Translation API.

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

Bài viết này dành cho đối tượng nào?

Bài đăng này là tài liệu tham khảo kỹ thuật đến phiên bản hiện tại của Protected Audience API thử nghiệm.

Protected Audience API là thông tin tổng quan ít mang tính kỹ thuật hơn về đề xuất này, và cũng có một bảng thuật ngữ.
Bản minh hoạ về Protected Audience cung cấp hướng dẫn từng bước về FLEDGE cơ bản triển khai.
Video minh hoạ về Protected Audience giải thích cách hoạt động của mã minh hoạ và cho biết cách sử dụng Công cụ của Chrome cho nhà phát triển để gỡ lỗi Protected Audience.

Protected Audience là gì?

Protected Audience API là một đề xuất Hộp cát về quyền riêng tư để 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ế để không ai có thể sử dụng bên thứ ba để theo dõi hành vi duyệt web của người dùng trên các trang web. API này bật phiên đấu giá trên thiết bị bằng cách trình duyệt, để chọn quảng cáo có liên quan cho trang web mà người dùng đã truy cập trước đó.

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

Sơ đồ dưới đây cung cấp thông tin tổng quan về vòng đời của FLEDGE:

Hình minh hoạ cung cấp thông tin tổng quan về từng giai đoạn trong vòng đời FLEDGE — Vòng đời FLEDGE.

Làm cách nào để dùng thử Protected Audience?

Bản minh hoạ Protected Audience

Bạn có thể xem hướng dẫn từng bước về cách triển khai Protected Audience 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.

Video minh hoạ giải thích cách hoạt động của mã minh hoạ và cho biết cách sử dụng Công cụ của Chrome cho nhà phát triển để gỡ lỗi Protected Audience.

Tham gia bản dùng thử theo nguyên gốc Protected Audience

Bản dùng thử theo nguyên gốc về Mức độ liên quan và hoạt động đo lường của Hộp cát về quyền riêng tư đã có sẵn trong Chrome Beta 101.0.4951.26 trở lên trên máy tính cho Protected Audience, Chủ đề và API Attribution Reporting.

Để tham gia, hãy đăng ký mã thông báo dùng thử theo nguyên gốc.

Sau khi đăng ký dùng thử thành công, bạn có thể dùng thử Protected Audience JavaScript API trên các trang cung cấp mã dùng thử hợp lệ (ví dụ: để yêu cầu trình duyệt tham gia vào một hoặc nhiều nhóm mối quan tâm), rồi chạy phiên đấu giá quảng cáo để chọn và hiển thị quảng cáo.

Bản minh hoạ về Protected Audience cung cấp một ví dụ cơ bản về cách triển khai Protected Audience toàn diện.

Cung cấp mã dùng thử cho mỗi trang mà bạn muốn chạy mã Protected Audience API:

Dưới dạng thẻ meta trong <head>:

<meta http-equiv="origin-trial" content="TOKEN_GOES_HERE">
Dưới dạng tiêu đề HTTP:

Origin-Trial: TOKEN_GOES_HERE

Cung cấp mã thông báo theo phương thức lập trình:

const otMeta = document.createElement('meta');
otMeta.httpEquiv = 'origin-trial';
otMeta.content = 'TOKEN_GOES_HERE';
document.head.append(otMeta);

Một iframe chạy mã Protected Audience (chẳng hạn như navigator.joinAdInterestGroup()) lệnh gọi của chủ sở hữu nhóm mối quan tâm – sẽ cần cung cấp mã thông báo khớp với nguồn gốc của lệnh gọi.

Thông tin đề xuất về bản dùng thử theo nguyên gốc của Protected Audience cung cấp thêm thông tin chi tiết về mục tiêu của bản dùng thử đầu tiên và giải thích những tính năng được hỗ trợ.

Kiểm thử API này

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

Bằng cách bật tất cả các Ad Privacy API trong chrome://settings/adPrivacy
Bằng cách thiết lập cờ từ dòng lệnh.

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

Quảng cáo có thể 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

Bao gồm cờ BiddingAndScoringDebugReportingAPI để bật các phương thức báo cáo thắng/thua gỡ lỗi tạm thời.

Chạy Chromium bằng cờ giải thích cách đặt cờ khi chạy Chrome và các trình duyệt dựa trên Chromium khác từ lệnh . Danh sách đầy đủ các cờ Protected Audience có tại Tìm kiếm mã Chromium.

Phiên bản Chrome mới nhất hỗ trợ những tính năng nào?

Protected Audience sắp ra mắt phía sau các cờ tính năng trong Chromium thử nghiệm để kiểm tra các tính năng sau đây của đề xuất Protected Audience:

Nhóm mối quan tâm: được trình duyệt lưu trữ, cùng với siêu dữ liệu được liên kết để định cấu hình hoạt động đặt giá thầu quảng cáo và kết xuất hình ảnh.
Đặ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 mối quan tâm 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 trong phiên đấu giá và siêu dữ liệu từ người mua.
Hiển thị quảng cáo trong phiên bản khung bảo vệ tạm thời thoải mái: với quyền truy cập mạng và cho phép ghi nhật ký để hiển thị quảng cáo.

Thông tin giải thích về API sẽ cung cấp thêm thông tin chi tiết về việc hỗ trợ tính năng và các hạn chế.

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

Theo mặc định trong cách triển khai Protected Audience hiện tại là cho phép gọi joinAdInterestGroup() từ ở bất kỳ vị trí nào trong trang, ngay cả từ iframe trên nhiều miền. Trong tương lai, khi chủ sở hữu trang web có thời gian điều chỉnh chính sách về quyền iframe trên nhiều miền, kế hoạch là không cho phép cuộc gọi iframe trên nhiều miền, như nội dung giải thích mô tả.

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

Trong một phiên đấu giá quảng cáo sử dụng Protected Audience API, trình duyệt có thể truy cập vào dịch vụ khoá/giá trị trả về các cặp khoá-giá trị đơn giản để cung cấp thông tin cho người mua quảng cáo, chẳng hạn như ngân sách chiến dịch. Đề xuất sử dụng Protected Audience yêu cầu máy chủ này "không thực hiện ghi nhật ký ở cấp sự kiện và không có tác dụng phụ nào khác dựa trên yêu cầu".

Mã dịch vụ Khoá/Giá trị của Protected Audience hiện đã có trong kho lưu trữ GitHub về Hộp cát về quyền riêng tư. Các nhà phát triển Chrome và Android có thể sử dụng dịch vụ này. Hãy xem bài đăng về thông báo này trên blog để biết thông tin cập nhật về trạng thái. Tìm hiểu thêm về dịch vụ Khoá/giá trị của Protected Audience trong tài liệu giải thích về API và tài liệu giải thích về mô hình tin cậy.

Đối với thử nghiệm ban đầu, mô hình "Tạo máy chủ riêng của bạn" được sử dụ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ị của Protected Audience nguồn mở chạy trong môi trường thực thi đáng tin cậy để truy xuất dữ liệu theo thời gian thực.

Nhằm đảm bảo hệ sinh thái có đủ thời gian để thử nghiệm, chúng tôi dự kiến sẽ không yêu cầu bạn phải sử dụng các dịch vụ Khoá/giá trị nguồn mở hay TEE cho đến khi cookie của bên thứ ba không được dùng nữa. Chúng tôi sẽ thông báo đáng kể để nhà phát triển 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 hỗ trợ

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:

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

Làm cách nào để chọn không sử dụng Protected Audience?

Bạn có thể 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.

Các trang web có thể kiểm soát quyền truy cập bằng cách nào?

Sau này, Protected Audience sẽ yêu cầu các trang web đặt Chính sách về quyền để cho phép sử dụng chức năng Protected Audience. Điều này giúp đảm bảo rằng các bên thứ ba tuỳ ý không thể sử dụng API nếu không có kiến thức. Tuy nhiên, để tạo điều kiện cho việc thử nghiệm trong thời gian dùng thử theo nguyên gốc đầu tiên, yêu cầu này được miễn theo mặc định. Các trang web muốn tắt rõ ràng chức năng Protected Audience trong giai đoạn thử nghiệm có thể sử dụng Chính sách về quyền liên quan để chặn quyền truy cập.

Có 2 chính sách về quyền của Protected Audience có thể được đặt độc lập:

join-ad-interest-group bật/tắt chức năng thêm một trình duyệt vào nhóm mối quan tâm
run-ad-auction bật/tắt chức năng chạy phiên đấu giá trên thiết bị

Bạn có thể tắt hoàn toàn quyền truy cập vào Protected Audience API trong bối cảnh của bên thứ nhất bằng cách chỉ định các thông tin sau: chính sách quyền trong tiêu đề phản hồi HTTP:

Permissions-Policy: join-ad-interest-group=(), run-ad-auction=()

Bạn có thể tắt tính năng sử dụng API trong iframe bằng cách thêm thuộc tính allow sau đây vào một phần tử iframe:

<iframe src="https://example.com" allow="join-ad-interest-group 'none'; run-ad-auction 'none'"></iframe>

Phần Chính sách đề xuất về quyền của bản dùng thử theo nguyên gốc của Protected Audience sẽ cung cấp thêm thông tin chi tiết.

Người dùng chọn không tham gia

Người dùng có thể chặn quyền truy cập vào Protected Audience API và các tính năng khác của Hộp cát về quyền riêng tư bằng cách sử dụng bất kỳ các cơ chế sau:

Tắt bản dùng thử Hộp cát về quyền riêng tư trong phần Cài đặt của Chrome: Cài đặt > Bảo mật và quyền riêng tư > Hộp cát về quyền riêng tư. Bạn cũng có thể truy cập vào nội dung này tại chrome://settings/adPrivacy.
Tắt cookie của bên thứ ba trong phần Cài đặt của Chrome: Cài đặt > Bảo mật và quyền riêng tư.
Đặt Cookie và các dữ liệu khác của trang web thành "Chặn cookie của bên thứ ba" hoặc "Chặn tất cả cookie" từ chrome://settings/cookies.
Sử dụng Chế độ ẩn danh.

Thông tin giải thích về Protected Audience cung cấp thêm thông tin chi tiết về các phần tử thiết kế API và mô tả cách API này đáp ứng các mục tiêu về quyền riêng tư.

Gỡ lỗi công việc của Protected Audience

Từ Chrome Canary 98.0.4718.0, bạn có thể gỡ lỗi các worklet của Protected Audience trong Chrome Công cụ cho nhà phát triển.

Bước đầu tiên là đặt các điểm ngắt thông qua một danh mục mới trong ngăn Điểm ngắt trình xử lý sự kiện trong bảng điều khiển Sources (Nguồn).

Ảnh chụp màn hình của
Công cụ cho nhà phát triển trong Chrome Canary, trong đó ngăn Điểm ngắt trình nghe sự kiện trong bảng điều khiển Nguồn được làm nổi bật.
Bắt đầu giai đoạn đặt giá thầu của bên đặt giá thầu được chọn trong Worklet đấu giá quảng cáo.

Khi điểm ngắt kích hoạt, quá trình thực thi sẽ bị tạm dừng trước câu lệnh đầu tiên ở cấp cao nhất của lệnh tập lệnh worklet. Bạn có thể sử dụng các điểm ngắt thông thường hoặc lệnh thực hiện bước để chuyển đến phần đặt giá thầu/tính điểm/báo cáo chính nó.

Các tập lệnh worklet trực tiếp cũng sẽ xuất hiện trong bảng điều khiển Threads (Luồng).

Ảnh chụp màn hình của
Công cụ cho nhà phát triển trong Chrome Canary, trong đó ngăn Threads (Luồng) được làm nổi bật trong bảng điều khiển Nguồn, cho thấy bảng điều khiển hiện tại
tập lệnh worklet đã bị tạm dừng.

Vì một số worklet có thể chạy song song, nên nhiều luồng có thể bị "tạm dừng" nêu rõ ở đó; bạn có thể sử dụng danh sách luồng để chuyển đổi giữa các luồng, rồi tiếp tục hoặc kiểm tra chúng kỹ hơn phù hợp.

Quan sát các sự kiện Protected Audience

Trên bảng điều khiển Ứng dụng trong Công cụ của Chrome cho nhà phát triển, bạn có thể quan sát nhóm đối tượng có cùng mối quan tâm và phiên đấu giá của Protected Audience các sự kiện.

Nếu bạn truy cập vào trang web mua sắm minh hoạ của Protected Audience trong trình duyệt có bật Protected Audience, Công cụ cho nhà phát triển sẽ hiển thị thông tin về sự kiện join.

Chiến lược phát hành đĩa đơn
Bảng điều khiển Ứng dụng Công cụ cho nhà phát triển trong Chrome Canary, hiển thị thông tin về một nhóm đối tượng có cùng mối quan tâm của Protected Audience
tham gia sự kiện.

Bây giờ, nếu bạn truy cập vào trang web của nhà xuất bản minh hoạ về Protected Audience trong trình duyệt có bật Protected Audience, Công cụ cho nhà phát triển sẽ hiển thị thông tin về các sự kiện bid và win.

Chiến lược phát hành đĩa đơn
Bảng điều khiển Ứng dụng Công cụ cho nhà phát triển trong Chrome Canary, hiển thị thông tin về giá thầu trong phiên đấu giá Protected Audience và
giành chiến thắng.

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

Trong ví dụ này, 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à được hiển thị một quảng cáo về một mẫu xe đạp mới của nhà sản xuất xe đạp.

Cảnh báo: Không phải tất cả tính năng được mô tả trong bài đăng này đều đã được triển khai (hoặc triển khai đầy đủ) trong phiên bản của Protected Audience API hiện đang được thử nghiệm trong Chrome. Kiểm thử bằng cờ tính năng giải thích những tính năng của Protected Audience hiện có để thử nghiệm trong Chrome chạy từ dòng lệnh bằng cách sử dụng cờ tính năng. Chúng tôi dự kiến rằng các tính năng của Protected Audience sẽ được bổ sung theo thời gian trong quá trình triển khai. Một lần API chuyển đến giai đoạn dùng thử theo nguyên gốc, chúng tôi sẽ cung cấp một danh sách được cập nhật thường xuyên về những phần đã được triển khai và những việc vẫn đang trong quá trình hoàn thiện.

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

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

Giả sử 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 ở 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 cung cấp nhà sản xuất xe đạp với cơ hội tái tiếp thị.

Từ khoá quan trọng: Nền tảng bên cầu (DSP) là một dịch vụ công nghệ quảng cáo dùng để tự động hoá quy trình mua quảng cáo. DSP là được nhà quảng cáo dùng để mua lượt hiển thị quảng cáo trên hàng loạt trang web của nhà xuất bản. Nhà xuất bản bán khoảng không quảng cáo thông qua thị trường được gọi là Ad Exchange và DSP quyết định quảng cáo nào có sẵn bằng cách lập trình lượt hiển thị có ý nghĩa nhất đối với nhà quảng cáo nên mua. Nền tảng bên cung (SSP) là một dịch vụ công nghệ quảng cáo dùng để tự động hoá việc bán khoảng không quảng cáo. SSP cho phép nhà xuất bản cung cấp khoảng không quảng cáo của họ (các hình chữ nhật trống nơi quảng cáo sẽ đặt đến) cho nhiều quảng cáo sàn giao dịch, DSP và mạng. Điều này cho phép nhiều người mua tiềm năng đặt giá thầu cho không gian quảng cáo.

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

Hình minh hoạ cho thấy một người đang xem một trang web bằng trình duyệt trên máy tính xách tay. JavaScript
mã joinAdinterestGroup() đang chạy trong trình duyệt.

Mục Người giải thích: Các nhóm mối quan tâm ghi lại của trình duyệt

Nền tảng bên cầu (DSP) của nhà quảng cáo (hoặc 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 có chứa trình duyệt. Trong ví dụ này, nhóm được đặt tên là custom-bikes và chủ sở hữu là dsp.example. Chủ sở hữu nhóm đối tượng có cùng 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 được mô tả trong bước 4. Tư cách thành viên của nhóm đối tượng có cùng mối quan tâm được trình duyệt, trên thiết bị của người dùng lưu trữ và không được chia sẻ với nhà cung cấp trình duyệt hay bất kỳ ai khác.

Lưu ý: Nguồn gốc của ngữ cảnh gọi cho joinAdInterestGroup() phải khớp với nhóm đối tượng có cùng mối quan tâm nguồn gốc của chủ sở hữu, vì vậy, joinAdInterestGroup() sẽ cần được gọi từ iframe (đối với từ một DSP), trừ phi nguồn gốc của chủ sở hữu nhóm mối quan tâm khớp với nguồn gốc của tài liệu (ví dụ: một trang web với các nhóm mối quan tâm riêng). runAdAuction không có cùng yêu cầu, vì vậy, việc gọi runAdAuction() từ một <script> có thể mang lại hiệu quả cao hơn nhiều so với iframe trên nhiều nguồn gốc.

joinAdInterestGroup() yêu cầu bạn cấp quyền:

Trang web đang được truy cập
Chủ sở hữu nhóm mối quan tâm

Ví dụ: malicious.example không được phép gọi joinAdInterestGroup() có dsp.example là chủ sở hữu mà không có sự cho phép của dsp.example.

Quyền từ trang web mà người dùng đang truy cập

Cùng nguồn gốc: Theo mặc định, quyền được cấp cho các lệnh gọi joinAdInterestGroup() qua mặc định có cùng nguồn gốc với trang web đang được truy cập, tức là có cùng nguồn gốc với khung cấp cao nhất của trang hiện tại. Các trang web có thể sử dụng tiêu đề chính sách về quyền của Protected Audience Lệnh join-ad-interest-group để vô hiệu hoá các lệnh gọi joinAdInterestGroup().

Nhiều nguồn gốc: Gọi joinAdInterestGroup() từ các nguồn gốc khác với nguồn hiện tại chỉ có thể thành công nếu trang web đang được truy cập đã đặt chính sách quyền cho phép cuộc gọi đến joinAdInterestGroup() khỏi các iframe nhiều nguồn gốc.

Lưu ý: Chế độ mặc định trong cách triển khai Protected Audience hiện tại là cho phép các lệnh gọi đến joinAdInterestGroup() từ bất kỳ vị trí nào trong một trang, ngay cả từ các iframe nhiều nguồn gốc. Trong tương lai, khi chủ sở hữu trang web đã có thời gian điều chỉnh chính sách quyền của họ. Theo mặc định, kế hoạch sẽ không cho phép các cuộc gọi iframe trên nhiều nguồn gốc, như mô tả trong phần giải thích về Protected Audience.

Sự cho phép của chủ sở hữu nhóm mối quan tâm

Quyền của chủ sở hữu nhóm mối quan tâm được ngầm cấp bằng cách gọi joinAdInterestGroup() từ một iframe có cùng nguồn gốc với iframe của chủ sở hữu nhóm mối quan tâm. Ví dụ: dsp.example iframe có thể gọi joinAdInterestGroup() cho các nhóm mối quan tâm do dsp.example sở hữu.

Đề xuất là joinAdInterestGroup() có thể chạy trong một trang hoặc iframe trong miền của chủ sở hữu, hoặc được uỷ quyền cho các miền khác được cung cấp bằng danh sách tại URL .well-known.

Sử dụng navigator.joinAdinterestGroup()

Dưới đây là ví dụ về cách sử dụng API này:

const interestGroup = {
  owner: 'https://dsp.example',
  name: 'custom-bikes',
  biddingLogicUrl: ...,
  biddingWasmHelperUrl: ...,
  dailyUpdateUrl: ...,
  trustedBiddingSignalsUrl: ...,
  trustedBiddingSignalsKeys: ['key1', 'key2'],
  userBiddingSignals: {...},
  ads: [bikeAd1, bikeAd2, bikeAd3],
  adComponents: [customBike1, customBike2, bikePedal, bikeFrame1, bikeFrame2],
};

navigator.joinAdInterestGroup(interestGroup, 7 * kSecsPerDay);

Đối tượng interestGroup được truyền vào hàm không được có kích thước không quá 50 kiB, nếu không thì sẽ không thực hiện được lệnh gọi. Tham số thứ hai chỉ định thời lượng của nhóm mối quan tâm, giới hạn ở mức 30 ngày. Các lệnh gọi tiếp theo sẽ ghi đè các giá trị đã lưu trữ trước đó.

Lưu ý quan trọng: Tất cả URL được dùng làm tham số cho các phương thức Protected Audience API đều phải từ nguồn gốc bảo mật: tất cả tài nguyên đều phải được phân phát qua URL HTTPS. Cách sử dụng HTTPS để phát triển cục bộ giải thích cách thực hiện việc này khi chạy Protected Audience cục bộ. Ngoài ra, biddingLogicUrl, decisionLogicUrl và trustedBiddingSignals đều yêu cầu phải có một Tiêu đề phản hồi HTTP X-Allow-FLEDGE: true.

Thuộc tính nhóm mối quan tâm

Thuộc tính	Bắt buộc	Ví dụ:	Vai trò
`owner`	Bắt buộc	`'https://dsp.example'`	Nguồn gốc của chủ sở hữu nhóm mối quan tâm.
`name`	Bắt buộc	`'custom-bikes'`	Tên của nhóm mối quan tâm.
`biddingLogicUrl`**	Không bắt buộc*	`'https://dsp.example/bid/custom-bikes/bid.js'`	URL để đặt giá thầu JavaScript chạy trong worklet.
`biddingWasmHelperUrl`**	Không bắt buộc*	`'https://dsp.example/bid/custom-bikes/bid.wasm'`	URL cho mã WebAssembly lấy từ `biddingLogicUrl`.
`dailyUpdateUrl`**	Không bắt buộc	`'https://dsp.example/bid/custom-bikes/update'`	URL trả về JSON để cập nhật các thuộc tính nhóm mối quan tâm. (Xem bài viết Cập nhật nhóm mối quan tâm.)
`trustedBiddingSignalsUrl`**	Không bắt buộc	`'https://dsp.example/trusted/bidding-signals'`	URL cơ sở cho các yêu cầu khoá-giá trị gửi đến máy chủ đáng tin cậy của bên đặt giá thầu.
`trustedBiddingSignalsKeys`	Không bắt buộc	`['key1', 'key2' ...]`	Khoá cho các yêu cầu gửi khoá-giá trị máy chủ đáng tin cậy.
`userBiddingSignals`	Không bắt buộc	`{...}`	Siêu dữ liệu bổ sung mà chủ sở hữu có thể sử dụng trong khi đặt giá thầu.
`ads`	Không bắt buộc*	`[bikeAd1, bikeAd2, bikeAd3]`	Những quảng cáo có thể được hiển thị cho nhóm mối quan tâm này.
`adComponents`	Không bắt buộc	`[customBike1, customBike2, bikePedal, bikeFrame1, bikeFrame2]`	Thành phần cho quảng cáo bao gồm nhiều phần.

* Tất cả các thuộc tính đều không bắt buộc, ngoại trừ owner và name. biddingLogicUrl và ads thuộc tính là không bắt buộc, nhưng bắt buộc phải tham gia vào phiên đấu giá. Có thể có trường hợp sử dụng cho tạo một nhóm mối quan tâm không có các thuộc tính này: ví dụ: chủ sở hữu nhóm mối quan tâm có thể muốn thêm một trình duyệt vào nhóm mối quan tâm cho một chiến dịch chưa chạy hoặc cho một số người dùng cho mục đích sử dụng khác trong tương lai hoặc tạm thời có thể hết ngân sách quảng cáo.

** Các URL biddingLogicUrl, biddingWasmHelperUrl, dailyUpdateUrl và trustedBiddingSignalsUrl phải có cùng nguồn gốc với chủ sở hữu. Các URL ads và adComponents không có quy tắc ràng buộc nào như vậy.

Cập nhật thuộc tính nhóm mối quan tâm

dailyUpdateUrl chỉ định một máy chủ web trả về JSON xác định các thuộc tính nhóm mối quan tâm, tương ứng với đối tượng nhóm mối quan tâm được truyền đến navigator.joinAdInterestGroup(). Chiến dịch này cung cấp cơ chế để chủ sở hữu nhóm cập nhật định kỳ các thuộc tính của nhóm có cùng mối quan tâm. Trong cách triển khai hiện tại, bạn có thể thay đổi các thuộc tính sau:

biddingLogicUrl
biddingWasmHelperUrl
trustedBiddingSignalsUrl
trustedBiddingSignalsKeys
ads
priority

Mọi trường không được chỉ định trong JSON sẽ không bị ghi đè – chỉ những trường được chỉ định trong JSON mới nhận được được cập nhật, trong khi việc gọi navigator.joinAdInterestGroup() sẽ ghi đè mọi nhóm quan tâm hiện có.

Quá trình cập nhật sẽ được thực hiện với nỗ lực tối đa và có thể không thành công trong những điều kiện sau:

Thời gian chờ yêu cầu mạng (hiện là 30 giây).
Lỗi mạng khác.
Không thể phân tích cú pháp JSON.

Bản cập nhật cũng có thể bị huỷ nếu bạn dành quá nhiều thời gian liền nhau cho việc cập nhật, mặc dù vậy không áp dụng bất kỳ giới hạn tỷ lệ nào đối với các bản cập nhật bị huỷ (còn lại). Nội dung cập nhật có giới hạn tỷ lệ đối với một tối đa một lần mỗi ngày. Những bản cập nhật không thành công do lỗi mạng sẽ được thử lại sau một giờ, và các bản cập nhật không thành công do bị ngắt kết nối Internet sẽ được thử kết nối lại ngay lập tức.

Các bản cập nhật thủ công

Bạn có thể kích hoạt nội dung cập nhật đối với nhóm mối quan tâm do nguồn gốc của khung hiện tại sở hữu theo cách thủ công thông qua navigator.updateAdInterestGroups(). Giới hạn số lượng yêu cầu ngăn việc cập nhật diễn ra quá thường xuyên: các lệnh gọi lặp lại đến navigator.updateAdInterestGroups() không làm gì cho đến giới hạn số lượng yêu cầu khoảng thời gian (hiện là một ngày) đã trôi qua. Giới hạn số lượng yêu cầu sẽ được đặt lại nếu navigator.joinAdInterestGroup() được gọi lại cho cùng một nhóm mối quan tâm owner và name.

Tự động cập nhật

Tất cả các nhóm mối quan tâm được tải cho một phiên đấu giá đều được cập nhật tự động sau khi phiên đấu giá hoàn tất. tuân theo cùng giới hạn số lượng yêu cầu như khi cập nhật thủ công. Dành cho mỗi chủ sở hữu có ít nhất một nhóm mối quan tâm việc tham gia vào một phiên đấu giá giống như thể navigator.updateAdInterestGroups() được gọi từ một iframe có nguồn gốc khớp với chủ sở hữu đó.

Chỉ định quảng cáo cho nhóm sở thích

Các đối tượng ads và adComponents bao gồm URL của mẫu quảng cáo và tuỳ ý siêu dữ liệu 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 như thế nào?

Tập lệnh tại biddingLogicUrl do chủ sở hữu nhóm mối quan tâm cung cấp phải bao gồm generateBid() . Khi người bán không gian quảng cáo gọi navigator.runAdAuction(), generatedBid() được gọi một lần cho mỗi nhóm mối quan tâm mà trình duyệt là thành viên, nếu quan tâm chủ sở hữu của nhóm được mời đặt giá thầu. Nói cách khác, generateBid() được gọi một lần cho mỗi ứng cử viên quảng cáo. Người bán cung cấp tài sản decisionLogicUrl trên thông số cấu hình phiên đấu giá đã chuyển đến navigator.runAdAuction(). Mã tại URL này phải bao gồm hàm scoreAd(), tức là chạy cho từng bên đặt giá thầu trong phiên đấu giá để tính điểm từng giá thầu do generateBid() trả về.

Lưu ý: Thuộc tính biddingWasmHelperUrl là không bắt buộc nhưng cho phép bên đặt giá thầu cung cấp các chương trình con có chi phí tính toán cao trong WebAssembly, thay vì JavaScript, được điều khiển từ hàm JavaScript do biddingLogicUrl cung cấp. Nếu nếu được cung cấp, mã này phải trỏ đến tệp nhị phân WebAssembly, được phân phối bằng application/wasm mimetype. Chiến lược phát hành đĩa đơn WebAssembly.Module tương ứng mà trình duyệt cung cấp cho hàm generateBid().

Tập lệnh tại biddingLogicUrl do người mua không gian quảng cáo cung cấp phải bao gồm hàm generateBid(). Hàm này được gọi một lần cho mỗi quảng cáo đề xuất. runAdAuction() kiểm tra riêng từng quảng cáo, cùng với giá thầu và siêu dữ liệu được liên kết của quảng cáo đó, sau đó chỉ định quảng cáo điểm số mong muốn bằng số.

generateBid(interestGroup, auctionSignals, perBuyerSignals,
    trustedBiddingSignals, browserSignals) {
  ...
  return {
    ad: adObject,
    bid: bidValue,
    render: renderUrl,
    adComponents: [adComponentRenderUrl1, ...]
   };
}

generateBid() nhận các đối số sau:

interestGroup Đối tượng được người mua quảng cáo chuyển đến joinAdInterestGroup(). (Nhóm đối tượng có cùng mối quan tâm có thể được cập nhật thông qua dailyUpdateUrl.)
auctionSignals Thuộc tính của đối số cấu hình phiên đấu giá được truyền đến navigator.runAdAuction() bởi người bán không gian quảng cáo. Thông tin này cung cấp thông tin về ngữ cảnh của trang (chẳng hạn như kích thước quảng cáo và mã nhà xuất bản), loại phiên đấu giá (giá đầu tiên hoặc giá thứ hai) và các siêu dữ liệu.
perBuyerSignals Giống như auctionSignals, một thuộc tính của cấu hình phiên đấu giá đối số được người bán chuyển đến navigator.runAdAuction(). Thông tin này có thể cung cấp thông tin theo bối cảnh tín hiệu từ máy chủ của người mua về trang, nếu người bán là SSP thực hiện lệnh gọi đặt giá thầu theo thời gian thực đến máy chủ của người mua và chuyển lại phản hồi hoặc nếu nhà xuất bản liên hệ trực tiếp với máy chủ của người mua. Nếu có, người mua có thể muốn kiểm tra mật mã chữ ký của các tín hiệu đó bên trong generateBid() để bảo vệ khỏi hành vi can thiệp.
trustedBiddingSignals Đối tượng có các khoá là trustedBiddingSignalsKeys cho nhóm đối tượng có cùng mối quan tâm và có giá trị được trả về trong yêu cầu trustedBiddingSignals.
browserSignals Đối tượng do trình duyệt tạo ra, có thể bao gồm thông tin về trang ngữ cảnh (chẳng hạn như hostname của trang hiện tại mà người bán có thể giả mạo) và dữ liệu cho chính nhóm đối tượng có cùng mối quan tâm (chẳng hạn như hồ sơ về thời điểm mà nhóm đó đã thắng một phiên đấu giá trước đây, để cho phép giới hạn tần suất trên thiết bị).

Đối tượng browserSignals có các thuộc tính sau:

{
  topWindowHostname: 'publisher.example',
  seller: 'https://ssp.example',
  joinCount: 3,
  bidCount: 17,
  prevWins: [[time1,ad1],[time2,ad2],...],
  wasmHelper: ... /* WebAssembly.Module object based on interest group's biddingWasmHelperUrl. */
  dataVersion: 1, /* Data-Version value from the buyer's Key/Value service response(s). */
}

Để tính giá trị bid, mã trong generateBid() có thể sử dụng các thuộc tính của hàm tham số. Ví dụ:

function generateBid(interestGroup, auctionSignals, perBuyerSignals,
    trustedBiddingSignals, browserSignals) {
  return {
    ...
    bid: auctionSignals.is_above_the_fold ? perBuyerSignals.atf_value : perBuyerSignals.btf_value,
    ...
  }
}

generateBid() trả về một đối tượng có 4 thuộc tính:

ad Siêu dữ liệu tuỳ ý về quảng cáo, chẳng hạn như thông tin mà người bán muốn biết về giá thầu này hoặc mẫu quảng cáo. Người bán](/privacy-sandbox/resources/lưu#ssp) sử dụng thông tin này trong phiên đấu giá và quyết định của họ mẫu quảng cáo. Người bán sử dụng thông tin này trong phiên đấu giá và quyết định logic.
bid Giá thầu bằng số sẽ tham gia phiên đấu giá. Người bán phải có vị trí để so sánh giá thầu từ những người mua khác nhau, do đó, giá thầu phải bằng một số đơn vị do người bán chọn (ví dụ: "USD trên nghìn"). Nếu giá thầu bằng 0 hoặc âm, thì nhóm sở thích này sẽ không tham gia vào phiên đấu giá của người bán. Với cơ chế này, người mua có thể triển khai mọi quy tắc của nhà quảng cáo đối với vị trí quảng cáo của họ có thể xuất hiện hoặc không.
render URL hoặc danh sách URL sẽ được dùng để hiển thị mẫu quảng cáo nếu giá thầu này thắng phiên đấu giá. (Xem Quảng cáo bao gồm nhiều phần trong thông báo giải thích về API.) Giá trị này phải khớp với renderUrl của một trong quảng cáo được xác định cho nhóm đối tượng có cùng mối quan tâm.
adComponents Danh sách không bắt buộc gồm tối đa 20 thành phần cho quảng cáo bao gồm nhiều phần, được lấy từ thuộc tính adComponents của đối số nhóm mối quan tâm được truyền đến navigator.joinAdInterestGroup().

Yêu cầu trình duyệt rời khỏi nhóm mối quan tâm

Chủ sở hữu nhóm mối quan tâm có thể yêu cầu xoá một trình duyệt khỏi nhóm mối quan tâm. Trong khu vực khác thì trình duyệt sẽ được yêu cầu xoá nhóm đối tượng có cùng mối quan tâm khỏi danh sách các nhóm đối tượng mà trình duyệt là thành viên.

navigator.leaveAdInterestGroup({
  owner: 'https://dsp.example',
  name: 'custom-bikes'
});

Nếu người dùng quay lại trang web yêu cầu trình duyệt thêm nhóm mối quan tâm, thì chủ sở hữu nhóm mối quan tâm đó có thể gọi hàm navigator.leaveAdInterestGroup() để yêu cầu trình duyệt xoá nhóm quan tâm. Mã cho một quảng cáo cũng có thể gọi hàm này cho nhóm mối quan tâm của quảng cáo đó.

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

Hình minh hoạ một người truy cập vào một trang web tin tức bằng trình duyệt trên máy tính xách tay. Trang web này
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à trang web tin tức. Trang web này có khoảng không quảng cáo, tức là bán theo phương thức có lập trình bằng cách sử dụng đặt giá thầu theo thời gian thực.

Lưu ý: Có 3 vai trò chính được mô tả trong phần giải thích về đề xuất Protected Audience: * Nhà quảng cáo: trang web trả tiền để quảng cáo sản phẩm của họ. Trong ví dụ ở đây, một chiếc xe đạp tuỳ chỉnh . * Nhà xuất bản: những trang web bán không gian quảng cáo, chẳng hạn như trang web tin tức trực tuyến được đề cập trong ví dụ tại đây. Nhiều (nhưng không phải tất cả) các trang web bán không gian quảng cáo là nhà xuất bản nội dung. * Người bán: bên chạy phiên đấu giá quảng cáo (trong bước tiếp theo). Hầu hết các nhà xuất bản đều sử dụng công nghệ quảng cáo như SSP để tối ưu hoá việc bán khoảng không quảng cáo.

4. Một phiên đấu giá quảng cáo sẽ chạy trong trình duyệt

Hình minh hoạ cho thấy một người đang xem trang web tin tức bằng trình duyệt trên máy tính xách tay. Một quảng cáo
phiên đấu giá sử dụng Protected Audience API đang diễn ra.

Mục giải thích: Người bán tiến hành phiên đấu giá trên thiết bị

Phiên đấu giá quảng cáo có thể do SSP của nhà xuất bản chạy, hoặc chính nhà xuất bản đó. Mục đích của phiên đấu giá là để chọn quảng cáo thích 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á xem xét các nhóm mối quan tâm mà trình duyệt là một thành viên của, 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ị.

Người bán không gian quảng cáo đưa ra yêu cầu tới trình duyệt của người dùng để bắt đầu phiên đấu giá quảng cáo bằng cách gọi navigator.runAdAuction().

Ví dụ:

const auctionConfig = {
  seller: 'https://ssp.example',
  decisionLogicUrl: ...,
  trustedScoringSignalsUrl: ...,
  interestGroupBuyers: ['https://dsp.example', 'https://buyer2.example', ...],
  auctionSignals: {...},
  sellerSignals: {...},
  sellerTimeout: 100,
  perBuyerSignals: {
    'https://dsp.example': {...},
    'https://another-buyer.example': {...},
    ...
  },
  perBuyerTimeouts: {
    'https://dsp.example': 50,
    'https://another-buyer.example': 200,
    '*': 150,
    ...
  },
  componentAuctions: [
    {
      'seller': 'https://some-other-ssp.example',
      'decisionLogicUrl': ...,
      ...
    },
    ...
  ]
};

const auctionResultPromise = navigator.runAdAuction(auctionConfig);

runAdAuction() trả về một lời hứa phân giải thành URN (urn:uuid:<something>) đại diện cho kết quả đấu giá quảng cáo. Chỉ trình duyệt mới giải mã được điều này khi được truyền vào một khung bảo vệ để hiển thị: trang nhà xuất bản không thể kiểm tra quảng cáo giành chiến thắng.

Lưu ý: Như đã giải thích trước đó, nguồn gốc của ngữ cảnh gọi cho joinAdInterestGroup() phải khớp với chủ sở hữu nhóm quan tâm điểm gốc, nên joinAdInterestGroup() sẽ cần được gọi từ iframe (ví dụ: từ DSP) trừ phi nguồn gốc của chủ sở hữu nhóm mối quan tâm khớp với nguồn gốc của tài liệu (ví dụ: một trang web với các nhóm mối quan tâm riêng). runAdAuction không có cùng yêu cầu, vì vậy, việc gọi runAdAuction() từ một <script> có thể mang lại hiệu quả cao hơn nhiều so với iframe trên nhiều nguồn gốc.

Tập lệnh decisionLogicUrl xem xét từng quảng cáo riêng lẻ, cùng với giá thầu được liên kết và từng siêu dữ liệu, sau đó chỉ định cho siêu dữ liệu đó điểm số mong muốn.

`auctionConfig` cơ sở lưu trú

Thuộc tính	Bắt buộc	Ví dụ:	Vai trò
`seller`	Bắt buộc	`'https://ssp.example'`	Nguồn gốc người bán.
`decisionLogicUrl`	Bắt buộc	`'https://ssp.example/auction-decision-logic.js'`	URL dành cho JavaScript worklet đấu giá.
`trustedScoringSignalsUrl`	Không bắt buộc	`'https://ssp.example/scoring-signals'`	URL của máy chủ đáng tin cậy của người bán.
`interestGroupBuyers*`	Bắt buộc	`['https://dsp.example', 'https://buyer2.example', ...]`	Nguồn gốc của tất cả các chủ sở hữu nhóm mối quan tâm đã yêu cầu đặt giá thầu trong phiên đấu giá.
`auctionSignals`	Không bắt buộc	`{...}`	Thông tin của người bán về bối cảnh của trang, loại phiên đấu giá, v.v.
`sellerSignals`	Không bắt buộc	`{...}`	Thông tin dựa trên chế độ cài đặt của nhà xuất bản, việc đưa ra yêu cầu quảng cáo theo bối cảnh, v.v.
`sellerTimeout`	Không bắt buộc	`100`	Thời gian chạy tối đa (mili giây) của tập lệnh `scoreAd()` của người bán.
`perBuyerSignals`	Không bắt buộc	`{'https://dsp.example': {...}, 'https://another-buyer.example': {...}, ...}`	Tín hiệu bối cảnh về trang cho từng người mua cụ thể, từ máy chủ của họ.
`perBuyerTimeouts`	Không bắt buộc	`50`	Thời gian chạy tối đa (mili giây) của tập lệnh `generateBid()` của người mua cụ thể.
`componentAuctions`	Không bắt buộc	`[{'seller': 'https://www.some-other-ssp.com', 'decisionLogicUrl': ..., ...}, ...]`	Cấu hình bổ sung cho phiên đấu giá thành phần.

* Người bán có thể chỉ định interestGroupBuyers: '*' để cho phép tất cả các nhóm mối quan tâm đặt giá thầu. Sau đó, quảng cáo được chấp nhận hoặc bị từ chối dựa trên các tiêu chí khác ngoài việc bao gồm chủ sở hữu nhóm mối quan tâm. Ví dụ: người bán có thể xem xét mẫu quảng cáo để xác nhận rằng họ tuân thủ chính sách của họ.

** additionalBids không được hỗ trợ trong quá trình triển khai Protected Audience hiện tại. Đọc thông tin về Phiên đấu giá Phần Người tham gia trong Thông tin giải thích về Protected Audience để biết thêm thông tin.

Quảng cáo được chọn như thế nào?

Mã tại decisionLogicUrl (thuộc tính của đối tượng cấu hình đấu giá đã được chuyển đến runAdAuction()) phải bao gồm hàm scoreAd(). Thử nghiệm này được chạy một lần cho mỗi quảng cáo để xác định mức độ mong muốn của ứng dụng.

scoreAd(adMetadata, bid, auctionConfig, trustedScoringSignals, browserSignals) {
  ...
  return desirabilityScoreForThisAd;
}

scoreAd() nhận các đối số sau:

adMetadata Siêu dữ liệu tuỳ ý do người mua cung cấp.
bid Giá trị giá thầu bằng số.
auctionConfig Đối tượng cấu hình phiên đấu giá được truyền đến navigator.runAdAuction().
trustedScoringSignals Các giá trị được truy xuất tại thời điểm đấu giá từ máy chủ đáng tin cậy của người bán, thể hiện ý kiến của người bán về quảng cáo.
browserSignals Đối tượng do trình duyệt tạo, bao gồm thông tin mà trình duyệt biết và tập lệnh đấu giá nào của người bán có thể muốn xác minh:

{
  topWindowHostname: 'publisher.example',
  interestGroupOwner: 'https://dsp.example',
  renderUrl: 'https://cdn.example/render',
  adComponents: ['https://cdn.com/ad-component-1', ...],
  biddingDurationMsec: 12,
  dataVersion: 1 /* Data-Version value from the seller's Key/Value service response. */
}

Trước khi phiên đấu giá bắt đầu, người bán tìm quảng cáo theo bối cảnh phù hợp nhất cho vùng quảng cáo có sẵn. Thuộc logic scoreAd() của nút này là để từ chối mọi quảng cáo không thể đánh bại quảng cáo chiến thắng theo bối cảnh.

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

Phần Giải thích: Tìm nạp dữ liệu theo thời gian thực từ dịch vụ Khoá/giá trị của Protected Audience.

Trong phiên đấu giá quảng cáo, người bán không gian quảng cáo có thể nhận 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 tới dịch vụ Khoá/Giá trị bằng cách sử dụng thuộc tính trustedScoringSignalsUrl của đối số cấu hình phiên đấu giá được chuyển đến navigator.runAdAuction(), cùng với các khoá từ thuộc tính renderUrl của tất cả mục nhập trong các trường ads và adComponents trong tất cả nhóm có cùng mối quan tâm trong phiên đấu giá.

Tương tự, người mua không gian quảng cáo 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 một yêu cầu đến máy chủ đáng tin cậy của mỗi người mua quảng cáo. Chiến lược phát hành đĩa đơn 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 các giá trị cho mỗi khoá.

Lưu ý quan trọng: Trong giai đoạn thử nghiệm ban đầu hiện tại để kiểm thử Protected Audience, trustedBiddingSignalsUrl phải có có cùng nguồn gốc với chủ sở hữu nhóm mối quan tâm: hãy xem Tài sản nhóm đối tượng có cùng mối quan tâm và mang theo máy chủ riêng.

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

Hình minh hoạ cho thấy một người đang xem trang web tin tức bằng trình duyệt trên máy tính xách tay. Một quảng cáo
cho xe đạp (giảm 20%) được hiển thị — có khoá ở trên để cho biết rằng quảng cáo được hiển thị ở
khung bảo vệ.

Phần người giải thích: Trình duyệt hiển thị quảng cáo giành chiến thắng

Như đã mô tả trước đó: lời hứa mà runAdAuction() trả về sẽ phân giải thành một URN được truyền đến một khung bảo vệ để hiển thị, sau đó trang web sẽ hiển thị quảng cáo giành chiến thắng.

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

Phần giải thích: Báo cáo ở cấp sự kiện (hiện tại)

Lưu ý: 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 cả người bán và người mua bằng cách sử dụng API báo cáo tổng hợp. 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(). Việc này cần 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 cần báo cáo.

Kết quả báo cáo của người bán

Mục giải thích: Báo cáo của người bán trên Mạng Hiển thị

JavaScript của người bán được cung cấp tại decisionLogicUrl (cũng cung cấp scoreAd()) có thể thêm hàm reportResult() để báo cáo kết quả phiên đấu giá.

reportResult(auctionConfig, browserSignals) {
  ...
  return signalsForWinner;
}

Các đối số được truyền đến hàm này là:

auctionConfig Đối tượng cấu hình phiên đấu giá được truyền đến navigator.runAdAuction().

browserSignals số
Đối tượng được tạo bởi trình duyệt cung cấp thông tin về phiên đấu giá. Ví dụ:

{
  'topWindowHostname': 'publisher.example',
  'interestGroupOwner': 'https://dsp.example',
  'renderUrl': 'https://cdn.example/url-of-winning-creative.wbn',
  'bid:' <bidValue>,
  'desirability': <winningAdScore>
}

Giá trị trả về của hàm này được dùng làm đối số sellerSignals cho giá trị của bên thắng thầu reportWin().

Kết quả báo cáo của bên đặt giá thầu thắng cuộc

Mục giải thích: Báo cáo của người mua về tính năng Hiển thị và Sự kiện quảng cáo

JavaScript của bên đặt giá thầu giành chiến thắng (cũng cung cấp generateBid()) có thể bao gồm một reportWin() để báo cáo kết quả phiên đấu giá.

reportWin(auctionSignals, perBuyerSignals, sellerSignals, browserSignals) {
  ...
}

Lưu ý: Quy trình triển khai Protected Audience hiện tại trong Chrome sẽ cảnh báo nếu bạn chưa xác định reportWin().

Các đối số được truyền đến hàm này là:

auctionSignals và perBuyerSignals
Các giá trị tương tự đã được chuyển đến generateBid() cho bên đặt giá thầu giành chiến thắng.
sellerSignals Giá trị trả về của reportResult(), giúp người bán có cơ hội truyền thông tin đến người mua.

browserSignals Đối tượng được tạo bởi trình duyệt cung cấp thông tin về phiên đấu giá. Ví dụ:

{
  'topWindowHostname': 'publisher.example',
  'seller': 'https://ssp.example',
  'interestGroupOwner': 'https://dsp.example',
  'interestGroupName': 'custom-bikes',
  'renderUrl': 'https://cdn.example/winning-creative.wbn',
  'bid:' <bidValue>
}

Triển khai báo cáo thắng/thua tạm thời

Có hai phương thức tạm thời có sẵn trong Chrome để báo cáo phiên đấu giá:

forDebuggingOnly.reportAdAuctionLoss()
forDebuggingOnly.reportAdAuctionWin()

Mỗi phương thức này sẽ nhận một đối số duy nhất: một URL để tìm nạp sau khi phiên đấu giá hoàn tất. Chúng có thể được gọi nhiều lần, trong cả scoreAd() và generateBid(), với các đối số URL khác nhau.

Chrome chỉ gửi báo cáo gỡ lỗi/thắng/thua khi phiên đấu giá kết thúc. Nếu phiên đấu giá là bị huỷ (ví dụ: do điều hướng mới) sẽ không có báo cáo nào được tạo.

Những phương thức này có sẵn theo mặc định trong Chrome. Để có thể kiểm thử các phương thức, hãy bật tất cả API Quyền riêng tư trong quảng cáo trong chrome://settings/adPrivacy. Nếu đang chạy Chrome có cờ dòng lệnh để bật Protected Audience, bạn cần bật các phương thức một cách rõ ràng bằng cách thêm cờ BiddingAndScoringDebugReportingAPI. Nếu cờ chưa được bật, các phương thức sẽ vẫn khả dụng nhưng không làm gì cả.

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

Đang thể hiện hình minh hoạ
một người đang nhấp vào quảng cáo về xe đạp, bên trong khung có hàng rào, trên một trang web tin tức, với phóng sự
đến người bán và người mua.

Hệ thống sẽ báo cáo một lượt nhấp vào quảng cáo hiển thị trong khung bảo vệ. Để tìm hiểu thêm về cách hoạt động của tính năng này, xem Báo cáo quảng cáo có khung bảo vệ.

Sơ đồ dưới đây trình bày từng giai đoạn trong phiên đấu giá quảng cáo sử dụng Protected Audience API:

Hình minh hoạ cung cấp thông tin tổng quan về từng giai đoạn của một phiên đấu giá quảng cáo sử dụng Protected Audience API

Sự khác biệt giữa Protected Audience và TURTLEDOVE là gì?

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

Protected Audience 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 người dùng có khả năng quan tâm và trước đó đã 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 hiệu quả bằng cách nhà quảng cáo nhận ra một người cụ thể khi họ duyệt qua các trang web. Đây là mối quan tâm chính về quyền riêng tư của web ngày nay.

Nỗ lực của TURTLEDOVE nhằm 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, không phải nhà quảng cáo, lưu giữ thông tin về những gì nhà quảng cáo cho rằng người quan tâm.
Nhà quảng cáo có thể phân phát quảng cáo dựa trên sở thích, nhưng không thể kết hợp sở thích đó với sở thích khác thông tin về một người — cụ thể là họ là ai hoặc họ đang truy cập trang nào.

Protected Audience phát triển từ TURTLEDOVE và một tập hợp các đề xuất sửa đổi có liên quan nhằm phục vụ tốt hơn 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ụ ("người trực điện thoại") chạy trong môi trường thực thi đáng tin cậy (TEE). Protected Audience hạn chế hơn việc sử dụng các TEE để tra cứu dữ liệu theo thời gian thực và báo cáo tổng hợp.
TERN và Magnite của NextRoll CHỨC DANH đề xuất mô tả 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/tính điểm quảng cáo của Protected Audience dựa trên công việc này.
Dựa trên kết quả của RTB House và TURTLEDOVE cấp sản phẩm các sửa đổi giúp 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 TURTLEDOVE dựa vào 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 quyền riêng tư các thuộc tính. Protected Audience chưa áp dụng mô hình proxy này. Chúng tôi mang đến API JavaScript để paraKEET và Protected Audience phù hợp với nhau, hỗ trợ công việc trong tương lai nhằm kết hợp thêm những tính năng của cả hai đề xuất.

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

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

Người dùng có thể điều chỉnh việc họ tham gia 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 quá trình thử nghiệm ban đầu, mọi người sẽ 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. Chrome dự định cho phép người dùng xem và quản lý danh sách nhóm mối quan tâm mà họ đã được thêm vào trên web các trang web mà họ đã truy cập. Cũng giống như 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 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 khi đề xuất về Protected Audience diễn ra, dựa trên các bài kiểm thử 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 và dữ liệu liên quan.

Người 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 bị loại bỏ khi người dùng xoá dữ liệu trang web của họ.

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

GitHub: Đọc đề xuất, đặt câu hỏi và theo dõi nội dung thảo luận.
W3C: Thảo luận các trường hợp sử dụng của ngành trong bài viết Cải thiện hoạt động kinh doanh quảng cáo web Nhóm.
Hỗ trợ nhà phát triển: Đặt câu hỏi và tham gia thảo luận trên Kho lưu trữ hỗ trợ nhà phát triển Hộp cát về quyền riêng tư.
Danh sách gửi thư FLEDGE: fledge-api-announce đưa ra thông báo và nội dung cập nhật về API này.
Tham gia các cuộc gọi đã lên lịch cho Protected Audience (mỗi tuần thứ hai). Mọi người đều có thể tham gia—để tham gia, trước tiên, hãy đảm bảo tham gia WICG. Bạn có thể chủ động tham gia hoặc chỉ nghe nhạc!
Sử dụng biểu mẫu phản hồi Hộp cát về quyền riêng tư để chia sẻ phản hồi riêng tư với nhóm Chrome bên ngoài các diễn đàn công khai.

Yêu cầu hỗ trợ

Để đặt câu hỏi về cách triển khai của bạn, về bản minh hoạ hoặc về tài liệu:

Mở vấn đề mới trên kho lưu trữ privacy-sandbox-dev-support. Hãy nhớ chọn mẫu vấn đề cho Protected Audience.
Nêu vấn đề trong kho lưu trữ mã minh hoạ trên GitHub.
Để biết thêm câu hỏi chung về cách đáp ứng các trường hợp sử dụng của bạn với API, báo cáo vấn đề về kho lưu trữ đề xuất.

Đối với các lỗi và vấn đề khi triển khai Protected Audience API trong Chrome: * Xem các vấn đề hiện tại được báo cáo cho API. * Báo cáo vấn đề mới tại crbug.com/new.

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

Để được thông báo về những thay đổi trạng thái trong API, hãy tham gia danh sách gửi thư cho nhà phát triển.
Để theo dõi chặt chẽ tất cả cuộc thảo luận đang diễn ra về API, hãy nhấp vào nút Xem trên trang đề xuất trên GitHub. Để thực hiện việc này, bạn cần có hoặc tạo một kho lưu trữ GitHub tài khoản.
Để nhận thông tin cập nhật tổng thể về Hộp cát về quyền riêng tư, hãy đăng ký nhận nguồn cấp dữ liệu RSS [Tiến trình trong Chính sách quyền riêng tư Sandbox].

Tìm hiểu thêm

Protected Audience API: đề xuất ít thông tin kỹ thuật hơn.
Bản minh hoạ về Protected Audience: hướng dẫn từng bước triển khai Protected Audience cơ bản.
Video minh hoạ về Protected Audience: giải thích mã minh hoạ và cho biết cách sử dụng Công cụ của Chrome cho nhà phát triển để gỡ lỗi Protected Audience.
Thông báo giải thích về kỹ thuật về Protected Audience API
Tìm hiểu sâu hơn về Hộp cát về quyền riêng tư
Ý định tạo nguyên mẫu

Ảnh của Ray Hennessy trên Unsplash.