Краткое руководство по внедрению общего хранилища и частного агрегирования

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

Целевая аудитория: рекламные технологии и поставщики аналитических услуг.

Попробуйте демо

Попробуйте живую демо-версию . Следуйте инструкциям в демонстрационных инструкциях, чтобы включить API Privacy Sandbox. Открытие Chrome DevTools поможет вам визуализировать результаты различных вариантов использования. Варианты использования, доступные в демо-версии:

• Частная агрегация
  • Уникальное измерение охвата
  • Демографические измерения
  • К+ измерение частоты
• Общее использование
  • Измерение события наведения курсора внутри огороженных рамок
  • Навигация верхнего уровня
  • Контроль того, где третьи лица могут писать

Как просмотреть общее хранилище

Чтобы просмотреть, что хранится в общем хранилище, используйте Chrome DevTools. Сохраненные данные можно найти в Application -> Shared Storage .

Просмотр отчетов для частного агрегирования

Чтобы просмотреть отправленные агрегированные отчеты, перейдите по адресу chrome://private-aggregation-internals . Когда режим отладки включен, отчет отправляется немедленно (без задержки) в [[YOUR_ORIGIN]]/.well-known/private-aggregation/debug/report-shared-storage вместе с отчетом с задержкой по времени, который будет отправлен в [[YOUR_ORIGIN]]/.well-known/private-aggregation/report-shared-storage .

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

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

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

Общее хранилище ограничено источником контекста (вызывающим объектом sharedStorage ).

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

Вызов общего хранилища

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

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

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

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

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

• Использование заголовков ответов

  Эта функция стала доступна в M119.

  Подобно JavaScript, с помощью заголовков ответов можно выполнять только определенные функции, такие как установка, добавление и удаление значений в общем хранилище. Чтобы работать с общим хранилищем в заголовке ответа, в заголовок запроса необходимо включить Shared-Storage-Writable: ?1 .

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

  • Использование fetch()

    fetch("https://a.example/path/for/updates", {sharedStorageWritable: true});
    

  • Использование тега iframe или img

    <iframe src="https://a.example/path/for/updates" sharedstoragewritable></iframe>
    

  • Использование атрибута IDL с тегом iframe или img

    let iframe = document.getElementById("my-iframe");
    iframe.sharedStorageWritable = true;
    iframe.src = "https://a.example/path/for/updates";
    

Дополнительную информацию можно найти в разделе Общее хранилище: заголовки ответов .

Запись в общее хранилище

Чтобы выполнить запись в общее хранилище, вызовите sharedStorage.set() изнутри или снаружи ворлета JavaScript. При вызове извне ворлета данные записываются в источник контекста просмотра, из которого был выполнен вызов. При вызове изнутри ворлета данные записываются в источник контекста просмотра, который загрузил ворлет. Установленные ключи имеют срок действия 30 дней с момента последнего обновления.

Поле ignoreIfPresent является необязательным. Если он присутствует и имеет значение true , ключ не обновляется, если он уже существует. Срок действия ключа продлевается до 30 дней с момента вызова set() , даже если ключ не обновляется.

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

• Использование JavaScript

  Вне рабочего листа:

  window.sharedStorage.set('myKey', 'myValue1', { ignoreIfPresent: true });
  // Shared Storage: {'myKey': 'myValue1'}
  window.sharedStorage.set('myKey', 'myValue2', { ignoreIfPresent: true });
  // Shared Storage: {'myKey': 'myValue1'}
  window.sharedStorage.set('myKey', 'myValue2', { ignoreIfPresent: false });
  // Shared Storage: {'myKey': 'myValue2'}
  

  Аналогично внутри ворлета:

  sharedStorage.set('myKey', 'myValue1', { ignoreIfPresent: true });
  

• Использование заголовков ответов

  Вы также можете писать в общее хранилище, используя заголовки ответов. Для этого используйте Shared-Storage-Write в заголовке ответа вместе со следующими командами:

  Shared-Storage-Write : set;key="myKey";value="myValue";ignore_if_present
  

  Shared-Storage-Write : set;key="myKey";value="myValue";ignore_if_present=?0
  

  Несколько элементов могут быть разделены запятыми и могут сочетать set , append , delete clear .

  Shared-Storage-Write : 
  set;key="hello";value="world";ignore_if_present, set;key="good";value="bye"
  

Добавление значения

Вы можете добавить значение к существующему ключу, используя метод добавления. Если ключ не существует, вызов метода append() создает ключ и устанавливает значение. Это можно сделать с помощью JavaScript или заголовков ответов.

• Использование JavaScript

  Чтобы обновить значения существующих ключей, используйте sharedStorage.append() внутри или снаружи ворлета.

  window.sharedStorage.append('myKey', 'myValue1');
  // Shared Storage: {'myKey': 'myValue1'}
  window.sharedStorage.append('myKey', 'myValue2');
  // Shared Storage: {'myKey': 'myValue1myValue2'}
  window.sharedStorage.append('anotherKey', 'hello');
  // Shared Storage: {'myKey': 'myValue1myValue2', 'anotherKey': 'hello'}
  

  Чтобы добавить внутрь ворлета:

  sharedStorage.append('myKey', 'myValue1');
  

• Использование заголовков ответов

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

  Shared-Storage-Write : append;key="myKey";value="myValue2"
  

Чтение из общего хранилища

Чтение из общего хранилища можно выполнять только внутри ворлета.

await sharedStorage.get('mykey');

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

Удаление из общего хранилища

Удаление из общего хранилища можно выполнять с помощью JavaScript как внутри, так и за пределами ворлета, а также с помощью заголовков ответов с помощью delete() . Чтобы удалить все ключи одновременно, используйте clear() для любого из них.

• Использование JavaScript

  Чтобы удалить из общего хранилища за пределами ворлета:

  window.sharedStorage.delete('myKey');
  

  Чтобы удалить из общего хранилища изнутри ворлета:

  sharedStorage.delete('myKey');
  

  Чтобы удалить все ключи одновременно за пределами ворлета:

  window.sharedStorage.clear();
  

  Чтобы удалить все ключи одновременно из ворлета:

  sharedStorage.clear();
  

• Использование заголовков ответов

  Чтобы удалить значения с помощью заголовков ответа, вы также можете использовать Shared-Storage-Write в заголовке ответа, чтобы передать удаляемый ключ.

  delete;key="myKey"
  

  Чтобы удалить все ключи с помощью заголовков ответа:

  clear;
  

Переключение контекста

Данные общего хранилища записываются в источник (например, https://example.adtech.com) контекста просмотра, из которого произошел вызов.

Когда вы загружаете сторонний код с помощью тега <script> , код выполняется в контексте просмотра средства внедрения. Таким образом, когда сторонний код вызываетsharedStorage.set sharedStorage.set() , данные записываются в общее хранилище внедряющего устройства. Когда вы загружаете сторонний код в iframe, код получает новый контекст просмотра, и его источником является источник iframe. Таким образом, вызов sharedStorage.set() , сделанный из iframe, сохраняет данные в общем хранилище источника iframe.

Собственный контекст

Если на собственной странице есть встроенный сторонний код JavaScript, который вызывает sharedStorage.set() или sharedStorage.delete() , пара ключ-значение сохраняется в собственном контексте.

Сторонний контекст

Пара ключ-значение может быть сохранена в рекламной технологии или стороннем контексте, создав iframe и вызвав set() или delete() в коде JavaScript изнутри iframe.

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

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

Чтобы создать отчет, вызовите contributeToHistogram() внутри ворлета с сегментом и значением. Сегмент представлен 128-битным целым числом без знака, которое необходимо передать в функцию как BigInt . Значение представляет собой положительное целое число.

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

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

privateAggregation.contributeToHistogram({
  bucket: BigInt(myBucket),
  value: parseInt(myBucketValue)
});

Выполнение общего хранилища и частной агрегации

В iframe объявления загрузите модуль ворлета, вызвав addModule() . Чтобы запустить метод, зарегистрированный в рабочем файле sharedStorageWorklet.js , в том же JavaScript-коде iframe вызовите sharedStorage.run() .

await window.sharedStorage.worklet.addModule('modules/sharedStorageWorklet.js');
await window.sharedStorage.worklet.run('shared-storage-report', {
  data: { campaignId: '1234' },
});

В сценарии ворлета вам нужно будет создать класс с методом асинхронного run . И register этот класс для запуска в iframe объявления. Внутри sharedStorageWorklet.js :

class SharedStorageReportOperation {
  async run(data) {
    // Other code goes here.
    bucket = getBucket(...);
    value = getValue(...);
    privateAggregation.contributeToHistogram({
      bucket: bucket,
      value: value
    });
  }
}
register('shared-storage-report',
  SharedStorageReportOperation);

Отладка

Чтобы включить отладку, вызовите метод JavaScript enableDebugMode() в том же контексте, где используется общее хранилище и частное агрегирование. Это будет применяться к будущим отчетам в том же контексте.

privateAggregation.enableDebugMode();

Чтобы связать отчеты с контекстами, которые их инициировали, вы можете установить ключ отладки 64-битного целого числа без знака, который передается в вызов JavaScript. debugKey — это BigInt .

privateAggregation.enableDebugMode({debugKey: 1234});

Отладка общего хранилища

Общее хранилище возвращает общее сообщение об ошибке:

Promise is rejected without and explicit error message

Вы можете отладить общее хранилище, обернув вызовы блоками try-catch .

try {
  privateAggregation.contributeToHistogram({bucket, value});
} catch (e){
  console.log(e);
}

Отладка частной агрегации

Отчеты отправляются в /.well-known/private-aggregation/report-shared-storage и /.well-known/private-aggregation/debug/report-shared-storage . Отчеты об отладке получают полезную нагрузку, аналогичную следующему JSON. Эта полезная нагрузка определяет поле api как «shared-storage».

{
   "aggregation_coordinator_identifier": "aws-cloud",
   "aggregation_service_payloads": [ {
      "debug_cleartext_payload": "omRkYXRhgaJldmFsdWVEAAAAgGZidWNrZXRQAAAAAAAAAAAAAAEfV32BFWlvcGVyYXRpb25paGlzdG9ncmFt",
      "key_id": "9bc4afa7-2934-4779-99ff-999d91b137ec",
      "payload": "bqOFO/cHCdwefU2W4FjMYRMSLoGHPWwZbgVF4aa/ji2YtwFz+jb6v2XCwQUdmvYcZSRPKosGRpKELJ0xAFv+VBYvCiv3FXP6jjAHQD+XAJUz17A39aXijk6JnEAu86+DfTSbXYn1fWhGzIG9xH/Y"
   } ],
   "debug_key": "1234",
   "shared_info": "{\"api\":\"shared-storage\",\"debug_mode\":\"enabled\",\"report_id\":\"93f86829-cdf7-4ecd-b16d-4e415a3ee063\",\"reporting_origin\":\"https://small-free-wealth.glitch.me\",\"scheduled_report_time\":\"1681319668\",\"version\":\"0.1\"}"
}

Отладка полезных данных открытого текста

debug_cleartext_payload имеет кодировку Base64 CBOR . Вы можете просмотреть сегмент и значение с помощью декодера или использовать код JavaScript, найденный в декодере общего хранилища .

Следующие шаги

На следующих страницах объясняются важные аспекты API общего хранилища и частного агрегирования.

• Введение в общее хранилище (для разработчиков Chrome)
• Варианты использования общего хранилища (для разработчиков Chrome)
• Введение в частное агрегирование (для разработчиков Chrome)
• Объяснение общего хранилища (GitHub)
• Объяснение частного агрегирования (GitHub)
• Демонстрация общего хранилища и частной агрегации

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

• Отчеты об отладке — context-origin/.well-known/private-aggregation/debug/report-shared-storage
• Отчеты – context-origin/.well-known/private-aggregation/report-shared-storage

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

Поделитесь своим отзывом

Вы можете поделиться своими отзывами об API и документации на GitHub.

• Общее хранилище
• Частная агрегация