Отчеты об аукционах API Protected Audience

Измерение данных и результатов аукциона с использованием API защищенной аудитории.

В этой статье вы найдете общий обзор различных механизмов, доступных для отправки данных аукциона Protected Audience API на ваш сервер, а также механизмы перехода, доступные в настоящее время для использования во время миграции до тех пор, пока не будут готовы альтернативные решения.

Для формирования отчетов по важным показателям, полученным в ходе рекламного аукциона, API защищенной аудитории работает со следующими компонентами:

• Частная система агрегации , которая собирает сигналы и результаты аукционов для создания сводных отчетов .
• API отчетов по рекламе для закрытых фреймов и iframe — это канал внутри фреймов для связи с рабочими модулями API защищенной аудитории. API позволяет связывать данные на уровне событий с сигналами аукциона. Отчетность на уровне событий в API отчетов по рекламе является временным механизмом до тех пор, пока не будет разработан более приватный механизм отчетности.
• Отчеты по атрибуции , позволяющие связывать данные о конверсиях с сигналами аукциона.
• Общее хранилище позволяет записывать сигналы аукциона в междоменное хранилище, а затем передавать эти данные позже с помощью частной агрегации.

Обзор отчетов API для защищенной аудитории

Существует три основных временных периода, в течение которых данные из процесса аукциона Protected Audience API могут передаваться на ваш сервер: время проведения аукциона на сайте издателя, время отображения объявления в рамке или iframe на сайте издателя и время конверсии, когда пользователь совершает какое-либо действие на другом сайте, которое может быть связано с аукционом.

Во время проведения аукциона вы можете формировать отчеты на основе полученных данных с помощью рабочих модулей. Во время отрисовки вы можете формировать отчеты на основе данных о вовлеченности пользователей из iframe или фрейма с ограждением. Во время конверсии вы можете формировать отчеты на основе данных об атрибуции со страницы назначения, используя API отчетов об атрибуции.

Места предоставления отчетов

В рамках аукциона покупатели могут сообщать о сигналах, доступных в рабочих модулях generateBid() и reportWin() , а продавцы — о сигналах, доступных в scoreAd() и reportResult() . Вне аукциона покупатели и продавцы могут сообщать данные из фрейма, который отобразил объявление, и с сайта, с которого была совершена конверсия.

В течение каждого из указанных периодов времени покупатели и продавцы будут иметь доступ к различным API-интерфейсам для формирования отчетов, содержащих такие данные, как сигналы аукциона, данные об уровне событий и данные о конверсиях.

Данные, доступные в рамках аукциона API для защищенной аудитории.

В ходе аукциона из рабочего модуля API для защищенной аудитории можно получить следующие данные.

Сигналы

Сигналы — это контекстные данные аукциона, данные пользователя, данные в реальном времени и данные браузера, доступные покупателям и продавцам в рамках рабочего процесса для формирования ставки, оценки объявления и сообщения о результатах аукциона.

Объект конфигурации аукциона является основным источником данных, которые становятся доступными в качестве сигналов в рабочих модулях. Издатель и продавец могут предоставлять контекстные данные и собственные данные в конфигурации аукциона, а эти сигналы могут быть дополнены данными о группах интересов покупателя, данными уровня событий из фрейма отображения рекламы и данными атрибуции со страницы перехода по ссылке. Сообщаемые данные могут использоваться для отчетности покупателей/продавцов, выставления счетов, составления бюджета, обучения моделей машинного обучения и многого другого.

Другие доступные данные

• Результаты аукциона, включающие данные о выигрышах и проигрышах, такие как цена выигрышной ставки и причина отклонения ставки.
• Данные о производительности , содержащие информацию о задержке, например, сколько времени потребовалось для получения и выполнения рабочего модуля торгов.

Данные, доступные вне аукциона API защищенной аудитории.

Помимо аукциона API для защищенной аудитории, существуют два временных периода, в течение которых данные доступны для составления отчетов.

Во время отрисовки, когда объявление отображается на сайте издателя, данные об уровне событий внутри iframe или фрейма могут быть связаны с данными аукциона Protected Audience API и переданы на ваш сервер. Примеры данных об уровне событий включают показ объявления, клик, наведение курсора и любые другие события, происходящие внутри фрейма.

В момент конверсии, когда пользователь совершает какое-либо действие на странице перехода, которое связано с аукционом, данные об уровне события со страницы конверсии могут быть связаны с данными аукциона через API защищенной аудитории и переданы на ваш сервер.

Отчетность на уровне событий

Отчеты на уровне событий содержат подробную информацию об одном или нескольких событиях. Событием может быть выигрыш на аукционе, показ объявления или конверсия. По крайней мере до 2026 года отчеты о выигрышах на аукционах на уровне событий останутся в силе, для отображения объявлений в защищенной аудитории не потребуется использовать фреймы с ограниченным доступом к сети, а для отчетов на уровне событий можно использовать iframe с неограниченным доступом к сети. Кроме того, API отчетов по объявлениям доступен во фреймах и iframe, что позволяет связывать данные об аукционах и конверсиях с данными об уровне событий из фрейма. Это призвано упростить миграцию в экосистеме, поскольку вы можете продолжать использовать существующую инфраструктуру отчетности как минимум до 2026 года, пока ваша система переводится на защищенную аудиторию.

Отчеты о выигрышах на аукционах на уровне событий с помощью sendReportTo()

Механизмом для отправки данных на уровне событий внутри аукциона с защищенной аудиторией является sendReportTo() function при выигрыше в аукционе. Эта функция доступна в рабочих модулях для отправки отчетов покупателю и продавцу, и браузер отправляет GET запрос на указанную строку URL при начале показа рекламы. Вы можете закодировать любой сигнал, доступный в ваших рабочих модулях, в качестве параметров запроса URL.

Например, покупатель может сообщить сумму выигрышной ставки из рабочего процесса reportWin() для целей выставления счетов:

// Buyer reporting worklet
function reportWin(auctionSignals, perBuyerSignals, sellerSignals, browserSignals, directFromSellerSignals) {
  sendReportTo(`https://buyer-reporting-server.example/reporting?bid=${browserSignals.bid}`);
}

Функция sendReportTo() может использоваться для генерации отчета о выигрыше для продавца при вызове из reportResult() и отчета о выигрыше для покупателя при вызове из reportWin() . Функция sendReportTo() будет доступна как минимум до 2026 года .

Отчет о взаимодействии

Отчет об активности содержит данные на уровне событий из рекламного креатива, такие как данные о показах или кликах, связанные с сигналами аукциона Protected Audience API, которые привели к отображению объявления. Поскольку объявление отображается после завершения аукциона, сигналы аукциона недоступны внутри фрейма, в котором отображается объявление. Для сопоставления этих данных за разные периоды времени мы предлагаем два механизма перехода для создания отчетов об активности.

Описанная выше функция sendReportTo() может использоваться для сопоставления данных аукциона с данными уровня событий из iframe, но она не работает для огороженного фрейма, поскольку уникальный идентификатор не может быть передан из встраиваемого элемента, так как связь между встраиваемым элементом и огороженным фреймом ограничена. Для сопоставления данных аукциона с данными уровня событий из рекламного объявления в огороженном фрейме можно использовать API отчетов по рекламе .

API для отчетов по рекламе для фреймов и iframe-элементов.

API отчетов по рекламе для фреймов и iframe предоставляет механизм для сопоставления данных об уровне событий пользователя из рекламного фрейма с сигналами в рамках аукциона защищенной аудитории.

В модуле отчетности Protected Audience API вы можете зарегистрировать рекламный маяк с помощью функции registerAdBeacon() и передать URL-адрес отчета с сигналами, добавленными в качестве параметров запроса. Вы также указываете пользовательское событие, которое хотите связать с URL-адресом отчета. Затем, позже, когда реклама будет отображена в огороженном фрейме, вы можете запустить пользовательское событие, вызвав функцию window.fence.reportEvent() . Данные, доступные внутри огороженного фрейма, можно добавить в качестве полезной нагрузки.

Функция registerAdBeacon() доступна только в функциях формирования отчетов и недоступна в логике торгов покупателя и логике оценки продавца.

В следующем примере идентификатор кампании связан с данными уровня события, содержащими координаты кликов:

// Protected Audience API buyer win reporting worklet
function reportWin(auctionSignals) {
  const { campaignId } = auctionSignals

  registerAdBeacon({
    click: `https://buyer-server.example/report/click?campaignId=${campaignId}`
  })
}

// Protected Audience API seller reporting worklet
function reportResult(auctionConfig) {
  const { campaignId } = auctionConfig.auctionSignals;

  registerAdBeacon({
    click: `https://seller-server.example/report/click?campaignId=${campaignId}`
  })
}

// Ad frame
window.fence.reportEvent({
  eventType: 'click',
  eventData: JSON.stringify({'clickX': '123', 'clickY': '456'}),
  destination:['buyer', 'seller']
});

API для формирования отчетов по рекламе в рамках проекта Fenced Frames также будет доступен как минимум до 2026 года по тем же причинам, что и отчеты о выигрышах .

Для более подробной информации см. пояснение .

Неограниченный доступ к сети

Ограниченные фреймы позволяют загружать сетевые ресурсы так же, как и iframe, и вы можете отправлять данные уровня событий внутри ограниченных фреймов на свой сервер. Вы можете позже генерировать отчеты уровня событий на стороне сервера, связывая данные уровня событий из ограниченного фрейма с данными аукциона, отправленными с помощью sendReportTo() , которая обсуждалась в разделе о механизме отчетности уровня событий аукциона выше.

В будущем доступ к сети будет ограничен.

Отчет об атрибуции

Отчет по атрибуции позволяет связать конверсию на веб-сайте с рекламным объявлением, выбранным в рамках аукциона Protected Audience API. Например, пользователь может кликнуть на показанное вами рекламное объявление, перейти на сайт рекламодателя и совершить там покупку, и вас интересует, как эта покупка будет связана с показанным рекламным объявлением. API отчетов по атрибуции будет интегрирован с Protected Audience API для объединения данных аукциона с сайта издателя и данных о конверсиях с сайта рекламодателя.

Пока мы разрабатываем более постоянное решение, вы можете использовать API отчетов по рекламе для фреймов с ограждением в качестве переходного механизма для генерации отчетов на уровне событий и агрегируемых отчетов с помощью Attribution Reporting. Обратите внимание, что эти отчеты предназначены для измерения конверсий и отделены от отчетов об уровне событий и агрегируемых отчетов о вовлеченности, генерируемых аукционом и фреймом объявления. Мы опубликуем пояснение к более постоянному решению, когда оно будет готово.

Переходный механизм

При регистрации рекламного маяка можно использовать ключевое слово reserved.top_navigation , которое автоматически добавит заголовок Attribution-Reporting-Eligible , чтобы маяк мог быть зарегистрирован в качестве источника атрибуции .

registerAdBeacon({
 'reserved.top_navigation': 'https://adtech.example/click?buyer_event_id=123',
});

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

window.fence.setReportEventDataForAutomaticBeacons({
  eventType: 'reserved.top_navigation',
  eventData: 'data from the frame',
  destination:['seller', 'buyer']
})

Подробнее см. раздел «Отчеты по атрибуции» в пояснении к API отчетов по рекламе .

Пример отчета по вовлеченности и конверсии

В этом примере мы рассмотрим ситуацию с точки зрения покупателя, который заинтересован в объединении данных с аукциона, рекламного блока и сайта конверсии.

В этом рабочем процессе покупатель координирует свои действия с продавцом для отправки уникального идентификатора в аукцион. Во время аукциона покупатель отправляет этот уникальный идентификатор вместе с данными аукциона. Во время рендеринга и конвертации данные из рамочного окна или iframe также отправляются с тем же уникальным идентификатором. Впоследствии этот уникальный идентификатор можно использовать для связывания этих отчетов.

Рабочий процесс:

1. Перед началом аукциона покупатель отправляет продавцу уникальный идентификатор в рамках своего программного ответа на торги в режиме реального времени («RTB») . Идентификатор может быть установлен в качестве переменной, например, auctionId . Идентификатор передается в качестве perBuyerSignals в auctionConfig и становится доступным в рабочих модулях покупателя.
2. Во время аукциона покупатель может зарегистрировать рекламный маяк, который будет запускаться во время показа рекламы и совершения конверсии ( registerAdBeacon() ).
   1. Чтобы связать сигналы аукциона с событием рекламного фрейма, укажите auctionId в качестве параметра запроса URL-адреса маяка.
   2. Чтобы связать сигналы аукциона с событием конверсии, укажите auctionId в URL-адресе маяка.
3. Во время показа рекламы зарегистрированные вами во время аукциона маячки могут активироваться или дополняться данными на уровне событий.
   1. Инициируйте событие кадра с помощью reportEvent() и передайте данные уровня события.
   2. Добавьте полезную нагрузку уровня события в маяк атрибуции с помощью setReportEventDataForAutomaticBeacons()
   3. Зарегистрируйте объявление в API отчетов по атрибуции, отвечая на запросы рекламного маяка заголовком Attribution-Reporting-Register-Source .
4. В процессе конвертации вы можете активировать источник, зарегистрированный вами во время аукциона.

После выполнения описанной выше процедуры покупатель получит отчет об аукционе, отчет о взаимодействии и отчет о конверсии, объединенные одним уникальным ключом, который можно использовать для их сопоставления.

Аналогичный рабочий процесс применим и к продавцу, если ему необходим доступ к данным об атрибуции. Продавец также может использовать уникальный идентификатор для отправки данных с помощью registerAdBeacon() . В фрейме вызов reportEvent() содержит свойство назначения, которое можно использовать для отправки отчета как покупателю, так и продавцу. Обратите внимание, что SSP также должен присутствовать на целевой странице, чтобы триггер был отнесен к источнику.

Агрегирование данных о защищенной аудитории

API частной агрегации — это механизм, используемый для формирования сводного отчета на основе данных о защищенной аудитории. Сводный отчет представляет собой агрегированный отчет, содержащий неполную информацию и собранный в отдельные сегменты. Сегмент представляется ключом агрегации, и некоторая информация может быть закодирована в этом ключе.

Например, событие показа рекламы может быть распределено по различным группам, каждая из которых представляет собой отдельную рекламную кампанию. Сводный отчет отличается от отчета по отдельным событиям тем, что он не раскрывает информацию о каждом отдельном событии. В отчете по отдельным событиям можно определить, что пользователи A, B и C видели кампанию 123. В сводных отчетах можно измерить количество пользователей, которые видели кампанию 123, при этом добавляется шум для защиты конфиденциальности пользователей.

Более подробную информацию об API см. в статье «Частная агрегация ».

Агрегирование сигналов аукциона

Вы можете агрегировать сигналы, доступные в рамках рабочих модулей, на свой сервер, используя частную агрегацию. Для агрегации сигналов можно использовать метод privateAggregation.contributeToHistogram() , доступный в рабочем модуле для торгов покупателя, рабочем модуле для оценки продавцов и рабочем модуле для отчетов покупателей/продавцов.

В этом примере выигрышная заявка объединяется в категорию владельцев групп интересов:

function convertBuyerToBucket(igOwner) {}
function convertWinningBidToValue(winningBid) {}

function reportResult(auctionConfig, browserSignals) {
  privateAggregation.contributeToHistogram({
    bucket: convertBuyerToBucket(browserSignals.interestGroupOwner),
    value: convertWinningBidToValue(browserSignals.bid)
  });
} 

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

Агрегирование сигналов аукциона с данными о событиях.

Вы можете агрегировать сигналы аукциона с ограниченной информацией о событии, происходящем во фрейме объявления. Например, вы можете агрегировать количество кликов по объявлению в рамках кампании, создав группу, представляющую эту кампанию и событие клика. Обратите внимание, что во фрейме объявления вы можете указать, какое событие произошло, но вы не можете прикрепить полезную нагрузку на уровне события.

Для агрегирования сигналов аукциона по событиям можно использовать privateAggregation.contributeToHistogramOnEvent(eventType, contribution) , который принимает строку, указывающую тип события и сумму вклада, которая будет отражена в отчете при срабатывании этого события. Вы можете вызвать этот метод с пользовательским типом события, а затем вызвать window.fence.reportEvent(eventType) из рекламного фрейма, чтобы инициировать отправку отчета.

Допустим, вы хотите измерить, сколько кликов получило объявление в рамках рекламной кампании.

// Protected Audience API worklet
function getClickReportBucketForCampaign(campaignId) {
  // return a bucket for the campaign ID and the click event
}

function generateBid(interestGroup) {
  privateAggregation.contributeToHistogramOnEvent('click', {
    bucket: getClickReportBucketForCampaign(interestGroup.ads.metadata.campaignId), 
    value: 1
  });
}

В функции генерации ставок можно определить категорию как комбинацию идентификатора кампании и события клика, а затем увеличивать значение этой категории на 1 каждый раз, когда событие срабатывает.

// Ad frame
window.fence.reportEvent('click');

Затем, позднее, из рекламного фрейма вы можете инициировать отправку отчета, вызвав метод reportEvent(eventType) :

Узнайте больше о том, как инициировать взносы в частную агрегацию из фрейма в пояснительной записке .

Отчет о результатах и ​​эффективности аукциона.

Также можно агрегировать результаты аукциона при срабатывании события выигрыша или проигрыша с помощью contributeToHistogramOnEvent(eventType, contribution) , передав ключевые слова типа зарезервированного события ( reserved.win, reserved.loss и reserved.always ).

Функция «Частная агрегация» предоставляет список базовых значений, на основе которых можно рассчитать размер и стоимость вашего вклада. Доступные базовые значения для результатов аукциона включают в себя сумму ставки победившего объявления, сумму ставки, которая была оценена как вторая по величине, и причину отклонения ставки на аукционе.

Если указано базовое значение, например, сумма выигрышной ставки, вы можете указать, сколько нужно добавить или вычесть из этого значения, а затем сообщить итоговую сумму. Например, если в качестве базового значения указана выигрышная ставка в 5 долларов, вы можете вычесть свою ставку в 2 доллара, чтобы рассчитать фактическую сумму проигрыша на аукционе, равную 3 долларам.

Отчет о результатах аукциона

Рассмотрим пример, когда вы проиграли аукцион и хотите узнать, насколько ваша ставка отличалась от цены закрытия аукциона.

Чтобы узнать, на сколько вы проиграли аукцион, вы можете вычесть свою ставку из выигрышной ставки:

function generateBid() {
  const bid = calculateBidAmount();

  privateAggregation.contributeToHistogramOnEvent('reserved.loss', {
    bucket: getBucketForCampaign(interestGroup.ads.metadata.campaignId),
    value: {
      baseValue: 'winning-bid',
      scale: 1 // Scale the value to minimize noise-to-signal ratio 
      offset: -bid, // Numbers added to browser value after scaling 
    }
  });
}

После отправки отчета фактическое отображаемое значение будет представлять собой масштабированное baseValue , сдвинутое на величину offset . Для получения дополнительной информации см. пояснение .

Отчетность о результатах деятельности

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

Подробнее см. пояснение .

Хранение сигналов аукциона в общем хранилище.

Общее хранилище — это неразделённое и междоменное хранилище, в которое можно свободно записывать данные, но оно защищено шлюзами при чтении и обработке хранимых значений. Одним из доступных шлюзов для API общего хранилища является частная агрегация. Вы можете читать значения из общего хранилища только изнутри рабочего процесса, и вы можете сообщать об этих значениях, используя частную агрегацию из этого рабочего процесса.

Вы также можете записывать данные в общее хранилище из рабочих модулей Protected Audience API для торгов, оценки и отчетности. Позже вы можете передать эти значения из общего хранилища на свой сервер, используя частную агрегацию. Вы также можете использовать сохраненные значения для операции выбора URL-адреса .

Из рабочего модуля API защищенной аудитории вы можете записывать любые ключи и значения в общее хранилище:

// Protected Audience API worklet
function generateBid() {
  sharedStorage.set('test-bucket', 123);
}

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

// Shared Storage worklet
class SendReachReport{
  async run() {
    const testBucket = await this.sharedStorage.get('test-bucket');

    privateAggregation.contributeToHistogram({
      bucket: testBucket,
      value: 1
    });
  }
}

register('send-report', SendReachReport);

Чтобы узнать больше о Shared Storage, ознакомьтесь с разделом о Shared Storage в руководстве разработчика по отчетности Protected Audience API, пояснениями , демонстрацией в реальном времени и кодом демонстрации на GitHub .

Что дальше?

Мы хотим пообщаться с вами, чтобы убедиться, что мы создаем API, который будет работать для всех.

Обсудить API

Как и другие API Privacy Sandbox, этот API документирован и обсуждается публично .

Экспериментируйте с API

Вы можете экспериментировать и участвовать в обсуждении API Protected Audience.