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

Hướng dẫn cho nhà phát triển API FLEDGE
bookmark_border Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.

Bài viết này dành cho ai?

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

Protected Audience API là một bản tổng quan ít kỹ thuật hơn về đề xuất này, đồng thời cũng có một bảng thuật ngữ.
Bản minh hoạ Protected Audience cung cấp hướng dẫn từng bước về cách triển khai FLEDGE cơ bản.
Video minh hoạ 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. API này được thiết kế để các bên thứ ba không thể sử dụng để 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 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 để 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à hướng dẫn 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

Chúng tôi đã cung cấp bản dùng thử theo nguyên gốc về Mức độ liên quan và Đo lường của Hộp cát về quyền riêng tư trong Chrome Beta 101.0.4951.26 trở lên trên máy tính cho các API Protected Audience, Topics và Attribution Reporting.

Để tham gia, hãy đăng ký mã dùng thử nguồn gốc.

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

Bản minh hoạ 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ã thông báo 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

Bằng cách 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ư lệnh gọi navigator.joinAdInterestGroup() của chủ sở hữu nhóm đối tượng có cùng mối quan tâm) sẽ cần cung cấp một mã thông báo khớp với nguồn gốc của iframe đó.

Thông tin chi tiết về bản dùng thử theo nguyên gốc đầu tiên của Protected Audience cung cấp thêm thông tin chi tiết về các 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ể thử nghiệm 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ả API Quyền riêng tư trong quảng cáo trong chrome://settings/adPrivacy
Bằng cách đặt cờ từ dòng lệ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.

Phần 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 khác dựa trên Chromium từ dòng lệnh. Bạn có thể xem danh sách đầy đủ các cờ Protected Audience trên Chromium Code Search.

Lưu ý: Đây là phiên bản Protected Audience đang trong quá trình phát triển để thử nghiệm sớm. Bạn không nên coi đây là bản hoàn chỉnh hoặc là chỉ báo cho quá trình triển khai cuối cùng. Tiến trình và trạng thái của Protected Audience được thảo luận trong các cuộc họp thường xuyên của WICG. Bản ghi biên bản của cuộc gọi WICG vào ngày 12 tháng 5 năm 2021 cung cấp thông tin chi tiết về những tính năng được hỗ trợ và không được hỗ trợ trong quá trình triển khai hiện tại. Dòng thời gian của Hộp cát về quyền riêng tư cung cấp thông tin về thời gian triển khai đối với Đối tượng được bảo vệ và các đề xuất khác trong Hộp cát về quyền riêng tư.

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

Protected Audience đang được cung cấp dưới dạng cờ tính năng trong Chromium dưới dạng thử nghiệm đầu tiên để kiểm thử các tính năng sau của đề xuất Protected Audience:

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.

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

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

Chế độ mặc định trong quá trình 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ừ 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 điều chỉnh chính sách về quyền đối với 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, như nội dung giải thích mô tả.

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

Trong phiên đấu giá quảng cáo Protected Audience, trình duyệt có thể truy cập vào một 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 còn lại. Đề xuất về Protected Audience yêu cầu máy chủ này "không thực hiện hoạt động ghi nhật ký ở cấp sự kiện và không có tác dụng phụ nào khác dựa trên những yêu cầu này".

Mã dịch vụ Khoá/Giá trị của Đối tượng được bảo vệ hiện có trong kho lưu trữ GitHub về Hộp cát về quyền riêng tư. Nhà phát triển Chrome và Android có thể sử dụng dịch vụ này. 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. 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.

Để kiểm thử ban đầu, mô hình "Tự cung cấp máy chủ" được sử dụng. Về lâu dài, công nghệ quảng cáo sẽ cần sử dụng các dịch vụ Khoá/Giá trị 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.

Để đảm bảo hệ sinh thái có đủ thời gian thử nghiệm, chúng tôi không yêu cầu sử dụng các dịch vụ Khoá/Giá trị nguồn mở hoặc TEE cho đến một thời điểm nào đó sau khi cookie của bên thứ ba ngừng hoạt động. Chúng tôi sẽ thông báo đầy đủ để 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 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');

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 khi là chủ sở hữu trang web hoặc người dùng cá nhân.

Làm cách nào để các trang web kiểm soát quyền truy cập?

Cuối cùng, 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 sẽ giúp đảm bảo rằng các bên thứ ba tuỳ ý không thể sử dụng API mà không có thông tin của trang web. Tuy nhiên, để tạo điều kiện cho việc kiểm thử trong bản dùng thử theo nguyên gốc đầu tiên, yêu cầu này sẽ bị miễn theo mặc định. Những trang web muốn tắt rõ ràng chức năng Protected Audience trong thời gian thử nghiệm có thể sử dụng Chính sách quyền liên quan để chặn quyền truy cập.

Bạn có thể thiết lập độc lập 2 chính sách về quyền trong Protected Audience:

join-ad-interest-group bật/tắt chức năng thêm 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 ngữ cảnh của bên thứ nhất bằng cách chỉ định chính sách quyền sau đây trong tiêu đề phản hồi HTTP:

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

Bạn có thể tắt chế độ sử dụng các API trong một iframe bằng cách thêm thuộc tính allow sau vào 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 về quyền trong bản dùng thử theo nguyên gốc đầu tiên của Protected Audience sẽ cung cấp thêm thông tin chi tiết.

Người dùng chọn không sử dụng

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ơ chế nào sau đây:

Tắt chế độ 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 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" trong chrome://settings/cookies.
Sử dụng Chế độ ẩn danh.

Tài liệu giải thích về Protected Audience cung cấp thông tin chi tiết hơn về các thành phần thiết kế API và mô tả cách API tìm cách đáp ứng các mục tiêu về quyền riêng tư.

Gỡ lỗi các worklet Protected Audience

Kể từ Chrome Canary 98.0.4718.0, bạn có thể gỡ lỗi các công cụ của Protected Audience trong Chrome DevTools.

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

Ảnh chụp màn hình DevTools trong Chrome Canary, làm nổi bật ngăn Điểm ngắt của trình nghe sự kiện trong bảng điều khiển Nguồn.
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 một điểm ngắt kích hoạt, quá trình thực thi sẽ tạm dừng trước câu lệnh đầu tiên ở cấp cao nhất của 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 bước để chuyển đến chính hàm đặt giá thầu/đánh giá/báo cáo.

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

Ảnh chụp màn hình DevTools trong Chrome Canary, làm nổi bật ngăn Luồng trong bảng điều khiển Nguồn, cho thấy tập lệnh worklet hiện tại đã bị tạm dừng.

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

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

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

Nếu bạn truy cập vào trang web mua sắm minh hoạ Protected Audience trong một trình duyệt đã bật Protected Audience, thì DevTools sẽ hiển thị thông tin về sự kiện join.

Bảng điều khiển Ứng dụng DevTools trong Chrome Canary, hiển thị thông tin về sự kiện tham gia nhóm quan tâm Protected Audience.

Giờ đây, nếu bạn truy cập vào trang web của nhà xuất bản minh hoạ Protected Audience trong một trình duyệt đã bật Protected Audience, thì DevTools sẽ hiển thị thông tin về các sự kiện bid và win.

Bảng điều khiển Ứng dụng DevTools trong Chrome Canary, hiển thị thông tin về giá thầu phiên đấu giá Protected Audience và các sự kiện thắng.

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ả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 Protected Audience API hiện đang được thử nghiệm trong Chrome. Bài viết Kiểm thử bằng cờ tính năng giải thích những tính năng Protected Audience hiện có để kiểm thử trong Chrome chạy từ dòng lệnh bằng cờ tính năng. Chúng tôi dự kiến sẽ bổ sung các tính năng của Protected Audience theo thời gian khi quá trình triển khai tiếp tục diễn ra. Khi API đạt đến giai đoạn thử nghiệm gốc, chúng tôi sẽ cung cấp danh sách thường xuyên cập nhật về những phần đã được triển khai và những phần vẫn đang trong quá trình triển khai.

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

Hình minh hoạ một người đang 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 (nhà quảng cáo trong ví dụ này) và dành thời gian trên trang sản phẩm của một chiếc xe đạp thép làm 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.

Từ khoá chính: 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á việc mua quảng cáo. Nhà quảng cáo sử dụng DSP để mua lượt hiển thị quảng cáo trên một 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 các trang web thương mại được gọi là sàn giao dịch quảng cáo. DSP quyết định theo phương thức lập trình về lượt hiển thị quảng cáo nào hiện có phù hợp nhất để nhà quảng cáo 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 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 (hình chữ nhật trống nơi quảng cáo sẽ xuất hiện) cho nhiều sàn giao dịch quảng cáo, DSP và mạng. Điều này giúp nhiều bên 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 một nhóm mối quan tâm

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

Phần giải thích: Trình duyệt ghi lại các nhóm đối tượng có cùng mối quan tâm

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à một người mua trong phiên đấu giá quảng cáo được mô tả trong bước 4. Trình duyệt lưu trữ thông tin về nhóm 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.

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

joinAdInterestGroup() yêu cầu quyền của:

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

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

Quyền của trang web đang được truy cập

Cùng nguồn gốc: Theo mặc định, quyền được cấp ngầm cho các lệnh gọi joinAdInterestGroup() từ cùng một nguồn gốc với trang web đang được truy cập, tức là từ cùng một 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 lệnh join-ad-interest-group tiêu đề chính sách về quyền của Protected Audience để tắt các lệnh gọi joinAdInterestGroup().

Nhiều nguồn gốc: Việc gọi joinAdInterestGroup() từ các nguồn gốc khác với trang 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 các lệnh gọi đến joinAdInterestGroup() từ các iframe nhiều nguồn gốc.

Lưu ý: Chế độ mặc định trong quá trình 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 trang, ngay cả từ các iframe có nguồn gốc khác. Trong tương lai, sau khi chủ sở hữu trang web có thời gian điều chỉnh chính sách về quyền, theo mặc định, chúng tôi sẽ không cho phép các lệnh gọi từ iframe trên nhiều nguồn gốc, như mô tả trong phần giải thích về Protected Audience.

Quyền của chủ sở hữu nhóm theo mối quan tâm

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

Đề 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 cách sử dụng danh sách tại URL .well-known.

Sử dụng navigator.joinAdInterestGroup()

Sau đây là ví dụ về cách sử dụng API:

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 đến hàm phải có kích thước không quá 50 kiB, nếu không, lệnh gọi sẽ không thành công. 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 liên tiếp sẽ ghi đè các giá trị đã lưu trước đó.

Điểm chính: Tất cả URL dùng làm tham số cho các phương thức Protected Audience API phải đến từ các nguồn gốc bảo mật: tất cả tài nguyên phải được phân phát qua URL HTTPS. Bài viết 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 tiêu đề phản hồi HTTP X-Allow-FLEDGE: true.

Thuộc tính nhóm đối tượng có cùng 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 đối tượng có cùng 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 cho JavaScript đặt giá thầu chạy trong worklet.
`biddingWasmHelperUrl`**	Không bắt buộc*	`'https://dsp.example/bid/custom-bikes/bid.wasm'`	URL cho mã WebAssembly được điều khiển 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 của nhóm mối quan tâm. (Xem phần 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ị đế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 đến máy chủ đáng tin cậy dạng khoá-giá trị.
`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 quá trình đặt giá thầu.
`ads`	Không bắt buộc*	`[bikeAd1, bikeAd2, bikeAd3]`	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ả thuộc tính đều không bắt buộc, ngoại trừ owner và name. Các thuộc tính biddingLogicUrl và ads là không bắt buộc, nhưng cần thiết để tham gia phiên đấu giá. Có thể có các trường hợp sử dụng để tạo nhóm mối quan tâm 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 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ố trường hợp sử dụng khác trong tương lai, hoặc họ có thể tạm thời hết ngân sách quảng cáo.

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

Cập nhật các thuộc tính của 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(). Điều này cung cấp một cơ chế để chủ sở hữu của nhóm cập nhật định kỳ các thuộc tính của nhóm mối quan tâm. Trong quy trình 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 được cập nhật – trong khi việc gọi navigator.joinAdInterestGroup() sẽ ghi đè mọi nhóm mối quan tâm hiện có.

Chúng tôi sẽ cố gắng hết sức để cập nhật và có thể không thành công trong các điều kiện sau:

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

Các bản cập nhật cũng có thể bị huỷ nếu đã mất quá nhiều thời gian liên tục để cập nhật, mặc dù điều này không áp dụng bất kỳ giới hạn tốc độ nào đối với các bản cập nhật bị huỷ (còn lại). Số lần cập nhật được giới hạn ở mức tối đa là một lần mỗi ngày. Các 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 mất kết nối Internet sẽ được thử lại ngay khi kết nối lại.

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 cho các nhóm mối quan tâm thuộc sở hữu của nguồn gốc khung hiện tại theo cách thủ công thông qua navigator.updateAdInterestGroups(). Giới hạn tốc độ giúp ngăn việc cập nhật quá thường xuyên: các lệnh gọi lặp lại đến navigator.updateAdInterestGroups() sẽ không thực hiện bất kỳ thao tác nào cho đến khi hết khoảng thời gian giới hạn tốc độ (hiện là một ngày). Giới hạn tốc độ 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á sẽ tự động được cập nhật sau khi phiên đấu giá kết thúc, đồng thời tuân theo các giới hạn tốc độ tương tự như khi cập nhật thủ công. Đối với mỗi chủ sở hữu có ít nhất một nhóm mối quan tâm tham gia phiên đấu giá, 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 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à (không bắt buộc) siêu dữ liệu tuỳ ý 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?

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 một hàm generateBid(). Khi người bán không gian quảng cáo gọi navigator.runAdAuction(), hàm generatedBid() sẽ được gọi một lần 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. Nói cách khác, generateBid() được gọi một lần cho mỗi quảng cáo đề xuất. Người bán cung cấp thuộc tính decisionLogicUrl trên tham số cấu hình phiên đấu giá được truyền vào navigator.runAdAuction(). Mã tại URL này phải bao gồm một hàm scoreAd(). Hàm này sẽ chạy cho mỗi bên đặt giá thầu trong phiên đấu giá để tính điểm cho 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 tốn kém về mặt tính toán trong WebAssembly, thay vì JavaScript, được điều khiển từ hàm JavaScript do biddingLogicUrl cung cấp. Nếu được cung cấp, tệp này phải trỏ đến tệp nhị phân WebAssembly, được phân phối bằng application/wasm mimetype. Trình duyệt cung cấp WebAssembly.Module tương ứng 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 liên quan, sau đó chỉ định cho quảng cáo một điểm số về mức độ 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 do người mua quảng cáo truyền đến joinAdInterestGroup(). (Nhóm mối quan tâm có thể được cập nhật thông qua dailyUpdateUrl.)
auctionSignals
Một thuộc tính của đối số cấu hình phiên đấu giá được người bán không gian quảng cáo truyền vào navigator.runAdAuction(). Thông tin này cung cấp thông tin về ngữ cảnh trang (chẳng hạn như kích thước quảng cáo và mã nhận dạng 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 khác.
perBuyerSignals
Giống như auctionSignals, một thuộc tính của đối số cấu hình phiên đấu giá do người bán truyền đến navigator.runAdAuction(). Điều này có thể cung cấp các tín hiệu theo bối cảnh từ máy chủ của người mua về trang, nếu người bán là một 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 phản hồi trở lại, hoặc nếu trang của 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 chữ ký mã hoá của các tín hiệu đó bên trong generateBid() để bảo vệ khỏi hành vi can thiệp.
trustedBiddingSignals
Một đối tượng có khoá là trustedBiddingSignalsKeys cho nhóm mối quan tâm và có giá trị được trả về trong yêu cầu trustedBiddingSignals.
browserSignals
Một đối tượng do trình duyệt tạo ra, có thể bao gồm thông tin về ngữ cảnh trang (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 mối quan tâm (chẳng hạn như bản ghi về thời điểm nhóm từng thắng phiên đấu giá trước đó, để 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 tham số của hàm. 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 hoặc mẫu quảng cáo này. Người bán sử dụng thông tin này trong phiên đấu giá và mẫu quảng cáo quyết định. Người bán sử dụng thông tin này trong phiên đấu giá và logic đưa ra quyết định.
bid
Giá thầu dạng số sẽ tham gia phiên đấu giá. Người bán phải có thể so sánh giá thầu của nhiều người mua, do đó, giá thầu phải được tính theo một đơn vị do người bán chọn (ví dụ: "USD/1.000"). Nếu giá thầu bằng 0 hoặc âm, thì nhóm mối quan tâm này sẽ không tham gia phiên đấu giá của người bán. Với cơ chế này, bên mua có thể triển khai mọi quy tắc của nhà quảng cáo về vị trí quảng cáo có thể xuất hiện hoặc không xuất hiện.
render
Một 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 phần Quảng cáo bao gồm nhiều phần trong phần giải thích về API.) Giá trị này phải khớp với renderUrl của một trong các quảng cáo được xác định cho nhóm 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, 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 một 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. Nói cách khác, trình duyệt được yêu cầu xoá nhóm mối quan tâm khỏi danh sách các nhóm 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 một 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 mối quan tâm đó. Mã cho 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 một trang web bán không gian quảng cáo

Hình minh hoạ một người đang 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 mà trang web này bán theo phương thức lập trình bằng cách sử dụng cơ chế đặ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: một trang web trả tiền để quảng cáo sản phẩm của mình. Trong ví dụ này, một nhà sản xuất xe đạp tuỳ chỉnh. * Nhà xuất bản: các 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 các ví dụ tại đây. Nhiều (nhưng không phải tất cả) trang web bán không gian quảng cáo đều 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 (ở bước tiếp theo). Hầu hết các nhà xuất bản đều sử dụng một dịch vụ 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. Phiên đấu giá quảng cáo được chạy trong trình duyệt

Hình minh hoạ một người đang xem 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.

Mục giải thích: Người bán chạy 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 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á này 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 của 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 gửi yêu cầu đến 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ả phiên đấu giá quảng cáo. Trình duyệt chỉ có thể giải mã thông tin này khi được chuyển đến một khung có hàng rào để hiển thị: trang của nhà xuất bản không thể kiểm tra quảng cáo 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 nguồn gốc của chủ sở hữu nhóm mối quan tâm, vì vậy, joinAdInterestGroup() cần được gọi từ một iframe (ví dụ: 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 hiện tại (ví dụ: một trang web có các nhóm mối quan tâm riêng). runAdAuction không có các yêu cầu tương tự, vì vậy, việc gọi runAdAuction() từ thẻ <script> có thể hiệu quả hơn nhiều so với iframe 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 và siêu dữ liệu liên quan, sau đó chỉ định cho quảng cáo đó một điểm số mong muốn dạng số.

`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 của người bán.
`decisionLogicUrl`	Bắt buộc	`'https://ssp.example/auction-decision-logic.js'`	URL 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ả chủ sở hữu nhóm mối quan tâm được 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ề ngữ cảnh 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 tạo 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 theo 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 (ms) của tập lệnh `generateBid()` của một 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 sẽ được chấp nhận hoặc từ chối dựa trên các tiêu chí khác ngoài việc có chủ sở hữu nhóm đối tượng có cùng mối quan tâm hay không. Ví dụ: người bán có thể xem xét mẫu quảng cáo để xác nhận việc tuân thủ chính sách của họ.

** additionalBids không được hỗ trợ trong cách triển khai Protected Audience hiện tại. Đọc phần Thành phần tham gia phiên đấu giá trong nội dung 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 (một thuộc tính của đối tượng cấu hình phiên đấu giá được truyền đến runAdAuction()) phải bao gồm một hàm scoreAd(). Quy trình 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 quảng cáo.

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 dạ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
Một đố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á 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 sẽ tìm quảng cáo theo bối cảnh phù hợp nhất cho vị trí quảng cáo có sẵn. Một phần của logic scoreAd() 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 được dữ liệu theo thời gian thực từ dịch vụ Khoá/Giá trị

Mục 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 đến 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 truyền đến navigator.runAdAuction(), 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 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 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á.

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ùng nguồn gốc với chủ sở hữu nhóm mối quan tâm: xem Thuộc tính nhóm mối quan tâm và Tự cung cấp máy chủ.

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

Hình minh hoạ một người đang 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 xe đạp (giảm giá 20%) sẽ xuất hiện, cùng với một ổ khoá ở phía trên để cho biết quảng cáo này xuất hiện trong một khung được bảo vệ.

Mục giải thích: Trình duyệt hiển thị quảng cáo chiến thắng

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

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

Mục 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 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 thắng thầu 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 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.

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

Phần giải thích: Báo cáo của người bán về lượt 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ể bao gồ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 vào hàm này là:

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

browserSignals
Một đối tượng do trình duyệt tạo ra, 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 hàm reportWin() của bên đặt giá thầu thắng thầu.

Bên đặt giá thầu giành chiến thắng báo cáo kết quả

Phần giải thích: Báo cáo của người mua về sự kiện hiển thị và sự kiện quảng cáo

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

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

Lưu ý: Việc triển khai Protected Audience hiện tại trong Chrome sẽ cảnh báo nếu reportWin() không được xác định.

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

auctionSignals và perBuyerSignals
Các giá trị tương tự được truyề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
Một đối tượng do trình duyệt tạo ra, 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 tạm thời tính năng báo cáo thắng/thua

Hiện tại, Chrome tạm thời có hai phương thức báo cáo phiên đấu giá:

forDebuggingOnly.reportAdAuctionLoss()
forDebuggingOnly.reportAdAuctionWin()

Mỗi phương thức này nhận một đối số duy nhất: một URL để tìm nạp sau khi phiên đấu giá kết thúc. Bạn có thể gọi các hàm này 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 về chiến thắng/thua khi một phiên đấu giá chạy đến khi hoàn tất. Nếu một phiên đấu giá bị huỷ (ví dụ: do một thao tác điều hướng mới), thì hệ thống sẽ không tạo báo cáo nào.

Các 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ư của quảng cáo trong chrome://settings/adPrivacy. Nếu đang chạy Chrome bằng cờ dòng lệnh để bật Protected Audience, bạn cần bật rõ ràng các phương thức bằng cách thêm cờ BiddingAndScoringDebugReportingAPI. Nếu bạn không bật cờ này, các phương thức vẫn sẽ có sẵn nhưng không làm gì cả.

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

Hình minh hoạ một người nhấp vào quảng cáo xe đạp, bên trong một khung được khoanh tròn, trên trang web tin tức, với 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 trong khung hình được khoanh vùng.

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

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

Protected Audience và TURTLEDOVE khác nhau như thế nào?

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 một người có thể 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 người dùng 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 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ột 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 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 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 vào 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 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 để 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 chưa ngăn được 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ó cấu hình trình duyệt nào không?

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 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 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à 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 khi đề xuất về Protected Audience được triển khai, dựa trên các 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ý Đối tượng được bảo vệ 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ọ.

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

GitHub: Đọc đề xuất, đặt câu hỏi và theo dõi cuộc thảo luận.
W3C: Thảo luận về các trường hợp sử dụng trong ngành trong Nhóm cải thiện hoạt động kinh doanh quảng cáo trên web.
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 cung cấp thông báo và thông tin cập nhật về API.
Tham gia các cuộc gọi theo 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 nhớ tham gia WICG. Bạn có thể tích cực tham gia hoặc chỉ nghe!
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.

Yêu cầu hỗ trợ

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

Mở một 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.
Đăng vấn đề trên kho lưu trữ mã minh hoạ trên GitHub.
Để biết thêm câu hỏi chung về cách đáp ứng trường hợp sử dụng của bạn bằng API, hãy gửi vấn đề trên kho lưu trữ đề xuất.

Đối với lỗi và vấn đề khi triển khai Protected Audience API trong Chrome: * Xem các vấn đề hiện có đượ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ề 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.
Để theo dõi chặt chẽ tất cả các cuộc thảo luận đang diễn ra về API này, hãy nhấp vào nút Watch (Xem) trên trang đề xuất trên GitHub. Để làm việc này, bạn cần có hoặc tạo tài khoản GitHub.
Để 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ý nguồn cấp dữ liệu RSS [Tiến trình trong Hộp cát về quyền riêng tư].

Tìm hiểu thêm

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

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

Hướng dẫn cho nhà phát triển API FLEDGE bookmark_borderbookmark Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.

Bài viết này dành cho ai?

Protected Audience là gì?

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

Bản minh hoạ Protected Audience

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

Kiểm thử API này

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

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

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

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

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

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

Làm cách nào để các trang web kiểm soát quyền truy cập?

Người dùng chọn không sử dụng

Gỡ lỗi các worklet Protected Audience

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

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

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

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

Quyền của trang web đang được truy cập

Quyền của chủ sở hữu nhóm theo mối quan tâm

Sử dụng navigator.joinAdInterestGroup()

Thuộc tính nhóm đối tượng có cùng mối quan tâm

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

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

Tự động cập nhật

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

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

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

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

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

auctionConfig cơ sở lưu trú

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

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

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

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

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

Bên đặt giá thầu giành chiến thắng báo cáo kết quả

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

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

Protected Audience và TURTLEDOVE khác nhau như thế nào?

Có cấu hình trình duyệt nào không?

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

Yêu cầu hỗ trợ

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

Tìm hiểu thêm

Hướng dẫn cho nhà phát triển API FLEDGE
bookmark_border Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.

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