Обзор API частного агрегирования

Создавайте сводные отчеты о данных, используя данные из Защищенной аудитории и межсайтовые данные из Общего хранилища.

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

Статус реализации

建议 状态
通过共享存储空间的报告验证防止无效的 Private Aggregation API 报告
说明者		 适用于 Chrome
不公开汇总调试模式的可用性取决于第三方 Cookie 的使用资格
GitHub 问题		 适用于 Chrome M119
缩短报告延迟时间
解说		 适用于 Chrome M119
支持适用于 Google Cloud 的 Private Aggregation API 和汇总服务
解说		 适用于 Chrome M121
可汇总报告载荷的内边距
解说		 适用于 Chrome M119
不公开汇总调试模式可用于 AuctionReportBuyers 报告使用
解说		 预计会在 Chrome M123 中提供
支持过滤 ID
解说		 预计会在 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 this.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 this.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) });

Проверка отчета

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

Функция доступна для тестирования в Chrome M114+. Проверка отчетов для API Protected Audience пока недоступна для тестирования.

Дополнительную информацию см. в пояснении к проверке отчета .

Привлекайте и делитесь отзывами

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