Chạy phiên đấu giá dựa trên trình duyệt với một người bán duy nhất

Trong tài liệu này, bạn sẽ thấy thông tin tổng quan cấp cao về cách chạy phiên đấu giá với dữ liệu Protected Audience cho một người bán, như được sử dụng trong vòng lặp hiện tại của Protected Audience API. Phiên đấu giá có một người bán có thể được thực thi trong một phiên đấu giá phức tạp hơn có nhiều người bán tham gia. Trong trường hợp này, phiên đấu giá duy nhất của người bán được gọi là "phiên đấu giá thành phần", có thể cung cấp các đề xuất quảng cáo cho "phiên đấu giá cấp cao nhất" có nhiều người bán tham gia.

Đọc hướng dẫn cho nhà phát triển để biết toàn bộ vòng đời của Protected Audience API và tham khảo tài liệu giải thích về Protected Audience API để thảo luận chi tiết về cách người bán chạy các phiên đấu giá trên thiết bị.

6 giai đoạn của một phiên đấu giá quảng cáo Protected Audience API

6 giai đoạn trong một phiên đấu giá quảng cáo bằng Protected Audience API
Sơ đồ này trình bày từng giai đoạn của phiên đấu giá quảng cáo Protected Audience API.
  1. Người dùng truy cập vào trang web hiển thị quảng cáo.
  2. Mã của người bán thực thi navigator.runAdAuction(). Điều này xác định không gian quảng cáo nào cần bán và ai có thể đặt giá thầu. Người bán cũng phải bao gồm một tập lệnh để tính điểm cho mỗi giá thầu, scoreAd().
  3. Mã của người mua được mời sẽ thực thi để tạo giá thầu, URL cho mẫu quảng cáo phù hợp và các dữ liệu khác. Tập lệnh đặt giá thầu có thể truy vấn dữ liệu theo thời gian thực, chẳng hạn như ngân sách còn lại của chiến dịch quảng cáo, từ dịch vụ Khoá/Giá trị của người mua.
  4. Mã của người bán tính điểm cho từng giá thầu và chọn giá thầu chiến thắng. Logic này sử dụng giá trị giá thầu và các dữ liệu khác trả về mức độ mong muốn của giá thầu. Quảng cáo không thể đánh bại quảng cáo giành chiến thắng theo ngữ cảnh sẽ bị từ chối. Người bán có thể sử dụng dịch vụ Khoá/Giá trị của riêng mình cho dữ liệu theo thời gian thực.
  5. Quảng cáo chiến thắng được trả về dưới dạng một giá trị không rõ ràng, hiển thị trong một khung được bảo vệ. Cả người bán và nhà xuất bản sẽ không thể xem giá trị này.
  6. Phiên đấu giá được báo cáo cho người bán và người mua giành chiến thắng.

Phiên đấu giá có thể diễn ra khi người dùng chuyển đến một trang hiển thị quảng cáo. Phiên đấu giá có thể được chạy trước để mẫu quảng cáo sẵn sàng khi vùng quảng cáo xuất hiện.

Người bán khởi tạo phiên đấu giá quảng cáo, tính điểm quảng cáo đề xuất bằng cách sử dụng logic tuỳ chỉnh được cung cấp dưới dạng hàm scoreAd() và chịu trách nhiệm báo cáo kết quả của phiên đấu giá cho chính họ cũng như người mua giành chiến thắng. Người bán cũng có thể thực thi các quy tắc của nhà xuất bản và lọc chất lượng quảng cáo bằng cách sử dụng hàm scoreAd().

Người bán có thể đề cập đến:

  • Nhà xuất bản nội dung tự lưu trữ nội dung quảng cáo trên trang web của mình
  • Nền tảng bên cung (SSP), làm việc với nhà xuất bản quảng cáo và cung cấp các dịch vụ khác
  • Tập lệnh của bên thứ ba, thay mặt nhà xuất bản tham gia vào phiên đấu giá quảng cáo.

Điều kiện tiên quyết để chạy phiên đấu giá

Người bán cần hai hàm JavaScript được xác định để chạy phiên đấu giá:

  • scoreAd(), sẽ tính điểm đề xuất quảng cáo
  • reportResult(), giúp xử lý việc báo cáo kết quả của phiên đấu giá cho người bán

Các tập lệnh này cần được phân phát từ một điểm cuối duy nhất mà người bán sở hữu.

scoreAd()

Người bán cần xác định hàm scoreAd() được phân phát từ điểm cuối mà họ sở hữu. Điểm cuối được chỉ định trong cấu hình phiên đấu giá là decisionLogicUrl. Hàm scoreAd() có chữ ký sau:

scoreAd(
  adMetadata,
  bid,
  auctionConfig,
  trustedScoringSignals,
  browserSignals,
  directFromSellerSignals)

Các tham số scoreAd() bao gồm:

  • adMetaData là siêu dữ liệu tuỳ ý về mẫu quảng cáo do người mua cung cấp. Đây là một đối tượng có thể chuyển đổi tuần tự JSON mà người bán và người mua sẽ cần xác định và thống nhất về cấu trúc.
  • bid, là một giá trị bằng số đại diện cho giá thầu.
  • auctionConfig, là cấu hình đấu giá được dùng để thực thi phiên đấu giá.
  • trustedScoringSignals là các tín hiệu được đọc tại thời điểm đấu giá từ máy chủ Khoá/Giá trị của người bán. Nền tảng này sẽ sử dụng renderUrl của quảng cáo đề xuất làm khoá cho nội dung tra cứu này.
  • browserSignals là 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 phiên đấu giá của người bán có thể muốn xác minh.
  • directFromSellerSignals là một đối tượng có thể chứa các trường sau: ** sellerSignals: Giống như auctionConfig.sellerSignals, nhưng được truyền bằng cơ chế directFromSellerSignals. ** auctionSignals: Giống như auctionConfig.auctionSignals nhưng được truyền bằng cơ chế directFromSellerSignals.

Sau đây là ví dụ về browserSignals. Xin lưu ý rằng renderUrl của quảng cáo đề xuất có sẵn thông qua các tín hiệu sau:

{ 'topWindowHostname': 'www.example-publisher.com',
  'interestGroupOwner': 'https://www.example-buyer.com',
  'renderURL': 'https://cdn.com/render_url_of_bid',
  'renderSize': {width: 100, height: 200}, /* if specified in the bid */
  'adComponents': ['https://cdn.com/ad_component_of_bid',
                   'https://cdn.com/next_ad_component_of_bid',
                   ...],
  'biddingDurationMsec': 12,
  'bidCurrency': 'USD', /* bidCurrency returned by generateBid, or '???' if none */
  'dataVersion': 1, /* Data-Version value from the trusted scoring signals server's response */
}

reportResult()

Người bán cần xác định một hàm reportResult() được phân phát từ một điểm cuối mà họ sở hữu. Điểm cuối được chỉ định trong cấu hình đấu giá là decisionLogicUrl. Hàm reportResult() có chữ ký sau:

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

Các tham số reportResult() bao gồm:

  • auctionConfig, là cấu hình đấu giá được dùng để thực thi phiên đấu giá.
  • browserSignals là 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 phiên đấu giá của người bán có thể muốn xác minh. Đây cũng chính là đối tượng được truyền vào hàm scoreAds().

reportResult() trả về signalsForWinner. Đây là một đối tượng JSON tuỳ ý được truyền đến hàm báo cáo của người mua chiến thắng. Dữ liệu này phải bao gồm mọi thông tin liên quan mà người bán có thể cung cấp về phiên đấu giá mà người mua yêu cầu để báo cáo.

Chạy phiên đấu giá Protected Audience API

Người bán phải thực hiện bốn bước chính để chạy phiên đấu giá. Xin lưu ý rằng các bước này giả định rằng người bán đã thiết lập một điểm cuối để trả về JavaScript bắt buộc đã đề cập trước đó trong hướng dẫn này.

  1. Định cấu hình phiên đấu giá. Bước này bao gồm tạo đối tượng auctionConfig. Điều này cho phép người bán chỉ định người mua nào sẽ tham gia vào phiên đấu giá, cũng như cung cấp mọi tín hiệu có thể liên quan trong quá trình tạo giá thầu hoặc tính điểm quảng cáo.
  2. Thực thi phiên đấu giá bằng cách gọi navigator.runAdAuction(), truyền vào cấu hình đã tạo ở bước trước. Việc này sẽ bắt đầu chuỗi người mua tạo giá thầu, sau đó tính điểm. Kết quả cuối cùng của bước này là một đề xuất quảng cáo có thể xuất hiện để hiển thị quảng cáo.
  3. Hiển thị quảng cáo chiến thắng trong khung bảo vệ hoặc iframe.
  4. Báo cáo kết quả của phiên đấu giá. Có một hàm navigator.sendReportTo() sẽ khởi tạo hoạt động báo cáo. Người bán sẽ luôn nhận được báo cáo về kết quả phiên đấu giá. Chỉ người mua đã thắng phiên đấu giá mới nhận được báo cáo. Phương thức này sử dụng reportResult() của người bán được mô tả ở phần trước trong hướng dẫn này để báo cáo cho máy chủ của họ.