Основы API частной агрегации

Оптимизируйте свои подборки Сохраняйте и классифицируйте контент в соответствии со своими настройками.

Ключевые концепции API частной агрегации

Для кого предназначен этот документ?

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

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

Ключевые термины

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

• Ключ агрегации (также известный как ведро) — это предопределенный набор точек данных. Например, вы можете захотеть собрать ведро данных о местоположении, где браузер сообщает название страны. Ключ агрегации может содержать более одного измерения (например, страну и идентификатор вашего виджета контента).
• Агрегируемое значение — это отдельная точка данных, собранная в ключ агрегации. Если вы хотите измерить, сколько пользователей из Франции увидели ваш контент, то France — это измерение в ключе агрегации, а viewCount равный 1 — это агрегируемое значение.
• Агрегируемые отчеты генерируются и шифруются в браузере. Для API Private Aggregation это содержит данные об одном событии.
• Служба агрегации обрабатывает данные из агрегируемых отчетов для создания сводного отчета.
• Сводный отчет является конечным результатом работы службы агрегации и содержит обобщенные пользовательские данные и подробные данные о конверсиях.
• Worklet — это часть инфраструктуры, которая позволяет вам запускать определенные функции JavaScript и возвращать информацию обратно запрашивающей стороне. Внутри worklet вы можете выполнять JavaScript, но вы не можете взаимодействовать или общаться с внешней страницей.

Рабочий процесс частной агрегации

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

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

Рабочий процесс, описанный в этом разделе, похож на API Attribution Reporting . Однако Attribution Reporting связывает данные, собранные из события показа и события конверсии, которые происходят в разное время. Частная агрегация измеряет одно межсайтовое событие.

Ключ агрегации

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

Например, у вас может быть виджет, встроенный на нескольких сайтах, и вы хотите проанализировать страну пользователей, которые видели ваш виджет. Вы хотите ответить на такие вопросы, как «Сколько пользователей, которые видели мой виджет, из страны X?» Чтобы составить отчет по этому вопросу, вы можете настроить ключ агрегации, который кодирует два измерения: идентификатор виджета и идентификатор страны.

Ключ, предоставленный API Private Aggregation, — это BigInt , который состоит из нескольких измерений. В этом примере измерениями являются идентификатор виджета и идентификатор страны. Предположим, что идентификатор виджета может быть длиной до 4 цифр, например 1234 , а каждая страна сопоставляется с числом в алфавитном порядке, например Афганистан — 1 , Франция — 61 , а Зимбабве — 195 . Таким образом, агрегируемый ключ будет иметь длину 7 цифр, где первые 4 символа зарезервированы для WidgetID , а последние 3 символа — для CountryID .

Предположим, что ключ представляет собой количество пользователей из Франции (идентификатор страны 061 ), которые видели идентификатор виджета 3276 Ключ агрегации — 3276061 .

Ключ агрегации также может быть сгенерирован с помощью механизма хеширования, такого как SHA-256 . Например, строку {"WidgetId":3276,"CountryID":67} можно хешировать, а затем преобразовать в значение BigInt 42943797454801331377966796057547478208888578253058197330928948081739249096287n . Если значение хеш-функции имеет более 128 бит, вы можете усечь его, чтобы оно не превысило максимально допустимое значение сегмента 2^128−1 .

В рабочем лете Shared Storage вы можете получить доступ к модулям crypto и TextEncoder , которые могут помочь вам сгенерировать хэш. Чтобы узнать больше о генерации хэша, ознакомьтесь с SubtleCrypto.digest() на MDN .

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

async function convertToBucket(data) {
  // Encode as UTF-8 Uint8Array
  const encodedData = new TextEncoder().encode(data);

  // Generate SHA-256 hash
  const hashBuffer = await crypto.subtle.digest('SHA-256', encodedData);

  // Truncate the hash
  const truncatedHash = Array.from(new Uint8Array(hashBuffer, 0, 16));

  // Convert the byte sequence to a decimal
  return truncatedHash.reduce((acc, curr) => acc * 256n + BigInt(curr), 0n);
}

const data = {
  WidgetId: 3276,
  CountryID: 67
};

const dataString = JSON.stringify(data);
const bucket = await convertToBucket(dataString);

console.log(bucket); // 126200478277438733997751102134640640264n

Агрегируемая стоимость

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

Теперь вернемся к примеру вопроса, заданному ранее: «Сколько пользователей, которые видели мой виджет, находятся во Франции?» Ответ на этот вопрос будет выглядеть примерно так: «Примерно 4881 пользователь, которые видели мой идентификатор виджета 3276, находятся во Франции». Агрегируемое значение равно 1 для каждого пользователя, а «4881 пользователь» — это агрегированное значение , которое является суммой всех агрегируемых значений для этого ключа агрегации .

Для этого примера мы увеличиваем значение на 1 для каждого пользователя, который видит виджет. На практике агрегируемое значение можно масштабировать для улучшения соотношения сигнал/шум .

Бюджет взносов

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

При суммировании всех агрегируемых значений по всем ключам агрегации сумма должна быть меньше бюджета вклада. Бюджет ограничен источником ворклета, днем ​​и является отдельным для ворклетов Protected Audience API и Shared Storage. Для дня используется скользящее окно приблизительно за последние 24 часа. Если новый агрегируемый отчет приведет к превышению бюджета, отчет не создается.

Бюджет вклада представлен параметром L ₁ и установлен на 2 ¹⁶ (65 536) за десять минут в день с резервом 2 ²⁰ (1 048 576). См. пояснение , чтобы узнать больше об этих параметрах.

Значение бюджета вклада произвольно, но шум масштабируется к нему. Вы можете использовать этот бюджет, чтобы максимизировать отношение сигнал/шум для сводных значений (подробнее обсуждается в разделе Шум и масштабирование ).

Чтобы узнать больше о бюджетах взносов, см. пояснение . Также см. Бюджет взносов для получения дополнительных указаний.

Лимит вклада на отчет

В зависимости от вызывающего, лимит вклада может различаться, и для Shared Storage эти лимиты являются значениями по умолчанию, которые можно переопределить . В настоящее время отчеты, созданные для вызывающих API Shared Storage, ограничены 20 вкладами на отчет. С другой стороны, вызывающие API Protected Audience ограничены 100 вкладами на отчет. Эти лимиты были выбраны для балансировки количества вкладов, которые могут быть встроены, с размером полезной нагрузки.

Для Shared Storage вклады, сделанные в рамках одной операции run() или selectURL() группируются в один отчет. Для Protected Audience вклады, сделанные одним источником в рамках аукциона, группируются вместе.

Вклады с отступами

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

Агрегируемые отчеты

После того, как пользователь вызывает API Private Aggregation, браузер генерирует агрегируемые отчеты, которые будут обработаны Aggregation Service в более поздний момент времени для генерации сводных отчетов . Агрегируемый отчет имеет формат JSON и содержит зашифрованный список вкладов, каждый из которых представляет собой пару {aggregation key, aggregatable value} . Агрегируемые отчеты отправляются со случайной задержкой до одного часа.

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

Пример агрегируемого отчета с включенным режимом отладки :

  "aggregation_service_payloads": [
    {
      "debug_cleartext_payload": "omRkYXRhgaJldmFsdWVEAAAAgGZidWNrZXRQAAAAAAAAAAAAAAAAAAAE0mlvcGVyYXRpb25paGlzdG9ncmFt",
      "key_id": "2cc72b6a-b92f-4b78-b929-e3048294f4d6",
      "payload": "a9Mk3XxvnfX70FsKrzcLNZPy+00kWYnoXF23ZpNXPz/Htv1KCzl/exzplqVlM/wvXdKUXCCtiGrDEL7BQ6MCbQp1NxbWzdXfdsZHGkZaLS2eF+vXw2UmLFH+BUg/zYMu13CxHtlNSFcZQQTwnCHb"
    }
  ],
  "debug_key": "777",
  "shared_info": "{\"api\":\"shared-storage\",\"debug_mode\":\"enabled\",\"report_id\":\"5bc74ea5-7656-43da-9d76-5ea3ebb5fca5\",\"reporting_origin\":\"https://localhost:4437\",\"scheduled_report_time\":\"1664907229\",\"version\":\"0.1\"}"

Агрегированные отчеты можно просмотреть на странице chrome://private-aggregation-internals :

В целях тестирования можно использовать кнопку «Отправить выбранные отчеты» для немедленной отправки отчета на сервер.

Собирайте и создавайте пакетные агрегированные отчеты

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

• Для общего хранилища: /.well-known/private-aggregation/report-shared-storage
• Для защищенной аудитории: /.well-known/private-aggregation/report-protected-audience

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

Затем сервер должен пакетировать отчеты и отправлять пакет в Aggregation Service. Создавайте пакеты на основе информации, доступной в незашифрованной полезной нагрузке агрегируемого отчета, например, поля shared_info . В идеале пакеты должны содержать 100 или более отчетов на пакет.

Вы можете выбрать пакетирование на ежедневной или еженедельной основе. Эта стратегия гибкая, и вы можете изменить стратегию пакетирования для определенных событий, когда вы ожидаете большего объема — например, дней в году, когда ожидается больше показов. Пакеты должны включать отчеты из той же версии API, источника отчетов и запланированного времени отчета.

Фильтр идентификаторов

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

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

Шаги общего хранилища

Если вы используете API общего хранилища в своем потоке:

1. Определите, где вы будете объявлять и запускать ваш новый модуль Shared Storage. В следующем примере мы назвали файл модуля filtering-worklet.js , зарегистрированный в filtering-example .

   (async function runFilteringIdsExample () {
   await window.sharedStorage.worklet.addModule('filtering-worklet.js');
   await window.sharedStorage.run('filtering-example', {
     keepAlive: true,
     privateAggregationConfig: {
       contextId: 'example-id',
       filteringIdMaxBytes: 8 // optional
     }
   }});
   })();
   

   Обратите внимание, что filteringIdMaxBytes настраивается для каждого отчета и, если не установлено, по умолчанию принимает значение 1. Это значение по умолчанию предотвращает ненужное увеличение размера полезной нагрузки и, следовательно, затрат на хранение и обработку. Подробнее читайте в гибком объяснении вклада .

2. В filtering-worklet.js при передаче вклада в privateAggregation.contributeToHistogram(...) в рабочем лете Shared Storage можно указать идентификатор фильтрации.

   // Within  filtering-worklet.js
   class FilterOperation {
     async run() {
       let contributions = [{
         bucket: 1234n,
         value: 56,
         filteringId: 3n // defaults to 0n if not assigned, type bigint
       }];
   
       for (const c of contributions) {
         privateAggregation.contributeToHistogram(c);
       }
       …
   }
   });
   
   register('filtering-example', FilterOperation);
   

3. Агрегируемые отчеты будут отправлены туда, где вы определили конечную точку /.well-known/private-aggregation/report-shared-storage . Продолжайте следовать руководству по идентификаторам фильтрации, чтобы узнать об изменениях, необходимых в параметрах задания Aggregation Service.

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

Защищенные шаги аудитории

Если вы используете в своем потоке API защищенной аудитории :

1. В вашей текущей реализации Protected Audience вы можете установить следующее для подключения к Private Aggregation. В отличие от Shared Storage, пока невозможно настроить максимальный размер идентификатора фильтрации. По умолчанию максимальный размер идентификатора фильтрации составляет 1 байт и будет установлен на 0n . Имейте в виду, что они будут установлены в ваших функциях отчетности Protected Audience (например, reportResult() или generateBid() ).

   const contribution = {
     ...
     filteringId: 0n
   };
   
   privateAggregation.contributeToHistogram(contribution);
   

2. Агрегируемые отчеты будут отправлены туда, где вы определили конечную точку /.well-known/private-aggregation/report-protected-audience . После завершения пакетирования и отправки в развернутую службу агрегации ваши отфильтрованные результаты должны быть отражены в вашем окончательном сводном отчете. Доступны следующие пояснения для API Attribution Reporting и API Private Aggregation, а также первоначальное предложение.

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

Агрегация услуг

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

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

Сводные отчеты

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

Сводный отчет содержит набор пар ключ-значение в стиле словаря JSON. Каждая пара содержит:

• bucket : ключ агрегации как двоичная числовая строка. Если используемый ключ агрегации - "123", то bucket - "1111011".
• value : итоговое значение для заданной цели измерения, суммированное из всех доступных агрегируемых отчетов с добавленным шумом.

Например:

[
  {"bucket":` `"111001001",` `"value":` `"2558500"},
  {"bucket":` `"111101001",` `"value":` `"3256211"},
  {"bucket":` `"111101001",` `"value":` `"6536542"},
]

Шум и масштабирование

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

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

Например, предположим, что распределение шума имеет стандартное отклонение 100 и центрировано на нуле. Если собранное агрегируемое значение отчета (или «агрегируемое значение») составляет всего 200, то стандартное отклонение шума составит 50% от агрегированного значения. Но если агрегируемое значение равно 20 000, то стандартное отклонение шума составит всего 0,5% от агрегированного значения. Таким образом, агрегируемое значение 20 000 будет иметь гораздо более высокое отношение сигнал/шум.

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

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

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

Более подробную информацию см. в документации по бюджету взносов .

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

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

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