Hướng dẫn dành cho người bán: chạy phiên đấu giá quảng cáo

Hướng dẫn và thông tin tham khảo về API người bán cho phiên đấu giá quảng cáo Protected Audience API.

Trong bài viết này, bạn sẽ tìm thấy tài liệu tham khảo kỹ thuật cho phiên đấu giá quảng cáo, như được sử dụng trong phiên bản hiện tại của Protected Audience API thử nghiệm.

Đọc hướng dẫn cho nhà phát triển toàn bộ chu kỳ của Protected Audience API và tham khảo tài liệu giải thích về Protected Audience API để nắm được nội dung thảo luận chuyên sâu về cách người bán chạy phiên đấu giá trên thiết bị.

Bạn không phải nhà phát triển? Tham khảo tổng quan về Protected Audience API.

Phiên đấu giá quảng cáo Protected Audience API là gì?

Phiên đấu giá quảng cáo Protected Audience API là một tập hợp các chương trình JavaScript nhỏ mà trình duyệt chạy trên thiết bị của người dùng để chọn quảng cáo. Để bảo vệ quyền riêng tư, tất cả quảng cáo mã đấu giá của người bán và người mua được chạy trong JavaScript riêng biệt worklet không thể kết nối với bên ngoài thế giới.

6 giai đoạn trong phiên đấu giá quảng cáo Protected Audience API
Sơ đồ này trình bày từng giai đoạn của một phiên đấu giá quảng cáo bằng 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 chỉ định không gian quảng cáo là để 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 từng giá thầu, scoreAd().
  3. Mã của người mua được mời thực thi để tạo giá thầu, URL cho quảng cáo có liên quan mẫu quảng cáo và 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, Dịch vụ Khoá/Giá trị.
  4. Mã của người bán tính điểm 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à dữ liệu khác trả về mức độ mong muốn của giá thầu. Những quảng cáo không thể bỏ qua quảng cáo chiến thắng theo bối cảnh sẽ bị từ chối. Người bán có thể sử dụng Dịch vụ Khoá/Giá trị 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, giá trị này hiển thị trong một khung 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 chiến thắng.

Phiên đấu giá diễn ra khi nào?

Bạn có thể chạy Protected Audience API độc lập hoặc trong các phiên đấu giá có lập trình. Trong chương trình nhiều người bán, phiên đấu giá có lập trình:

  1. Người dùng truy cập vào trang web tham gia.
  2. Một người bán khác tiến hành phiên đấu giá có lập trình để tìm quảng cáo theo bối cảnh cho một vùng quảng cáo có sẵn.
  3. Phiên đấu giá Protected Audience API sẽ chạy.
  4. scoreAd()so sánh giá thầu của người mua với kết quả của phiên đấu giá đầu tiên.

Những giá thầu không thể vượt qua giá thầu chiến thắng theo bối cảnh sẽ bị từ chối.

Ai chạy phiên đấu giá quảng cáo Protected Audience API?

Có nhiều bên có thể tiến hành phiên đấu giá để bán không gian quảng cáo.

Ví dụ:

  • 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 và cung cấp các dịch vụ khác.
  • Tập lệnh của bên thứ ba: hoạt động cho nhà xuất bản để cho phép tham gia vào các phiên đấu giá quảng cáo.

Với Protected Audience API, người bán có 3 công việc:

  • Thực thi các quy tắc của nhà xuất bản: người mua và giá thầu nào đủ điều kiện.
  • Chạy logic đấu giá: JavaScript chạy trong bài tập để tính toán điểm mong muốn cho mỗi giá thầu.
  • Báo cáo kết quả phiên đấu giá.

Các công việc này được thực hiện theo chương trình, bằng mã do người bán cung cấp khi khuyến khích một phiên đấu giá quảng cáo bằng cách gọi hàm JavaScript navigator.runAdAuction().

Các hàm API

runAdAuction()

Người bán đưa ra yêu cầu tới 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().

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': ...,
      ...
    },
    ...
  ]
};

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

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.

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

auctionConfig cơ sở lưu trú

seller
Bắt buộc
Ví dụ: 'https://ssp.example'
Vai trò: Nguồn gốc của người bán.
decisionLogicUrl
Bắt buộc
Ví dụ: 'https://ssp.example/auction-decision-logic.js'
Vai trò: URL cho worklet đấu giá JavaScript.
trustedScoringSignalsUrl
Không bắt buộc
Ví dụ: 'https://ssp.example/scoring-signals'
Vai trò: URL của máy chủ đáng tin cậy của người bán.
interestGroupBuyers
Bắt buộc
Ví dụ: ['https://dsp.example', 'https://buyer2.example', ...]
Vai trò: Nguồn gốc của tất cả cá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á.
Lưu ý: 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ọ.
auctionSignals
Không bắt buộc
Ví dụ: {...}
Vai trò: 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
Ví dụ: {...}
Vai trò: Thông tin dựa trên chế độ cài đặt của nhà xuất bản, đưa ra yêu cầu quảng cáo theo bối cảnh, v.v.
sellerTimeout
Không bắt buộc
Ví dụ: 100
Vai trò: 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
Ví dụ:
{'https://dsp.example': {...}, 'https://another-buyer.example': {...}, ... }
Vai trò: Các 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
Ví dụ: 50
Vai trò: 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
Ví dụ:
[{'seller': 'https://www.some-other-ssp.com', 'decisionLogicUrl': ..., ...}, ...]
Vai trò: Cấu hình bổ sung cho phiên đấu giá thành phần.

decisionLogicUrl

decisionLogicUrl là thuộc tính của đối tượng cấu hình đấu giá, được truyền đến runAdAuction(). URL này phải chứa một tập lệnh cho Hàm scoreAd(). Logic này chạy một lần cho mỗi quảng cáo để xác định mong muốn của ứng dụng đó.

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

browserSignals

browserSignals là một đối tượng do trình duyệt tạo, bao gồm cả 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 /* DValue 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 tốt nhất cho vùng quảng cáo có sẵn. Một phần của logic scoreAd() từ chối mọi quảng cáo không thể đánh bại biến thể chiến thắng theo bối cảnh.

scoreAd()

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

Đối số Vai trò
adMetadata Siêu dữ liệu tuỳ ý do người mua cung cấp.
auctionConfig Đối tượng cấu hình phiên đấu giá được truyền đến navigator.runAdAuction().
bid Giá trị giá thầu bằng số.
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 quan điểm của người bán về quảng cáo.

Câu hỏi thường gặp

Người chiến thắng phiên đấu giá được quyết định như thế nào và ai sẽ chọn họ?

Người bán cung cấp logic tính điểm để xác định điểm số mong muốn của từng quảng cáo, và trình duyệt sẽ chọn điểm số cao nhất làm quảng cáo giành chiến thắng.

Người bán đưa logic vào hàm scoreAd(), còn trình duyệt sẽ thực thi hàm này trong một worklet có chức năng giao tiếp hạn chế với mã bên ngoài. Bản thân trình duyệt không tính điểm quảng cáo. Trình duyệt chịu hoàn toàn trách nhiệm thực thi logic tính điểm và chọn giá thầu có điểm số cao nhất.

Tất cả tệp tham chiếu Protected Audience API

Hướng dẫn tham khảo API có sẵn:

Thông tin giải thích về Protected Audience API cũng cung cấp thông tin chi tiết về các quy tắc hỗ trợ và các quy tắc ràng buộc của tính năng.