Thiết lập phiên đấu giá quảng cáo trên trang của nhà xuất bản

Tìm hiểu cách định cấu hình phiên đấu giá Protected Audience API.

Phiên đấu giá trên thiết bị do người bán chạy

Phiên đấu giá Protected Audience trên thiết bị chạy trên một trang web bán khoảng không quảng cáo và chúng tôi gọi bên chạy phiên đấu giá là người bán. Nhiều bên có thể đóng vai trò là người bán: một trang web có thể chạy phiên đấu giá quảng cáo của riêng mình, hoặc có thể bao gồm một tập lệnh của bên thứ ba để chạy phiên đấu giá cho trang web đó, hoặc có thể sử dụng một SSP kết hợp việc chạy phiên đấu giá trên thiết bị với các hoạt động đấu giá quảng cáo khác phía máy chủ. Người bán có 3 công việc cơ bản trong phiên đấu giá quảng cáo trên thiết bị:

Người bán quyết định (a) người mua nào có thể tham gia và (b) giá thầu nào trong số các giá thầu từ nhóm đối tượng có cùng mối quan tâm của những người mua đó đủ điều kiện tham gia phiên đấu giá. Điều này cho phép người bán thực thi các quy tắc của trang web về những quảng cáo được phép xuất hiện trên trang.
Người bán chịu trách nhiệm về logic kinh doanh của phiên đấu giá: Mã JavaScript xem xét giá và siêu dữ liệu của từng giá thầu, đồng thời tính toán điểm "mức độ phù hợp". Giá thầu có điểm số về mức độ mong muốn cao nhất sẽ giành chiến thắng trong phiên đấu giá.
Người bán báo cáo về kết quả đấu giá, bao gồm cả thông tin về giá thanh toán và mọi khoản thanh toán khác. Người mua thắng và thua cũng có thể tự báo cáo.

Tài liệu này sẽ giải thích cách định cấu hình và bắt đầu một phiên đấu giá trên thiết bị.

Định cấu hình phiên đấu giá quảng cáo Protected Audience API

Để chạy phiên đấu giá quảng cáo Protected Audience API, bước đầu tiên là định cấu hình phiên đấu giá. Bạn có thể thực hiện việc này bằng cách tạo một đối tượng auctionConfig. Dưới đây là ví dụ về một cấu hình như vậy:

const auctionConfig = {
  seller: 'https://seller.example',
  decisionLogicUrl: ...,
  trustedScoringSignalsUrl: ...,
  interestGroupBuyers: ['https://buyer-1.example', 'https://buyer-2.example', ...],
  auctionSignals: {...},
  sellerSignals: {...},
  sellerTimeout: 100,
  perBuyerSignals: {
    'https://buyer-1.example': {...},
    'https://buyer-2.example': {...},
    ...
  },
  perBuyerTimeouts: {
    'https://buyer-1.example': 50,
    'https://buyer-2.example': 200,
    '*': 150,
    ...
  },
  componentAuctions: [
    {
      'seller': 'https://component-seller.example',
      'decisionLogicUrl': ...,
      ...
    },
    ...
  ],
  resolveToConfig: [true|false],
};

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

Thuộc tính bắt buộc

Các thuộc tính bắt buộc duy nhất đối với auctionConfigs là seller, decisionLogicUrl và interestGroupBuyers.

Thuộc tính	Ví dụ:	Vai trò
người bán	https://seller.example	Quốc gia của người bán.
decisionLogicUrl	https://seller.example/decision-logic.js	URL cho worklet logic quyết định JavaScript của phiên đấu giá. Trường này cần có cùng nguồn gốc với trường người bán.
interestGroupBuyers	[https://buyer-1.example, https://buyer-2.example, ...]	Nguồn gốc của tất cả chủ sở hữu nhóm đối tượng có cùng mối quan tâm được yêu cầu đặt giá thầu trong phiên đấu giá

Thuộc tính tuỳ chọn

Các thuộc tính còn lại cho auctionConfigs là không bắt buộc.

Thuộc tính	Ví dụ:	Vai trò
trustedScoringSignalsUrl	https://seller.example/scoring-signals	URL của máy chủ khoá/giá trị của người bán. Tham số này sẽ được truy vấn trong quá trình tính điểm quảng cáo bằng cách sử dụng URL hiển thị của mẫu quảng cáo làm khoá. Trường này cần có cùng nguồn gốc với trường người bán.
auctionSignals	{"category":"news"}	Đối tượng có thể chuyển đổi tuần tự JSON đại diện cho các tín hiệu mà tất cả người mua và người bán tham gia phiên đấu giá đều có thể sử dụng.
sellerSignals	{...}	Đối tượng có thể chuyển đổi tuần tự JSON đại diện cho các tín hiệu chỉ có sẵn cho người bán.
perBuyerSignals	{https://dsp.example: {...}, https://another-buyer.example: {...}, ... }	Các tín hiệu có sẵn cho một người mua cụ thể. Các tín hiệu này có thể đến từ người bán và cả người mua.
perBuyerTimeouts	{https://www.example-dsp.com: 50, https://www.another-buyer.com: 200, *: 150, ...},	Thời gian chạy tối đa (tính bằng mili giây) của tập lệnh generateBid() của một người mua cụ thể. Ký tự đại diện sẽ được áp dụng cho mọi người mua không có thời gian chờ cụ thể được xác định.
sellerTimeout	100	Thời gian chạy tối đa (tính bằng mili giây) của tập lệnh scoreAd() của người bán.
componentAuctions	[{seller: https://www.some-other-ssp.com, decisionLogicUrl: ..., ...}, ...]	Các cấu hình bổ sung cho phiên đấu giá thành phần.
resolveToConfig	true\|false	Một giá trị boolean hướng dẫn lời hứa được trả về từ runAdAuction() để phân giải thành FencedFrameConfig nếu đúng (để sử dụng trong <fencedframe>), hoặc thành một URL urn:uuid mờ nếu sai (để sử dụng trong <iframe>). Giá trị mặc định là false.

Cung cấp tín hiệu không đồng bộ

Bạn có thể cung cấp giá trị của một số tín hiệu (những tín hiệu được định cấu hình bằng các trường auctionSignals, sellerSignals, perBuyerSignals và perBuyerTimeouts) không phải là giá trị cụ thể mà là Promise (không bắt buộc). Điều này cho phép một số phần của phiên đấu giá, chẳng hạn như tải tập lệnh và tín hiệu đáng tin cậy, cũng như khởi chạy các quy trình worklet riêng biệt, để chồng chéo quá trình tính toán (hoặc truy xuất mạng) của các giá trị đó. Các tập lệnh worklet sẽ chỉ thấy các giá trị đã phân giải; nếu bất kỳ Lời hứa nào như vậy bị từ chối, thì phiên đấu giá sẽ bị huỷ bỏ, trừ phi phiên đấu giá đó đã thất bại hoặc bị huỷ bỏ theo cách khác.

Định cấu hình phiên đấu giá có nhiều người bán

Trong một số trường hợp, nhiều người bán có thể muốn tham gia một phiên đấu giá, trong đó người chiến thắng của các phiên đấu giá riêng biệt sẽ được chuyển lên một phiên đấu giá khác do một người bán khác điều hành. Những phiên đấu giá riêng biệt được chuyển lên này được gọi là phiên đấu giá thành phần. Để tạo điều kiện thuận lợi cho các phiên đấu giá thành phần này, đối tượng componentAuctions có thể chứa các cấu hình đấu giá bổ sung cho phiên đấu giá thành phần của mỗi người bán. Giá thầu chiến thắng của mỗi phiên đấu giá thành phần này sẽ được chuyển đến phiên đấu giá "cấp cao nhất" để đưa ra quyết định cuối cùng về phiên đấu giá. auctionConfig của các phiên đấu giá thành phần có thể không có componentAuctions riêng. Khi componentAuctions không trống, interestGroupBuyers phải trống. Tức là đối với bất kỳ phiên đấu giá Protected Audience nào, sẽ có một người bán duy nhất và không có phiên đấu giá thành phần, hoặc tất cả giá thầu đều đến từ các phiên đấu giá thành phần và phiên đấu giá cấp cao nhất chỉ có thể chọn trong số những người chiến thắng của các phiên đấu giá thành phần.

Chạy phiên đấu giá

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

try {
  const auctionResultPromise = navigator.runAdAuction(auctionConfig);
} catch (error) {
  // Handle error.
}

Lệnh gọi runAdAuction() trả về một Promise phân giải thành quảng cáo. Không có mã nào trên trang của nhà xuất bản có thể kiểm tra quảng cáo chiến thắng hoặc tìm hiểu nội dung của quảng cáo đó từ kết quả của runAdAuction(). Nếu cờ resolveToConfig được đặt thành true trong AuctionConfig, thì một đối tượng FencedFrameConfig sẽ được trả về và chỉ có thể hiển thị trong một khung được phân vùng. Nếu cờ được đặt thành false, thì một URN mờ sẽ được trả về và có thể hiển thị trong iframe. Có thể runAdAuction trả về giá trị rỗng, cho biết không có quảng cáo nào được chọn. Trong trường hợp này, người bán có thể chọn hiển thị một quảng cáo được nhắm mục tiêu theo ngữ cảnh.