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

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

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

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

Что такое API частного агрегирования?

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

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

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

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

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

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

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

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

API Private Aggregation имеет много общего с API Attribution Reporting . Attribution Reporting — это автономный API, предназначенный для измерения конверсий, тогда как Private Aggregation создан для межсайтовых измерений в сочетании с API, такими как Protected Audience API и Shared Storage. Оба API создают агрегируемые отчеты, которые используются бэкэндом Aggregation Service для создания сводных отчетов.

Attribution Reporting связывает данные, собранные из события показа и события конверсии, которые происходят в разное время. Private Aggregation измеряет одно межсайтовое событие.

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

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

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

Использовать демо

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

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

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

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

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

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

Измерение уникального охвата

Вы можете захотеть измерить, сколько уникальных пользователей увидели их контент. API Private Aggregation может предоставить ответ, например, «Примерно 317 уникальных пользователей увидели идентификатор контента 861».

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

Демографические измерения

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

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

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

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

Private Aggregation может дать ответ, например, «Примерно 89 пользователей видели идентификатор контента 581 не менее 3 раз». Счетчик может быть увеличен в Shared Storage с разных сайтов и может быть прочитан в рабочем лете. Когда счетчик достигнет K, отчет может быть отправлен с помощью Private Aggregation.

Атрибуция с несколькими касаниями

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

С API защищенной аудитории

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

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

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

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

внести вклад в гистограмму()

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

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

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 с идентификатором контента, преобразованным в ключ агрегации (bucket).

внести вклад в гистограмму по событию()

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

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

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

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

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

Режим отладки доступен только для вызывающих, которым разрешен доступ к сторонним куки. Если вызывающий не имеет доступа к сторонним куки, 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 Private Aggregation позволяет проводить межсайтовые измерения, защищая конфиденциальность пользователей. Однако злоумышленники могут попытаться манипулировать точностью этих измерений. Чтобы предотвратить это, вы можете использовать идентификатор контекста для проверки подлинности отчетов.

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

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

Совместное хранилище

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

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

Например:

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

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

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

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

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

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

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

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

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

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

• GitHub : прочитайте пояснение , задавайте вопросы и участвуйте в обсуждении .
• Поддержка разработчиков : задавайте вопросы и присоединяйтесь к обсуждениям в репозитории Privacy Sandbox Developer Support .
• Присоединяйтесь к группе API общего хранилища и группе API защищенной аудитории, чтобы быть в курсе последних объявлений, связанных с частной агрегацией.