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 bộ 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 Dịch vụ B&A, người mua sẽ cập nhật nhóm 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 thực hiện các nhiệm vụ tối ưu hoá tải trọng sau:

Nhóm đối tượng có cùng mối quan tâm về 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 đã á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 nhóm mối quan tâm trên thiết bị và B&A là:

Trường B&A IG Instagram trên thiết bị Được đưa vào tải trọng phiên đấu giá B&A
auctionServerRequestFlags Đã qua sử dụng Không được sử dụng Không
userBiddingSignals Không nên dùng Đã qua sử dụng Không, nếu bạn đặt cờ omit-user-bidding-signals
adRenderId trong ads và adComponents Đã qua sử dụng Không được sử dụng Nếu bạn đặt cờ omit-ads, adRenderId trong ads sẽ chỉ có trong browserSignals.prevWins của tải trọng. adRenderId được xác định trong adComponents không có trong tải trọng.

Nếu bạn không đặt cờ omit-ads, thì cờ này sẽ có trong browserSignals.prevWins, interestGroup.adRenderIds và interestGroup.adComponentRenderIds.
renderURL trong ads và adComponents Đã qua sử dụng Đã qua sử dụng Không
metadata trong ads và adComponents Không được sử dụng Đã qua sử dụng Không
Mã báo cáo trong ads Đã qua sử dụng Đã qua sử dụng Không
  • Trường auctionServerRequestFlags cho phép đặt cờ để yêu cầu trình duyệt bỏ qua một số dữ liệu trong tải trọng phiên đấu giá B&A.
  • Bạn có thể xác định giá trị userBiddingSignals trong nhóm mối quan tâm, nhưng bạn 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ụ K/V.
  • 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ã 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ã báo cáo không có trong tải trọng phiên đấu giá B&A. Thay vào đó, 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ã 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 phiên đấu giá, vì trình duyệt sẽ kiểm tra để đảm bảo URL hiển thị và mã báo cáo được trả về từ hàm generateBid() của Dịch vụ đặt giá thầu 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:

Cờ Nội dung mô tả
omit-user-bidding-signals Cờ omit-user-bidding-signals bỏ qua đối tượng userBiddingSignals trong tải trọng phiên đấu giá.

Nếu bạn không đặt cờ này, giá trị userBiddingSignals được xác định trong nhóm mối quan tâm sẽ có sẵn bên trong generateBid() của Dịch vụ đặt giá thầu.
omit-ads Cờ omit-ads yêu cầu trình duyệt bỏ qua các đối tượng ads và adComponents trong tải trọng phiên đấu giá.

adRenderId sẽ có trong thuộc tính prevWins của browserSignals.

Nếu bạn không đặt cờ này, các trường adRenderIds và adComponentRenderIds trong đối số interestGroup của generateBid() sẽ chứa mã hiển thị quảng cáo tương ứng.

Người mua nên chọn cờ omit-ads. Tại một thời điểm nào đó trong tương lai, việc truyền mã nhận dạng kết xuất và mã nhận dạng kết xuất thành phần quảng cáo từ ứng dụng có thể không còn được dùng nữa để tối ưu hoá tải trọng hơn nữa.

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 từng cờ riêng lẻ và không nhất thiết 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 tải trọng phiên đấu giá B&A, các đối tượng ads và adComponents của nhóm mối quan tâm sẽ bị bỏ qua, do đó, các đối tượng này sẽ không có trong hàm generateBid() 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) liên kết với từng quảng cáo trong cấu hình nhóm mối quan tâm. Giá trị nhận dạng phải là một DOMString có độ dài từ 12 byte trở xuống. Nếu giá trị nhận dạng được mã hoá Base64, thì độ dài của giá trị nhận dạng đó phải nhỏ hơn hoặc bằng 12 byte.

Ví dụ về 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 trong generateBid().

Mặc dù renderURL không có trong tải trọng yêu cầu, nhưng URL hiển thị được trả về từ generateBid() phải khớp với URL hiển thị đượ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à thông tin khác trong trustedBiddingSignals để có thể tạo URL hiển thị quảng cáo và URL hiển thị thành phần quảng cáo cho giá thầu trong quá trình thực thi generateBid().

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

Chrome cho phép người mua ưu tiên các nhóm mối quan tâm. Nếu người bán đã đặt giới hạn kích thước tải trọng trên mỗi người mua, thì các giá trị mức độ ưu tiên của nhóm mối quan tâm sẽ được dùng để loại bỏ các nhóm mối quan tâm có mức độ ưu tiên thấp hơn cho một người mua 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 đượ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ạo tải trọng yêu cầu.

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

Thuộc tính Nội dung mô tả
Vectơ mức độ ưu tiên Người mua cung cấp các vectơ dưới dạng giá trị của khoá priorityVector từ Dịch vụ khoá/giá trị
Tín hiệu ưu tiên Người bán cung cấp các tín hiệu bằng cách đặt priority_signals của cấu hình phiên đấu giá
Ghi đè tín hiệu ưu tiên Người mua cung cấp chế độ ghi đè trong trường priority_signals_overrides của PerBuyerConfig trong cấu hình phiên đấu giá.

Trong phiên đấu giá, trình duyệt sẽ tính toán tích vô hướng thưa thớt của các khoá trùng 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) được giảm xuống còn 8 + -3, vì vậy, mức độ ưu tiên của nhóm mối quan tâm này tại thời điểm đấu giá là 5.

Mỗi khoá trong vectơ mức độ ưu tiên và các đối tượng tín hiệu mức độ ưu tiên được nhân với nhau, sau đó kết quả được cộng lại với nhau để tính mức độ ưu tiên
Hình 1: Tính toán mức độ ưu tiên bằng cách sử dụng vectơ của người mua và tín hiệu của người bán

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ín hiệu Nội dung mô tả
deviceSignals.one Giá trị này luôn là 1 và hữu ích khi thêm một hằng số vào tích vô hướng.
deviceSignals.ageInMinutes Giá trị này mô tả thời gian hoạt động của nhóm mối quan tâm (kể từ lần tham gia nhóm mối quan tâm gần đây nhất) tính bằng phút dưới dạng số nguyên từ 0 đến 43.200.
deviceSignals.ageInMinutesMax60 Giá trị này mô tả giống như tín hiệu ageInMinutes, nhưng tối đa là 60. Nếu nhóm đã tồn tại hơn 1 giờ, thì hệ thống sẽ trả về giá trị 60.
deviceSignals.ageInHoursMax24 Giá trị này mô tả độ tuổi của nhóm mối quan tâm tính bằng giờ, tối đa là 24 giờ. Nếu nhóm đã tồn tại hơn một ngày, thì hệ thống sẽ trả về giá trị 24.
deviceSignals.ageInDaysMax30 Giá trị này mô tả độ tuổi của nhóm mối quan tâm tính bằng ngày, tối đa là 30 ngày. Nếu nhóm đã tồn tại hơn 30 ngày, thì hệ thống sẽ trả về giá trị 30.

Để tìm hiểu thêm, hãy truy cập vào 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 khỏi 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 dữ liệu bị bỏ qua sau đây:

  • userBiddingSignals nếu người mua sử dụng
  • metadata liên kết với mỗi quảng cáo
  • adRenderId liên kết với mỗi quảng cáo
  • Mã báo cáo
Dữ liệu bị bỏ qua từ nhóm mối quan tâm có thể được gửi đến máy chủ thu thập dữ liệu của người mua. Máy chủ thu thập đẩy dữ liệu đến dịch vụ khoá/giá trị và sau đó, trình duyệt sẽ tải dữ liệu đó từ dịch vụ khoá/giá trị
Hình 2: Ví dụ về cách thiết lập tín hiệu đáng tin cậy

Một phương pháp có thể được áp dụng là đưa một giá trị nhận dạng duy nhất vào khoá tín hiệu đặt giá thầu đáng tin cậy, sau đó gửi dữ liệu liên kết đến máy chủ của bạn để 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ế phụ thuộc vào công nghệ quảng cáo và API không mang tính quy định.

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 duy nhất được xác định cho một 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ị. 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 mối quan tâm được lưu trữ trong trình duyệt, thì trình duyệt sẽ không vượt qua 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ề nhóm quảng cáo trong nhóm mối quan tâm.

Hãy truy cập vào bài viết 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 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:

Thuộc tính Nội dung mô tả
prevWins prevWins là một mảng các bộ dữ liệu gồm thời gian và quảng cáo. Thời gian này thể hiện số giây đã trôi qua kể từ lần chiến thắng trước đó của quảng cáo được liên kết trong 30 ngày qua.

Phương thức này đã được sửa đổi để cung cấp adRenderId thay vì đối tượng ad.
wasmHelper Đối tượng đã biên dịch của mã được cung cấp từ biddingWasmHelperURL.
dataVersion Một máy chủ đáng tin cậy có thể tuỳ ý thêm tiêu đề phản hồi Data-Version dạng số có sẵn trong generateBid().

Đọc tài liệu giải thích trên GitHub để tìm hiểu thêm.

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

Vì đối tượng ads bị bỏ qua trong tải trọng phiên đấu giá B&A, nên bạn phải tạo lại URL hiển thị được trả về từ generateBid(). Cách tạo lại URL hiển thị sẽ do cách triển khai của bạn xác định 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 phương pháp có thể áp dụng là duy trì một 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 và thông tin sản phẩm mà người dùng yêu thích để 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á chạy, các tín hiệu đặt giá thầu đáng tin cậy sẽ xuất hiện trong generateBid() và bạn có thể sử dụng thông tin đó để 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ã báo cáo không có trong tải trọng phiên đấu giá B&A, nên mã 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 mã báo cáo cần sử dụng, mã báo cáo đã chọn sẽ được trả về từ generateBid(). Mã nhận dạng được trả về phải khớp với 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ã hiển thị liên kết với quảng cáo đó được trả về từ generateBid():

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

Mã 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 truy cập vào Hướng dẫn về mã 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

Bạn có câu hỏi?