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

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

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

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

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