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

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

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

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

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

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

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

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

Ключевые концепции

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

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

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

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

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

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

Протестируйте этот 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 частного агрегирования может предоставить ответ, например: «Примерно 317 уникальных пользователей просмотрели контент с идентификатором 861».

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Вы можете вызвать 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);

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

ВнестиГистограммуВСобытие()

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

Метод 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() в ворклете включает режим отладки, который позволяет включать незашифрованные (открытые) полезные данные в агрегируемые отчёты. Затем эти полезные данные можно обработать с помощью локального инструмента тестирования Aggregation Service.

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

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

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

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

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

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

Например:

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

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

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

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

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

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

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

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

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

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

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