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

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

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

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

Что такое API частной агрегации?

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

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

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

Ключевые понятия

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

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

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

Отличия от отчетности по атрибуции

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

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

Протестируйте этот API

Чтобы протестировать API частной агрегации локально, включите все API конфиденциальности рекламы в разделе chrome://settings/adPrivacy .

Узнайте больше о тестировании в эксперименте и примите участие .

Воспользуйтесь демо-версией

Демонстрационный пример Private Aggregation API для общего хранилища доступен по адресу goo.gle/shared-storage-demo , а код размещен на GitHub . Демонстрация реализует операции на стороне клиента и формирует агрегируемый отчет, который отправляется на ваш сервер.

Демонстрационная версия Private Aggregation API для Protected Audience API будет опубликована в будущем.

Варианты использования

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

С общим хранилищем

Shared Storage позволяет читать и записывать данные между сайтами в безопасной среде, предотвращая утечки, а Private Aggregation API позволяет измерять объем данных, хранящихся в Shared Storage, между сайтами.

Уникальное измерение досягаемости

Возможно, вам потребуется измерить, сколько уникальных пользователей просмотрели ваш контент. API частной агрегации может предоставить ответ, например: «Приблизительно 317 уникальных пользователей просмотрели контент с ID 861».

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

Измерение демографических данных

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

Функция частной агрегации может дать ответ, например: «Приблизительно 317 уникальных пользователей находятся в возрасте от 18 до 45 лет и проживают в Германии». Используйте общее хранилище для доступа к демографическим данным из стороннего источника. Позже вы можете создать отчет с помощью частной агрегации, закодировав возрастную группу и страну в ключе агрегации.

измерение частоты K+

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

Функция частной агрегации может выдать ответ, например: «Приблизительно 89 пользователей видели контент с ID 581 не менее 3 раз». Счетчик может увеличиваться в общем хранилище данных с разных площадок и считываться в рамках рабочего модуля. Когда счетчик достигнет K, можно отправить отчет, используя частную агрегацию.

Многосенсорная атрибуция

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

С помощью API защищенной аудитории

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

С помощью рабочего модуля Protected Audience API вы можете напрямую агрегировать данные, используя contributeToHistogram() , и формировать отчеты на основе триггера, используя contributeToHistogramOnEvent() , которая является специальным расширением для Protected Audience API.

Доступные функции

В объекте privateAggregation , доступном в рабочих модулях Shared Storage и Protected Audience API, доступны следующие функции.

contributeToHistogram()

Вы можете вызвать privateAggregation.contributeToHistogram({ bucket: <bucket>, value: <value> }) , где ключом агрегации является bucket , а значением, подлежащим агрегированию, — value . Для параметра bucket требуется тип BigInt . Для параметра value требуется тип integerNumber.

Вот пример того, как это может быть вызвано в Shared Storage для измерения охвата:

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';

    // Don't 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);

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

contributeToHistogramOnEvent()

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

Метод privateAggregation.contributeToHistogramOnEvent(eventType, contribution) принимает eventType , указывающий на событие, запускающее действие, и contribution которая должна быть внесена при срабатывании события. Событие, запускающее действие, может исходить от самого аукциона после его завершения, например, от события выигрыша или проигрыша на аукционе, или от фрейма, в котором было отображено объявление.

Для отправки отчета о событиях аукциона можно использовать два зарезервированных ключевых слова: reserved.win , reserved.loss и reserved.always . Для отправки отчета, запускаемого событием из фрейма с ограниченным доступом, определите пользовательский тип события. Для запуска события из фрейма с ограниченным доступом используйте метод fence.reportEvent() , доступный в API отчетов по объявлениям в фреймах с ограниченным доступом .

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

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

Подробнее см. в пояснительной статье о расширенной агрегированной отчетности для частных пользователей .

enableDebugMode()

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

Вызов метода privateAggregation.enableDebugMode() в рабочем модуле включает режим отладки, благодаря которому агрегируемые отчеты будут включать незашифрованные (в открытом виде) данные. Затем вы можете обрабатывать эти данные с помощью локального инструмента тестирования службы агрегации.

Режим отладки доступен только тем, кому разрешен доступ к сторонним файлам cookie. Если у вызывающей стороны нет доступа к сторонним файлам cookie, enableDebugMode() завершится с ошибкой.

Вы также можете установить ключ отладки, вызвав метод privateAggregation.enableDebugMode({ <debugKey: debugKey> }) , где в качестве ключа отладки можно использовать BigInt . Ключ отладки можно использовать для сопоставления данных из измерения на основе cookie и данных из измерения Private Aggregation.

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

// Enables debug mode
privateAggregation.enableDebugMode();

// Enables debug mode and sets a debug key
privateAggregation.enableDebugMode({ debugKey: BigInt(1234) });

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

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

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

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

Общее хранилище

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

Этот идентификатор встроен в отчет, созданный с помощью рабочего модуля. Вы можете указать его при вызове методов run() или selectURL() для общего хранилища в объекте options в ключе privateAggregationConfig .

Например:

sharedStorage.run('measurement-operation', {
  privateAggregationConfig: {
    contextId: 'exampleId123456789abcdeFGHijk'
  }
});

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

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

Пример рабочего процесса (как показано на диаграмме выше):

1. Операция «Общее хранилище» выполняется с конфигурацией «Частная агрегация», указывающей идентификатор контекста, и генерируется агрегируемый отчет.
2. Идентификатор контекста внедряется в сгенерированный сводный отчет, отправляемый на ваш сервер.
3. Ваш сервер собирает сгенерированные сводные отчеты.
4. Процессы на вашем сервере проверяют идентификатор контекста в каждом агрегируемом отчете на соответствие сохраненным идентификаторам контекста, чтобы убедиться в его корректности, прежде чем объединять отчеты в пакеты и отправлять их в вашу службу агрегации .

Проверка контекстного идентификатора

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

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

Принимайте участие и делитесь отзывами.

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

• GitHub : Прочитайте пояснение , задавайте вопросы и участвуйте в обсуждении .