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

Измерьте данные и результаты аукциона API Protected Audience API

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

Чтобы составить отчет о важных показателях, которые вы собираете на аукционе рекламы, API Protected Audience работает с:

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

Обзор отчетов API Protected Audience

Общий рабочий процесс защищенной аудитории
Общий рабочий процесс защищенной аудитории

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

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

Отчетные местоположения

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

Период времени Место назначения Расположение Доступные данные Доступны API отчетов
Аукцион Покупатель generateBid() Сигналы, результаты аукционов и эффективность аукционов API частного агрегирования
reportWin() API частного агрегирования
API отчетов по рекламе
Продавец scoreAd() API частного агрегирования
reportResult() API частного агрегирования
API отчетов по рекламе
Оказывать Покупатель/Продавец Рамка на сайте издательства Данные на уровне событий в рамках рекламного фрейма API частного агрегирования
API отчетов по рекламе
Конверсия Покупатель/Продавец Конверсионный сайт Данные о конверсиях и событиях с сайта конверсий. API отчетов по атрибуции
API частного агрегирования
API отчетов по рекламе

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

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

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

Сигналы

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

Сигнал Описание Установить местоположение Пользователи Доступность
аукционСигналы Данные доступны в контексте того, где проводится аукцион. Эти данные могут включать информацию о содержимом страницы, данные собственных пользователей и многое другое. Устанавливается продавцом с сайта издателя в конфиге аукциона. Покупатель
Продавец		 генерироватьОценку ставкиРекламный отчетОтчет о победеРезультат
ПрямойОтПродавцаСигналы Те же данные для auctionSignals , perBuyerSignals , sellerSignals , но сигналы гарантированно поступают от указанного продавца. Устанавливается через заголовки HTTP-ответа от продавца. Покупатель
Продавец		 генерироватьОценку ставкиРекламный отчетОтчет о победеРезультат
браузерСигналы Различные данные, предоставляемые браузером ( topWindowHostname , interestGroupOwner , renderUrl , adComponents , biddingDurationMsec , IGJoinCount , IGRecency , modelingSignals ). Устанавливается браузером. Покупатель
Продавец		 генерироватьОценку ставкиРекламный отчетОтчет о победеРезультат
продавецСигналы Сигналы, предоставляемые продавцу для оценки рекламы. Устанавливается продавцом с сайта издателя в конфиге аукциона. Продавец ОценкаОбъявление
отчетВыиграть
отчетРезультат
доверенныеScoringSignals Сигналы в реальном времени передаются продавцу для оценки рекламы. URL-адрес задается продавцом на сайте издателя в конфигурации аукциона. Продавец ОценкаОтчет по рекламеРезультат
perBuyerSignals Контекстные данные аукциона, предоставляемые конкретным покупателям. Продавец может получить стоимость для покупателей до начала аукциона. Это знание покупателя о рекламной возможности. Устанавливается продавцом с сайта издателя в конфиге аукциона. Покупатель генерироватьОценку ставкиРекламный отчетОтчет о победеРезультат
доверенные BiddingSignals Сигналы в режиме реального времени предоставляются покупателям для назначения ставок по рекламе. URL-адрес задается покупателем на сайте рекламодателя при настройке группы интересов. Покупатель генерировать ставку
userBiddingSignals Пользовательские данные предоставляет покупатель. Устанавливается покупателем на сайте рекламодателя при настройке группы интересов. Покупатель генерировать ставку

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

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

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

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

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

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

Во время конверсии, когда пользователь выполняет какое-либо действие на странице перехода, связанное с аукционом, данные уровня событий со страницы конверсии могут быть связаны с данными аукциона 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 года .

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

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

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

API отчетов по рекламе для изолированных фреймов и iframe

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

В рабочей программе отчетов API Protected Audience вы можете зарегистрировать рекламный маяк с помощью функции 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() , который обсуждался в разделе о механизме отчетов на уровне событий аукциона выше.

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

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

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

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

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

При регистрации рекламного маяка вы можете использовать ключевое слово 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) :

Узнайте больше о запуске вкладов Private Aggregation из кадра из объяснителя .

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

Вы также можете агрегировать результаты аукциона, вызванные событием выигрыша или проигрыша аукциона, с помощью 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 общего хранилища является частная агрегация. Вы можете считывать значения в общем хранилище только внутри рабочего листа и сообщать об этих значениях с помощью частного агрегирования из рабочего листа.

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

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

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

Позже вы можете загрузить ворлет общего хранилища, чтобы прочитать и отправить это значение с помощью Private Aggregation:

// 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);

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

Что дальше?

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

Обсудить API

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

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

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