Интегрируйтесь с B&A в качестве продавца.

Сервисы торгов и аукционов (B&A) — это набор сервисов для покупателей и продавцов рекламы, работающих в среде доверенного исполнения (TEE) для проведения аукционов с защищённой аудиторией (PA). В этом руководстве разработчика объясняется, как продавец может интегрироваться с аукционом Chrome PA для B&A.

Пошаговое руководство

Эти шаги можно обобщить следующим образом:

1. Вызовите getInterestGroupAdAuctionData() чтобы получить зашифрованную полезную нагрузку из браузера.
2. Вызовите fetch('https://your-ad-server.example') и отправьте унифицированный запрос аукциона с зашифрованной полезной нагрузкой на ваш SAS.
3. Вызовите операцию SelectAd() вашего SFE из вашего SAS для запуска аукциона B&A.
4. Верните результат аукциона B&A на страницу вместе с хешем ответа.
5. Вызовите runAdAuction() в браузере, чтобы запустить аукцион PA с одним продавцом, в смешанном режиме или с несколькими продавцами, и передайте результат аукциона B&A со стороны сервера в вызов

Получите зашифрованные данные аукциона рекламы

Чтобы получить данные, необходимые для запуска аукциона B&A на стороне сервера, код JavaScript продавца на странице издателя вызывает navigator.getInterestGroupAdAuctionData() .

const adAuctionData = await navigator.getInterestGroupAdAuctionData({
  seller: 'https://ssp.example', // Required
  requestSize: 51200,
  coordinatorOrigin: 'https://publickeyservice.pa.gcp.privacysandboxservices.com/',
  perBuyerConfig: {
    'https://dsp-x.example': { targetSize: 8192 },
    'https://dsp-y.example': { targetSize: 8192 }
  }
});

const { requestId, request } = adAuctionData;

При выполнении вызова браузер считывает группы интересов покупателей, перечисленные в perBuyerConfig , и шифрует данные покупателя. Эти данные покупателя содержат межсайтовую информацию, используемую для торгов, и не могут быть расшифрованы вне TEE. Для оптимизации полезной нагрузки в полезную нагрузку включаются только название группы интересов, доверенные ключи сигналов торгов и сигналы браузера.

В объекте данных аукциона объявлений, возвращаемом вызовом getInterestGroupAdAuctionData() , доступны строка requestId и зашифрованный массив байтов request .

Строка requestId используется позже при вызове runAdAuction() для завершения аукциона в браузере. Зашифрованная полезная нагрузка request отправляется в службу объявлений продавца как часть унифицированного запроса на аукцион.

Чтобы увидеть пример этого вызова, см. код JavaScript продавца локального тестового приложения .

Отправьте единый запрос на аукцион в SAS

Унифицированный запрос на аукцион — это запрос, содержащий полезную нагрузку контекстного аукциона в открытом виде и полезную нагрузку аукциона PA B&A. Полезная нагрузка аукциона PA B&A представляет собой зашифрованные данные request , сгенерированные браузером в вызове getInterestGroupAdAuctionData() . Этот запрос отправляется в SAS, где координируются контекстный аукцион и аукцион PA B&A.

fetch('https://ssp.example/ad-auction', {
  method: 'POST',
  adAuctionHeaders: true,
  body: JSON.stringify({
    contextualAuctionPayload: { somePayload },
    protectedAudienceAuctionPayload: encodeBinaryData(request)
  }),
});

Для отправки запроса в SAS выполняется вызов fetch() со страницы:

• Вызов должен включать опцию adAuctionHeaders: true , которая сигнализирует браузеру о необходимости проверки ответа на этот вызов позднее, когда будет вызван runAdAuction() для завершения аукциона в браузере.
• Источник запроса на выборку должен совпадать с источником seller , указанным в вызовах getInterestGroupAdAuctionData() и runAdAuction() .

Текст вызова содержит:

1. Полезная нагрузка контекстного аукциона в открытом виде, которая будет использоваться SAS для проведения контекстного аукциона.
2. Зашифрованная полезная нагрузка аукциона Protected Audience, которая будет отправлена ​​в SFE компанией SAS для запуска аукциона B&A на стороне сервера.

Чтобы увидеть пример этого вызова, см. код JavaScript продавца локального тестового приложения .

Кодирование и декодирование Base64

Зашифрованные данные request , возвращаемые вызовом getInterestGroupAdAuctionData() представляют собой экземпляр Uint8Array , тип данных которого не поддерживается JSON. Чтобы отправить массив байтов в формате JSON, можно применить кодировку base64 к двоичным данным, чтобы преобразовать их в строку.

API браузера JavaScript предоставляет функции atob() и btoa() для window , которые преобразуют двоичные данные в строку ASCII, закодированную в base64. ( atob означает преобразование ASCII в двоичный код, а btoa означает преобразование двоичного кода в ASCII).

Вызов btoa() для кодирования двоичных данных в строку, закодированную в формате base64, выглядит следующим образом:

function encodeBinaryData(data) {
  return btoa(String.fromCharCode.apply(null, data));
}

Зашифрованный результат аукциона B&A, возвращаемый этим fetch выборки, также представлен в кодировке base64, поэтому его необходимо декодировать обратно в двоичные данные. Вызовите atob() чтобы декодировать строку ASCII в кодировке base64 в двоичные данные:

function decodeBase64String(base64string) {
  return new Uint8Array(
    atob(base64string)
      .split('')
      .map((char) => char.charCodeAt(0))
  );
}

Однако строка, закодированная в формате base64, обычно примерно на 33% больше исходных данных. Если вы хотите ещё больше сократить задержку, используйте для отправки двоичных данных формат, отличный от JSON.

Позвоните в SelectAd SFE, чтобы провести аукцион B&A

После того, как сервис Seller Ad Service получает со страницы единый запрос на аукцион, сначала запускается контекстный аукцион для определения победителя и сбора сигналов покупателей, которые затем передаются на аукцион PA B&A. Затем аукцион B&A инициируется вызовом операции SelectAd SFE из SAS с полезной нагрузкой запроса. Обратите внимание, что некоторые метаданные из запроса страницы к SAS на шаге 2 передаются в SFE.

Создание полезной нагрузки SelectAdRequest

Полезную нагрузку запроса SelectAd можно построить следующим образом:

const selectAdRequest = {
  auction_config: {
    seller: 'https://ssp.example',
    auction_signals: '{"testKey":"someValue"}',
    seller_signals: '{"testKey":"someValue"}',
    buyer_list: [
      'https://dsp-x.example',
      'https://dsp-y.example',
    ],
    per_buyer_config: {
      'https://dsp-x.example': { buyer_signals: '{"testKey": "someValue"}' },
      'https://dsp-y.example': { buyer_signals: '{"testKey": "someValue"}' },
    },
  },
  client_type: 'CLIENT_TYPE_BROWSER',
  protected_auction_ciphertext: decodeBase64string(request)
};

Обратите внимание: если зашифрованные данные аукциона рекламы из браузера были закодированы в формате Base64, их необходимо декодировать обратно в двоичные данные , если запрос к SFE отправляется через gRPC. Если запрос отправляется по HTTP, зашифрованные данные аукциона рекламы могут оставаться в формате Base64.

Чтобы увидеть другие поля, определенные в запросе SelectAd , см. определение proto SelectAdRequest .

Установить поле продавца верхнего уровня для аукционов смешанного режима и компонентов

Если продавец проводит аукцион в смешанном режиме или участвует в качестве продавца-компонента в аукционе с несколькими продавцами, в запросе необходимо определить поле top_level_seller .

Если вы продавец смешанного типа, то значение top_level_seller будет вашим источником:

const selectAdRequest = {
  auction_config: {
    seller: 'https://ssp-mix.example',
    top_level_seller: 'https://ssp-mix.example',
  }
}

Если вы продавец компонентов, значение top_level_seller — это продавец верхнего уровня на аукционе нескольких продавцов:

const selectAdRequest = {
  auction_config: {
    seller: 'https://ssp-mix.example',
    top_level_seller: 'https://ssp-top.example',
  }
}

Позвоните в SelectAd компании SFE

Вызов SFE из SAS можно осуществить с помощью gRPC или HTTP.

вызов gRPC

Запрос gRPC к SFE при использовании Express в Node с клиентом gRPC выглядит следующим образом:

import grpc from '@grpc/grpc-js';

// Load proto definition
const packageDefinition = protoLoader.loadSync(protoPath, { keepCase: true, enums: String });

const {
  privacy_sandbox: {
    bidding_auction_servers: { SellerFrontEnd }
  }
} = grpc.loadPackageDefinition(packageDefinition);

// Instantiate the gRPC client
const sfeGrpcClient = new SellerFrontEnd('192.168.84.104:50067', grpc.credentials.createInsecure());

// Send SelectAd request
sfeGrpcClient.selectAd(selectAdRequest,(error, response) => {
  // Handle SFE response
});

Определение прототипа для клиента SFE можно найти в локальном репозитории тестовых приложений .

HTTP-вызов к прокси-серверу Envoy

HTTP-запрос POST к SFE отправляется по пути /v1/selectAd и выглядит следующим образом:

fetch('https://ssp-ba.example/sfe/v1/selectAd', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(selectAdRequest),
});

Переслать метаданные

Следующие метаданные из вызова страницы к SAS должны быть добавлены к вызову SelectAd SAS к SFE:

• Accept-Language
• User-Agent
• IP-адрес

При отправке метаданных в SFE необходимо использовать следующие нестандартные заголовки, поскольку gRPC может изменить заголовок User-Agent :

• X-Accept-Language
• X-User-Agent
• X-BnA-Client-IP

Ниже приведен пример того, как метаданные могут быть пересланы с использованием Express в Node с клиентом gRPC :

sellerAdService.post('/ad-auction', (req, res) => {
  // …
  const metadata = new grpc.Metadata();
  metadata.add('X-Accept-Language', req.header('Accept-Language'));
  metadata.add('X-User-Agent', req.header('User-Agent'));
  metadata.add('X-BnA-Client-IP', req.ip);

  const sfeGrpcClient = createSfeGrpcClient();
  sfeGrpcClient.selectAd(selectAdRequest, metadata, callbackFn);
})

Ниже приведен пример того, как метаданные могут быть пересланы с помощью HTTP-вызова:

sellerAdService.post('/ad-auction', (req, res) => {
  // …
  fetch('https://ssp-ba.example/sfe/v1/selectAd', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-Accept-Language': req.header('Accept-Language'),
      'X-User-Agent': req.header('User-Agent'),
      'X-BnA-Client-IP': req.ip
    },
    body: JSON.stringify(selectAdRequest)
  });
})

Аукцион с несколькими продавцами, организованный сервером

Если вы являетесь продавцом верхнего уровня, ведущим аукцион с несколькими продавцами, организованный сервером , вызов GetComponentAuctionCiphertexts выполняется в SFE до вызова SelectAd . Ответ содержит повторно зашифрованные данные аукциона компонентов, которые отправляются рекламным службам продавца компонентов. Возвращенные результаты аукциона B&A-рекламы компонентов передаются в вызов SelectAd SFE продавца верхнего уровня.

Более подробную информацию можно найти в описании мультипродавца на GitHub.

Вернуть результат аукциона B&A на страницу

После завершения аукциона B&A зашифрованный результат аукциона возвращается в SAS, и SAS отвечает на унифицированный запрос аукциона со страницы на шаге 2, предоставляя зашифрованный результат аукциона. В ответе SAS на страницу хэш SHA-256 зашифрованного результата аукциона, закодированный в base64url, указывается в заголовке ответа Ad-Auction-Result . Этот хэш используется браузером для проверки полезной нагрузки при завершении аукциона в клиенте.

Создание хеша SHA-256 с кодировкой base64 в Node выглядит следующим образом:

import { createHash } from 'crypto';

createHash('sha256')
  .update(binaryData, 'base64')
  .digest('base64url');

Присоединение хеша к заголовку ответа и возврат результата аукциона на страницу выглядит следующим образом:

sellerAdService.post('/ad-auction', (req, res) => {
  // …
  sfeGrpcClient.selectAd(selectAdRequest, metadata, (error, response) => {
    const { auction_result_ciphertext } = response;

    const ciphertextShaHash = createHash('sha256')
      .update(auction_result_ciphertext, 'base64')
      .digest('base64url');

    res.set('Ad-Auction-Result', ciphertextShaHash);

    res.json({
      protectedAudienceAuctionResult: encodeBinaryData(auction_result_ciphertext),
      contextualAuctionResult: getContextualAuctionResult()
    });
  });
})

Поскольку это ответ на единый запрос аукциона, сделанный со страницы на шаге № 2 , результат контекстного аукциона также включен в ответ.

В Ad-Auction-Result можно включить несколько хешей, повторив заголовок или разделив их. Следующие два заголовка ответа эквивалентны:

Ad-Auction-Result: ungWv48Bz-pBQUDeXa4iI7ADYaOWF3qctBD_YfIAFa0=,9UTB-u-WshX66Xqz5DNCpEK9z-x5oCS5SXvgyeoRB1k=

Ad-Auction-Result: ungWv48Bz-pBQUDeXa4iI7ADYaOWF3qctBD_YfIAFa0=
Ad-Auction-Result: 9UTB-u-WshX66Xqz5DNCpEK9z-x5oCS5SXvgyeoRB1k=

Чтобы увидеть пример этого вызова, см. код сервера продавца локального тестового приложения .

Вызовите runAdAuction() для завершения аукциона.

Унифицированный ответ аукциона, возвращаемый SAS, включает зашифрованный результат аукциона B&A. Эта полезная нагрузка передаётся в вызов runAdAuction() для завершения аукциона в браузере. Значение requestId из вызова getInterestGroupAdAuctionData() на шаге 1 также передаётся в аукцион.

// Get the encrypted ad auction data (Step #1)
const { requestId, request } = navigator.getInterestGroupAdAuctionData(adAuctionDataConfig)

// Send unified auction request (Step #2)
const response = await fetch('https://ssp-ba.example/ad-auction', {
  method: 'POST',
  body: JSON.stringify({
    adAuctionRequest: encodeBinaryData(request),
  }),
});

const { protectedAudienceAuctionResult } = await response.json();

// Finish the auction in the browser
await navigator.runAdAuction({
  // pass in "requestId" and "protectedAudienceAuctionResult"
  // the config structure will differ based on the auction configuration
});

Структура конфигурации аукциона, передаваемая в вызов runAdAuction() различается в зависимости от конфигурации аукциона, выбранной продавцом.

Аукцион с одним продавцом

Для проведения аукциона B&A с одним продавцом конфигурация аукциона вызова runAdAuction() создается следующим образом:

await navigator.runAdAuction({
  seller: 'https://ssp-ba.example',
  requestId,
  serverResponse: protectedAudienceAuctionResult,
});

Поле requestId принимает requestId , возвращаемый вызовом getInterestGroupAdAuctionData() . Поле serverResponse принимает байтовый массив аукциона B&A, запущенного на шаге 3 .

Чтобы увидеть пример этого вызова, см. код JavaScript продавца локального тестового приложения .

Аукцион смешанного режима

Для проведения аукциона B&A в смешанном режиме, в котором могут участвовать как покупатели на устройстве, так и покупатели B&A, конфигурация аукциона вызова runAdAuction() создается следующим образом:

await navigator.runAdAuction({
  seller: 'https://ssp-mix.example',
  decisionLogicURL: 'https://ssp-mix.example/score-ad.js',
  componentAuctions: [
    // B&A auction result
    {
      seller: 'https://ssp-mix.example',
      requestId,
      serverResponse: protectedAudienceAuctionResult,
    },
    // On-device auction config
    {
      seller: 'https://ssp-mix.example',
      decisionLogicURL: 'https://ssp-mix.example/on-device-score-ad.js',
      interestGroupBuyers: [
        'https://dsp-a.example', // On-device buyer
        'https://dsp-a.example', // On-device buyer
      ],
    },
  ]
});

Для проведения смешанного аукциона результат аукциона B&A и конфигурация аукциона на устройстве передаются в поле componentAuctions . В смешанном аукционе значение seller одинаково как для конфигурации верхнего уровня, так и для конфигураций компонентов.

Чтобы увидеть пример этого вызова, см. код JavaScript продавца локального тестового приложения .

Аукцион с несколькими продавцами

Если вы продавец высшего уровня, проводящий аукцион с участием нескольких продавцов, организованный с помощью устройств, то каждый продавец компонентов отправляет свой результат аукциона B&A и конфигурации аукциона на устройстве.

await navigator.runAdAuction({
  seller: 'https://ssp-top.example',
  decisionLogicURL: 'https://ssp-top.example/score-ad.js',
  componentAuctions: [
    // SSP-BA's B&A-only auction result
    {
      seller: 'https://ssp-ba.example',
      requestId: 'g8312cb2-da2d-4e9b-80e6-e13dec2a581c',
      serverResponse: Uint8Array(560) [193, 120, 4, …] // Encrypted B&A auction result
    },
    // SSP-MIX's B&A auction result
    {
      seller: 'https://ssp-mix.example',
      requestId: 'f5135cb2-da2d-4e9b-80e6-e13dec2a581c',
      serverResponse: Uint8Array(560) [133, 20, 4, …] // Encrypted B&A auction result
    }.
    // SSP-MIX's on-device auction config
    {
      seller: 'https://ssp-mix.example',
      interestGroupBuyers: ['https://dsp-a.example', 'https://dsp-b.example'],
      decisionLogicURL: 'https://ssp-mix.example/score-ad.js',
    }
    // SSP-OD's on-device auction config
    {
      seller: 'https://ssp-od.example',
      interestGroupBuyers: ['https://dsp-a.example', 'https://dsp-b.example'],
      decisionLogicURL: 'https://ssp-od.example/score-ad.js',
    }
  ]
})

Чтобы увидеть пример этого вызова, см. код JavaScript продавца локального тестового приложения .

Следующие шаги

После прочтения этого руководства вы можете предпринять следующие шаги:

Узнать больше

• Для более глубокого понимания ознакомьтесь со следующими пояснениями на GitHub:
  • API B&A в Chrome
  • Проектирование системы B&A
  • Многопродавцовый аукцион B&A
  • Аукцион смешанного режима B&A
• Узнайте больше об архитектуре B&A для веб-сайтов
• Поэкспериментируйте с защищенной аудиторией с помощью B&A, следуя кодовой лаборатории «Локальное сквозное тестирование» .

Есть вопросы?

• Если у вас есть вопрос по услугам торгов и аукционов, откройте вопрос в репозитории услуг B&A .