Создавайте сводные отчеты о данных, используя данные из Защищенной аудитории и межсайтовые данные из Общего хранилища.
Чтобы обеспечить критически важные функции, на которые опирается Интернет, был создан API частного агрегирования для агрегирования и составления отчетов по межсайтовым данным с сохранением конфиденциальности.
Статус реализации
Предложение | Положение дел |
---|---|
Предотвратите недействительные отчеты Private Aggregation API с помощью проверки отчетов для общего хранилища Объяснитель | Доступно в Chrome |
Доступность режима отладки частного агрегирования зависит от соответствия критериям 3PC. Проблема с GitHub | Доступен в хромированном цвете M119. |
Сокращение задержки отчета Объяснитель | Доступен в хромированном цвете M119. |
Поддержка частного API агрегации и службы агрегации для Google Cloud Объяснитель | Доступен в хромированном цвете M121. |
Заполнение полезных данных агрегированного отчета Объяснитель | Доступен в хромированном цвете M119. |
Для отчетов аукционаReportBuyers доступен режим отладки частного агрегирования. Объяснитель | Ожидается в Chrome M123 |
Поддержка фильтрации идентификаторов Объяснитель | Ожидается в Chrome M128 |
Что такое API частной агрегации
API частной агрегации позволяет разработчикам создавать отчеты с агрегированными данными, используя данные из API защищенной аудитории и межсайтовые данные из общего хранилища .
Основная функция этого API известна как contributeToHistogram()
. Операция с гистограммой позволяет агрегировать данные по пользователям в каждом сегменте (известном в API как ключ агрегирования), который вы определяете. Вызов гистограммы накапливает значения и возвращает зашумленный агрегированный результат в форме сводного отчета. Например, в отчете может быть показано количество сайтов, на которых каждый пользователь видел ваш контент, или обнаружил ошибку в вашем стороннем скрипте. Эта операция выполняется в рамках ворлета другого API.
Например, если вы ранее записали демографические и географические данные в общее хранилище, вы можете использовать API частной агрегации для построения гистограммы, которая приблизительно показывает, сколько пользователей в Нью-Йорке видели ваш контент на разных сайтах. Для агрегирования этого измерения вы можете закодировать географическое измерение в ключ агрегирования и подсчитать пользователей в агрегируемом значении.
Ключевые понятия
Когда вы вызываете Private Aggregation API с ключом агрегации и агрегируемым значением, браузер генерирует агрегируемый отчет.
Агрегированные отчеты отправляются на ваш сервер для сбора и пакетной обработки. Пакетные отчеты позже обрабатываются службой агрегирования , и создается сводный отчет .
См. документ «Основы API частного агрегирования» , чтобы узнать больше о ключевых понятиях, связанных с API частного агрегирования.
Отличия от отчетов по атрибуции
API частного агрегирования имеет много общего с API отчетов по атрибуции . Отчеты об атрибуции – это отдельный API, предназначенный для измерения конверсий, тогда как частное агрегирование создано для межсайтовых измерений в сочетании с такими API, как API защищенной аудитории и общее хранилище. Оба API создают агрегированные отчеты, которые используются серверной частью службы агрегации для создания сводных отчетов.
Отчеты по атрибуции связывают данные, собранные в результате показа и события-конверсии, которые происходят в разное время. Частное агрегирование измеряет одно межсайтовое событие.
Протестируйте этот API
Чтобы протестировать API частного агрегирования локально, включите все API конфиденциальности рекламы в разделе chrome://settings/adPrivacy
.
Узнайте больше о тестировании в эксперименте и примите участие .
Используйте демо-версию
Демо-версию Private Aggregation API для общего хранилища можно найти по адресу goo.gle/shared-storage-demo , а код доступен на GitHub . Демо реализует операции на стороне клиента и создает сводный отчет, который отправляется на ваш сервер.
Демо-версия API частного агрегирования для API защищенной аудитории будет опубликована в будущем.
Варианты использования
Частное агрегирование — это API общего назначения для межсайтового измерения, который можно использовать в рабочих модулях API общего хранилища и защищенной аудитории . Первый шаг — решить, какую конкретно информацию вы хотите собрать. Эти точки данных являются основой ваших ключей агрегирования.
С общим хранилищем
Общее хранилище позволяет вам читать и записывать межсайтовые данные в безопасной среде, чтобы предотвратить утечку, а API частной агрегации позволяет измерять межсайтовые данные, хранящиеся в общем хранилище.
Уникальное измерение охвата
Возможно, вы захотите измерить, сколько уникальных пользователей просмотрели ваш контент. API частного агрегирования может дать ответ, например: «Приблизительно 317 уникальных пользователей просмотрели Content ID 861».
Вы можете установить флаг в общем хранилище, чтобы указать, видел ли пользователь контент или нет. При первом посещении, когда флаг не существует, выполняется вызов Private Aggregation, а затем устанавливается флаг. При последующих посещениях пользователя, включая посещения между сайтами, вы можете проверить общее хранилище и пропустить отправку отчета в Private Aggregation, если установлен флаг. Чтобы узнать больше о методах реализации этих измерений, ознакомьтесь с нашим техническим документом .
Демографические измерения
Возможно, вы захотите измерить демографические данные пользователей, которые видели ваш контент на разных сайтах.
Частное агрегирование может дать ответ, например: «Приблизительно 317 уникальных пользователей в возрасте от 18 до 45 лет из Германии». Используйте общее хранилище для доступа к демографическим данным из стороннего контекста. Позже вы можете создать отчет с помощью частного агрегирования, закодировав параметры возрастной группы и страны в ключе агрегирования.
К+ измерение частоты
Возможно, вы захотите измерить количество пользователей, которые видели часть контента или рекламу как минимум K раз в данном браузере, для заранее выбранного значения K.
Частное агрегирование может дать такой ответ: «Приблизительно 89 пользователей просмотрели Content ID 581 как минимум 3 раза». Счетчик можно увеличивать в общем хранилище с разных сайтов и читать внутри ворлета. Когда количество достигнет K, отчет можно будет отправить через частное агрегирование.
С помощью API защищенной аудитории
API Protected Audience позволяет использовать ретаргетинг и настраиваемую аудиторию, а Private Aggregation позволяет сообщать о событиях из рабочих листов покупателя и продавца. API можно использовать для таких задач, как измерение распределения аукционных ставок.
Из рабочего модуля API Protected Audience вы можете напрямую агрегировать свои данные с помощью contributeToHistogram()
и сообщать о своих данных на основе триггера с помощью contributeToHistogramOnEvent()
, который является специальным расширением для API Protected Audience.
Доступные функции
Следующие функции доступны в объекте privateAggregation
, доступном в рабочих модулях API общего хранилища и защищенной аудитории.
внести вклад в гистограмму()
Вы можете вызвать privateAggregation.contributeToHistogram({ bucket: <bucket>, value: <value> })
, где ключом агрегации является bucket
, а агрегируемое значение — value
. Для параметра bucket
требуется BigInt
. В качестве параметра value
требуется целое число.
Вот пример того, как его можно вызвать в общем хранилище для измерения охвата:
iframe.js
// Cross-site iframe code
async function measureReach() {
// Register worklet
await window.sharedStorage.worklet.addModule('worklet.js');
// Run reach measurement operation
await window.sharedStorage.run('reach-measurement', {
data: { contentId: '1234' }
});
}
measureReach();
worklet.js
// Shared storage worklet code
function convertContentIdToBucket(campaignId){
// Generate aggregation key
}
// The scale factor is multiplied by the aggregatable value to
// maximize the signal-to-noise ratio. See "Noise and scaling"
// section in the Aggregation Fundamentals document to learn more.
const SCALE_FACTOR = 65536;
class ReachMeasurementOperation {
async run(data) {
const key = 'has-reported-content';
// Read the flag from Shared Storage
const hasReportedContent = await sharedStorage.get(key) === 'true';
// Do not send report if the flag is set
if (hasReportedContent) {
return;
}
// Send histogram report
// Set the aggregation key in `bucket`
// Bucket examples: 54153254n or BigInt(54153254)
// Set the scaled aggregatable value in `value`
privateAggregation.contributeToHistogram({
bucket: convertContentIdToBucket(data.contentId),
value: 1 * SCALE_FACTOR
});
// Set the flag in Shared Storage
await sharedStorage.set(key, true);
}
}
register('reach-measurement', ReachMeasurementOperation);
В приведенном выше примере кода будет вызываться частное агрегирование всякий раз, когда загружается межсайтовое содержимое iframe. Код iframe загружает ворлет, а ворлет вызывает API частного агрегирования с идентификатором контента, преобразованным в ключ агрегации (корзину).
вкладToHistogramOnEvent()
Только в рабочих модулях API Protected Audience мы предоставляем триггерный механизм для отправки отчета только в случае возникновения определенного события. Эта функция также позволяет корзине и стоимости зависеть от сигналов, которые еще не доступны на данном этапе аукциона.
Метод privateAggregation.contributeToHistogramOnEvent(eventType, contribution)
принимает eventType
, который определяет инициирующее событие, а также contribution
, который должен быть отправлен при инициировании события. Событие, вызывающее срабатывание, может исходить из самого аукциона после его завершения (например, событие выигрыша или проигрыша на аукционе) или из огороженного фрейма, в котором отображалось объявление. Чтобы отправить отчет о событиях аукциона, вы можете использовать два зарезервированных ключевых слова: reserved.win
, reserved.loss
и reserved.always
. Чтобы отправить отчет, вызванный событием из изолированного фрейма, определите настраиваемый тип события. Чтобы вызвать событие из изолированного фрейма, используйте метод fence.reportEvent()
, доступный в API отчетов по рекламе в Fenced Frames .
В следующем примере отправляется отчет о показе, когда инициируется событие победы на аукционе, и отправляется отчет о клике, если событие click
инициируется из изолированного фрейма, в котором отображается объявление. Эти два значения можно использовать для расчета рейтинга кликов.
function generateBid(interestGroup, auctionSignals, perBuyerSignals, trustedBiddingSignals, browserSignals) {
// …
privateAggregation.contributeToHistogramOnEvent("reserved.win", {
bucket: getImpressionReportBucket(),
value: 1
});
privateAggregation.contributeToHistogramOnEvent("click", {
bucket: getClickReportBuckets(), // 128-bit integer as BigInt
value: 1
});
Дополнительную информацию см. в пояснении к расширенной частной агрегированной отчетности .
включитьDebugMode()
Хотя сторонние файлы cookie по-прежнему доступны, мы предоставим временный механизм, который позволит упростить отладку и тестирование, включив режим отладки. Отчет об отладке полезен для сравнения ваших измерений на основе файлов cookie с измерениями частного агрегирования, а также позволяет быстро проверить интеграцию API.
Вызов privateAggregation.enableDebugMode()
в рабочемлете включает режим отладки, который приводит к включению в агрегированные отчеты незашифрованных (открытых) полезных данных. Затем вы можете обработать эти полезные данные с помощью инструмента локального тестирования Aggregation Service.
Режим отладки доступен только вызывающим абонентам, которым разрешен доступ к сторонним файлам cookie. Если вызывающая сторона не имеет доступа к сторонним файлам cookie, enableDebugMode()
завершится ошибкой. Это означает, что, когда сторонние файлы cookie устареют, режим отладки больше не будет доступен.
Вы также можете установить ключ отладки, вызвав метод privateAggregation.enableDebugMode({ <debugKey: debugKey> })
где BigInt
можно использовать в качестве ключа отладки. Ключ отладки можно использовать для связывания данных измерений на основе файлов cookie и данных измерений частного агрегирования.
Их можно вызывать только один раз для каждого контекста. Любые последующие вызовы вызовут исключение.
// Enables debug mode
privateAggregation.enableDebugMode();
// Enables debug mode and sets a debug key
privateAggregation.enableDebugMode({ debugKey: BigInt(1234) });
Проверка отчета
В случае общего хранилища вы можете проверить достоверность полученных агрегированных отчетов , добавив идентификатор контекста в вызов операции общего хранилища. Идентификатор будет прикреплен к отправленному отчету, и позже вы сможете использовать этот идентификатор, чтобы убедиться, что отчет был отправлен из вашей операции общего хранилища.
Дополнительную информацию см. в пояснении к проверке отчета .
Привлекайте и делитесь отзывами
API частного агрегирования находится в стадии активного обсуждения и может быть изменен в будущем. Если вы попробуете этот API и у вас есть отзывы, мы будем рады их услышать.
- GitHub : читайте пояснение , задавайте вопросы и участвуйте в обсуждении .
- Поддержка разработчиков : задавайте вопросы и присоединяйтесь к обсуждениям в репозитории поддержки разработчиков Privacy Sandbox .
- Присоединяйтесь к группе API общего хранилища и группе API защищенной аудитории, чтобы быть в курсе последних объявлений, связанных с частной агрегацией.