Tích hợp với B&A với tư cách là người mua

Dịch vụ Đặt giá thầu và Phiên đấu giá (B&A) là một nhóm dịch vụ dành cho người mua và người bán quảng cáo, chạy trong Môi trường thực thi đáng tin cậy (TEE) để hỗ trợ phiên đấu giá Protected Audience (PA). Hướng dẫn dành cho nhà phát triển này giải thích cách người mua có thể tích hợp với phiên đấu giá PA B&A cho Chrome.

Tổng quan

Để tham gia phiên đấu giá Protected Audience bằng B&A Services, người mua sẽ cập nhật nhóm đối tượng có cùng mối quan tâm (IG) để tối ưu hoá tải trọng nhằm cải thiện độ trễ của phiên đấu giá.

Người mua yêu cầu bạn thực hiện các nhiệm vụ tối ưu hoá tải trọng sau đây:

• joinAdInterestGroup() việc cần làm
  • Đặt cờ yêu cầu máy chủ
  • Đặt mã nhận dạng hiển thị quảng cáo
  • Đặt mức độ ưu tiên cho nhóm lợi ích
  • Thiết lập tín hiệu đặt giá thầu đáng tin cậy
• generateBid() việc cần làm
  • Đọc tín hiệu của trình duyệt
  • Trả về URL hiển thị
  • Trả về mã nhận dạng báo cáo

Nhóm đối tượng có cùng mối quan tâm đối với B&A

Sau đây là ví dụ về cấu hình nhóm mối quan tâm cho phiên đấu giá PA B&A có áp dụng tính năng tối ưu hoá tải trọng:

navigator.joinAdInterestGroup({
  name: 'example-ig',
  owner: 'https://dsp.example',

  // An ID is mapped to each render URL
  ads: [
    {
      renderURL: 'https://dsp.example/ad.html',
      adRenderId: '12345678' // 12 characters max,
      buyerReportingId: 'brid123', // Optional
      buyerAndSellerReportingId: 'bsrid123', // Optional
      selectableBuyerAndSellerReportingId: ['sbsrid123', 'sbsrid456'], // Optional
    },
  ],
  adComponents: [
    {
      renderURL: 'https://dsp.example/ad-component.html',
      adRenderId: 'abcdefgh'
    },
  ],

  // Flags are set to omit data in the B&A auction payload
  auctionServerRequestFlags: ['omit-ads', 'omit-user-bidding-signals'],

  // Data not included in the B&A auction payload can be fetched as trusted signals
  // The following is an example of how the keys could look, but the actual
  // implementation is up to the ad tech
  trustedBiddingSignalsKeys: [
    'exampleUserBiddingSignalsKey',
    'exampleAdRenderIdKey',
    'exampleAdMetadataKey',
    'exampleAdReportingIdKey',
  ],

  // Optionally, interest groups can be prioritized
  priority: 0.0,
});

Sự khác biệt giữa cấu hình B&A và nhóm lợi ích trên thiết bị là:

• Trường auctionServerRequestFlags cho phép đặt các cờ yêu cầu trình duyệt bỏ qua một số dữ liệu trong tải trọng đấu giá B&A.
• Bạn có thể xác định giá trị userBiddingSignals trong nhóm lợi ích, nhưng nên bỏ qua các giá trị này bằng cách sử dụng cờ omit-user-bidding-signals. Bạn có thể cung cấp các tín hiệu bị bỏ qua bằng cách sử dụng Dịch vụ khoá/giá trị.
• Trường adRenderId được đặt cùng với renderURL được liên kết, nhưng chỉ adRenderId mới trở thành một phần của tải trọng phiên đấu giá B&A. URL hiển thị được trả về từ generateBid() sau đó trong thời gian đấu giá phải khớp với URL hiển thị được xác định trong IG.
• Mã nhận dạng báo cáo được xác định trong IG B&A nhưng không có trong tải trọng phiên đấu giá B&A. Mã nhận dạng báo cáo được trả về từ generateBid() sau đó trong thời gian đấu giá phải khớp với URL hiển thị được xác định trong IG.
• ad.metadata và mã nhận dạng báo cáo không có trong tải trọng phiên đấu giá B&A. Thay vào đó, những dữ liệu đó sẽ có sẵn thông qua việc sử dụng Dịch vụ khoá/giá trị đáng tin cậy.

Xin lưu ý rằng renderURL và mã nhận dạng báo cáo trong ads vẫn được xác định trong cấu hình nhóm mối quan tâm, mặc dù chúng không được đưa vào tải trọng yêu cầu đấu giá, vì trình duyệt kiểm tra để đảm bảo rằng URL hiển thị và mã nhận dạng báo cáo do hàm generateBid() của Dịch vụ đặt giá thầu trả về khớp với các giá trị được xác định trong nhóm mối quan tâm.

joinAdInterestGroup() việc cần làm

Bạn cần thực hiện các thao tác sau cho lệnh gọi joinAdInterestGroup().

Đặt cờ yêu cầu máy chủ

Trường auctionServerRequestFlags của cấu hình joinAdInterestGroup() chấp nhận các cờ sau:

Dữ liệu bị bỏ qua được xử lý bằng cách cung cấp thông tin liên quan trong trustedBiddingSignals. Bạn có thể sử dụng riêng từng cờ và không bắt buộc phải sử dụng cùng nhau.

Ví dụ về cách sử dụng:

navigator.joinAdInterestGroup({
  auctionServerRequestFlags: ['omit-user-bidding-signals', 'omit-ads'],
});

Đặt mã nhận dạng hiển thị quảng cáo

Để giảm kích thước của tải trọng phiên đấu giá B&A, các đối tượng ads và adComponents của nhóm lợi ích sẽ bị bỏ qua. Do đó, các đối tượng này sẽ không có trong hàm generateBid() đang chạy trong Dịch vụ đặt giá thầu.

Để xử lý thông tin quảng cáo bị thiếu, người mua duy trì một giá trị nhận dạng (adRenderId và adComponentRenderId) được liên kết với mỗi quảng cáo trong cấu hình nhóm lợi ích. Giá trị nhận dạng phải là một DOMString có độ dài tối đa là 12 byte. Nếu mã nhận dạng được mã hoá Base64, thì độ dài của mã nhận dạng phải từ 12 byte trở xuống.

Ví dụ về một nhóm mối quan tâm có mã hiển thị quảng cáo:

navigator.joinAdInterestGroup({
  ads: [
    {
      renderURL: 'https://dsp.example/ad.html',
      adRenderId: '12345678' // 12 characters max
    },
  ],
  adComponents: [
    {
      renderURL: 'https://dsp.example/ad-component.html',
      adComponentRenderId: 'abcdefgh'
    },
  ],
});

adRenderId được liên kết với quảng cáo sẽ xuất hiện trong prevWins.browserSignals trên generateBid().

Mặc dù renderURL không có trong tải trọng yêu cầu, nhưng URL kết xuất được trả về từ generateBid() phải khớp với URL kết xuất được xác định trong cấu hình nhóm mối quan tâm. Công nghệ quảng cáo có thể gửi lại siêu dữ liệu quảng cáo và các thông tin khác trong trustedBiddingSignals, để URL hiển thị quảng cáo và URL hiển thị thành phần quảng cáo có thể được tạo cho giá thầu trong quá trình thực thi generateBid().

Đặt mức độ ưu tiên cho nhóm đối tượng có cùng mối quan tâm

Chrome cho phép người mua ưu tiên các nhóm đối tượng có cùng mối quan tâm. Nếu đạt đến giới hạn kích thước tải trọng trên mỗi người mua do người bán đặt, thì các giá trị mức độ ưu tiên của nhóm lợi ích sẽ được dùng để loại bỏ các nhóm lợi ích có mức độ ưu tiên thấp hơn cho một người mua duy nhất khi tải trọng phiên đấu giá B&A được tạo cho người bán. Để chọn nhóm mối quan tâm giữa các người mua, trình duyệt sẽ quyết định dựa trên kích thước của tải trọng được chuyển đổi tuần tự. Theo mặc định, mỗi người mua sẽ được cấp một kích thước bằng nhau. Xin lưu ý rằng việc ưu tiên thực tế diễn ra trên các máy chủ B&A, chứ không phải khi tải trọng yêu cầu được tạo.

Mức độ ưu tiên được tính tại thời điểm đấu giá bằng cách sử dụng các vectơ ưu tiên của người mua (priorityVector) và các tín hiệu ưu tiên của người bán (prioritySignals). Người mua có thể ghi đè các tín hiệu ưu tiên của người bán.

Trong phiên đấu giá, trình duyệt sẽ tính tích vô hướng thưa của các khoá khớp trong priorityVector và prioritySignals cho mức độ ưu tiên. Trong sơ đồ sau, mức độ ưu tiên được tính bằng (4 * 2) + (3 * -1), giảm xuống còn 8 + -3, nên mức độ ưu tiên của nhóm đối tượng có cùng sở thích này tại thời điểm đấu giá là 5.

Bạn cũng có thể sử dụng các tín hiệu bổ sung để sắp xếp mức độ ưu tiên trong B&A:

Để tìm hiểu thêm, hãy xem tài liệu giải thích trên GitHub.

Thiết lập tín hiệu đặt giá thầu đáng tin cậy

Vì một số dữ liệu sẽ bị bỏ qua trong tải trọng phiên đấu giá B&A, nên bạn có thể sử dụng Dịch vụ khoá/giá trị để cung cấp dữ liệu bị bỏ qua dưới dạng tín hiệu đặt giá thầu đáng tin cậy cho hàm generateBid().

Dịch vụ K/V có thể cung cấp những dữ liệu bị bỏ qua sau đây:

• userBiddingSignals nếu người mua sử dụng
• metadata được liên kết với từng quảng cáo
• adRenderId được liên kết với từng quảng cáo
• Mã báo cáo

Một phương pháp có thể được áp dụng là thêm một giá trị nhận dạng duy nhất vào các khoá tín hiệu đặt giá thầu đáng tin cậy, sau đó gửi dữ liệu được liên kết đến máy chủ của bạn để máy chủ có thể tải dữ liệu đó vào Dịch vụ khoá/giá trị. Tuy nhiên, việc triển khai thực tế là tuỳ thuộc vào công nghệ quảng cáo và API không mang tính bắt buộc.

Ví dụ sau đây mô tả một phương pháp có thể triển khai:

const ad1RenderURL = 'https://dsp.example/ad-1.html';
const ad2RenderURL = 'https://dsp.example/ad-2.html';
const ad1RenderId = 'render-id-1';
const ad2RenderId = 'render-id-2';
const ad1ReportingId = 'reporting-id-1';
const ad2ReportingId = 'reporting-id-2';

// Generate a unique identifier
const id = crypto.randomUUID();

// Define the keys with the unique ID
const trustedSignalsKeyForIG = `interest-group-${id}`

// Set the keys in the interest group
navigator.joinAdInterestGroup({
  // …
  ads: [
    {
      renderURL: ad1RenderURL,
      adRenderId: ad1RenderId,
      buyerReportingId: ad1ReportingId
    },
    {
      renderURL: ad2RenderURL,
      adRenderId: ad2RenderId,
      buyerReportingId: ad2ReportingId
    },
  ],
  trustedBiddingSignalsKeys: [
    trustedSignalsKeyForIG
  ]
});

// Send the associated data to your server to be loaded into the Key/Value Service
fetch('https://dsp.example/kv/load', {
  method: 'POST',
  body: JSON.stringify({
    id,
    [trustedSignalsKeyForIG]: {
      userBiddingSignals: {
        favoriteColor: 'blue'
      },
      ads: [
        {
          renderURL: ad1RenderURL,
          adRenderId: ad1RenderId,
          buyerReportingId: ad1ReportingId,
          metadata: {
            color: 'red'
          }   
        },
        {
          renderURL: ad2RenderURL,
          adRenderId: ad2RenderId,
          buyerReportingId: ad2ReportingId,
          metadata: {
            color: 'blue'
          }   
        },
      ]
    }
  })
});

Trong ví dụ này, một giá trị nhận dạng riêng biệt được xác định cho IG và trở thành một phần của khoá tín hiệu đáng tin cậy. Khoá cho IG và các giá trị liên kết của khoá đó sẽ được gửi đến máy chủ của bạn để tải vào Dịch vụ khoá/giá trị. Vào một thời điểm sau đó trong phiên đấu giá, trình duyệt sẽ tìm nạp các tín hiệu đáng tin cậy và cung cấp các tín hiệu đó trong hàm generateBid() của người mua.

Trả về tín hiệu cập nhật nhóm mối quan tâm từ K/V nếu cần

Khoá updateIfOlderThanMs cho các tín hiệu đáng tin cậy được dùng để cập nhật nhóm mối quan tâm sớm hơn khoảng thời gian hằng ngày thông thường. Nếu nhóm mối quan tâm chưa được tham gia hoặc cập nhật trong khoảng thời gian vượt quá giá trị mili giây được trả về cho khoá updateIfOlderThanMs, thì nhóm mối quan tâm sẽ được cập nhật bằng cơ chế updateURL. Xin lưu ý rằng Chrome sẽ không cập nhật nhóm mối quan tâm thường xuyên hơn 10 phút một lần.

Nếu phiên đấu giá B&A trả về một quảng cáo chiến thắng không khớp với một trong các quảng cáo được xác định trong nhóm lợi ích được lưu trữ trong trình duyệt, thì trình duyệt sẽ không thực hiện được phiên đấu giá. Cơ chế updateIfOlderThanMs có thể hữu ích trong việc đảm bảo rằng trình duyệt và phiên đấu giá B&A đồng ý về tập hợp quảng cáo trong nhóm đối tượng có cùng mối quan tâm.

Hãy xem video giải thích để tìm hiểu thêm.

generateBid() việc cần làm

Bạn cần thực hiện các thao tác sau cho lệnh gọi generateBid().

Đọc tín hiệu của trình duyệt

Đối tượng browserSignals được truyền vào lệnh gọi generateBid() của B&A có dạng như sau:

{
  topWindowHostname: 'advertiser.example',
  seller: 'https://ssp.example',
  topLevelSeller: 'https://ssp-top.example',
  joinCount: 5,
  bidCount: 24,
  recency: 1684134092,

  // prevWins is [timeInSeconds, adRenderId]
  prevWins: [
    [9342, 'render-id-1'],
    [1314521, 'render-id-2']
  ],

  // Compiled WebAssembly code
  wasmHelper: WebAssembly.Module

  // Data-Version value from K/V response, if available
  dataVersion: 1,
}

Các thuộc tính mới hoặc đã sửa đổi sau đây có trong browserSignals:

Trả về URL kết xuất từ generateBid()

Vì đối tượng ads bị bỏ qua trong tải trọng của phiên đấu giá B&A, nên bạn phải tạo lại URL kết xuất được trả về từ generateBid(). Cách tạo lại URL hiển thị được xác định bằng việc triển khai của bạn và URL được trả về phải khớp với URL hiển thị được xác định trong nhóm mối quan tâm.

Một cách có thể áp dụng là duy trì URL cơ sở và điền thông tin từ interestGroup và trustedBiddingSignals vào mẫu.

Trong ví dụ này, chúng ta sẽ xác định 4 quảng cáo dựa trên màu sắc và sản phẩm:

await navigator.joinAdInterestGroup({
  ads: [
    { renderURL: 'https://dsp.example/red-shirt-ad.html', adRenderId: 'arid1'},
    { renderURL: 'https://dsp.example/blue-shirt-ad.html', adRenderId: 'arid2'},
    { renderURL: 'https://dsp.example/red-pants-ad.html', adRenderId: 'arid3'},
    { renderURL: 'https://dsp.example/blue-pants-ad.html', adRenderId: 'arid4'},
  ],
  trustedBiddingSignalKeys: [
    'userBiddingSignals-someUniqueId',
    // ...and more
  ]
})

Sau đó, chúng ta sẽ gửi màu sắc yêu thích và thông tin sản phẩm của người dùng để tải vào Dịch vụ khoá/giá trị:

fetch('https://dsp.example/kv/load', {
  body: JSON.stringify({
    'userBiddingSignals-someUniqueId': {
      favoriteColor: 'blue',
      favoriteProduct: 'shirt'
    }
  })
})

Sau đó, khi phiên đấu giá diễn ra, các tín hiệu đặt giá thầu đáng tin cậy sẽ có trong generateBid() và thông tin đó có thể được dùng để tạo lại URL:

function generateBid(..., trustedBiddingSignals, browserSignals) {
  const { userBiddingSignals } = trustedBiddingSignals
  const { favoriteColor, favoriteProduct } = userBiddingSignals

  return {
    bid: 1,
    render: `https://dsp.example/${favoriteColor}-${favoriteProduct}-ad.html`
  }
}

Trả về mã báo cáo từ generateBid()

Vì mã nhận dạng báo cáo không có trong tải trọng phiên đấu giá B&A, nên mã nhận dạng này sẽ có sẵn cho generateBid() thông qua các tín hiệu đặt giá thầu đáng tin cậy. Sau khi xác định được mã báo cáo cần sử dụng, mã báo cáo đã chọn sẽ được trả về từ generateBid(). Các mã nhận dạng được trả về phải khớp với các mã nhận dạng được xác định trong nhóm mối quan tâm.

Trong ví dụ này, quảng cáo 1 được chọn và mã nhận dạng hiển thị được liên kết với quảng cáo đó sẽ được trả về từ generateBid():

generateBid(..., trustedBiddingSignals, …) {
  const { ad1ReportingId, ad2reportingId } = trustedBiddingSignals;
  // ...
  return {
    bid: 1,
    render: 'https://dsp.example/ad-1.html'
    buyerReportingId: ad1reportingId
  }
}

Mã nhận dạng báo cáo được trả về sẽ có trong reportWin() thông qua buyerReportingSignals:

reportWin(..., buyerReportingSignals) {
  const { buyerReportingId } = buyerReportingSignals;
}

Nếu buyerReportingId không được trả về từ generateBid(), thì giá trị interestGroupName sẽ có trong buyerReportingSignals thay vì buyerReportingId.

Hãy xem hướng dẫn về mã nhận dạng báo cáo để tìm hiểu thêm.

Các bước tiếp theo

Bạn có thể tham khảo các tài nguyên sau

Tìm hiểu thêm

• Tìm hiểu thêm về các cấu hình đấu giá B&A trong Chrome
• Thử nghiệm Protected Audience bằng B&A bằng cách làm theo Lớp học lập trình Kiểm thử cục bộ toàn diện.

Bạn có thắc mắc?

• Nếu bạn có câu hỏi về Dịch vụ đặt giá thầu và phiên đấu giá, hãy mở một vấn đề trong kho lưu trữ Dịch vụ đặt giá thầu và phiên đấu giá.