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

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

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

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

Предложение Статус
Предотвратите недействительные отчеты Private Aggregation API с помощью проверки отчетов для общего хранилища
Объяснитель		 Доступно в Chrome
Доступность режима отладки частного агрегирования зависит от соответствия критериям 3PC.
Проблема с GitHub		 Доступен в хромированном цвете M119.
Сокращение задержки отчета
Объяснитель		 Доступен в хромированном цвете M119.
Тайм-аут вклада частной агрегации для общего хранилища
Объяснитель		 Доступен в исполнении M119.
Поддержка частного API агрегации и службы агрегации для Google Cloud
Объяснитель		 Доступен в хромированном цвете M121.
Заполнение полезных данных агрегированного отчета
Объяснитель		 Доступен в хромированном цвете M119.
Для отчетов аукционаReportBuyers доступен режим отладки частного агрегирования.
Объяснитель		 Доступен в хромированном цвете M123.
Поддержка фильтрации идентификаторов
Объяснитель		 Доступен в хромированном цвете M128.
Объединение вкладов на стороне клиента
Объяснитель		 Доступен в хромированном цвете M129.

Что такое 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, отчет можно будет отправить с помощью частного агрегирования.

Мультитач-атрибуция

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

С помощью 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';

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

Предыдущий пример кода будет вызывать частное агрегирование всякий раз, когда загружается межсайтовое содержимое 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() завершится ошибкой.

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

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

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

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

Например:

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

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

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

Пример рабочего процесса для проверки отчета

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

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

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

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

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

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

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