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

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

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

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

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

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

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

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

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

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

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

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

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

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

  Подобно 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)
});

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

Вам необходимо создать ворлет для доступа к данным из общего хранилища. Для этого вызовите createWorklet() указав URL-адрес ворлета. По умолчанию при использовании общего хранилища с createWorklet() источником раздела данных будет источник вызывающего контекста просмотра , а не источник самого сценария ворлета.

Чтобы изменить поведение по умолчанию, установите свойство dataOrigin при вызове createWorklet .

• dataOrigin: "context-origin" : (по умолчанию) Данные хранятся в общем хранилище источника, вызывающего контекст просмотра.
• dataOrigin: "script-origin" : данные хранятся в общем хранилище источника сценария рабочего листа. Обратите внимание, что для включения этого режима требуется согласие.

sharedStorage.createWorklet(scriptUrl, {dataOrigin: "script-origin"});

Чтобы согласиться, при использовании "script-origin" конечная точка сценария должна будет ответить заголовком Shared-Storage-Cross-Origin-Worklet-Allowed . Обратите внимание, что CORS должен быть включен для запросов из разных источников.

Shared-Storage-Cross-Origin-Worklet-Allowed : ?1

Установка `dataOrigin` в `createWorklet()` и создание ворлетов из разных источников с помощью `addModule()` стали доступны в M130.

Использование iframe с перекрестным происхождением

Для вызова рабочего модуля общего хранилища необходим iframe.

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

const sharedStorageWorklet = await window.sharedStorage.createWorklet(
  'https://any-origin.example/modules/sharedStorageWorklet.js'
);
await sharedStorageWorklet.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,
      value
    });
  }
}
register('shared-storage-report', SharedStorageReportOperation);

Использование запроса между источниками

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

Собственная страница также может вызывать вызов createWorklet() для конечной точки javascript между источниками. При создании ворлета вам нужно будет установить начало раздела данных ворлета так же, как и в сценарии-начало.

async function crossOriginCall() {
  const privateAggregationWorklet = await sharedStorage.createWorklet(
    'https://cross-origin.example/js/worklet.js',
    { dataOrigin: 'script-origin' }
  );
  await privateAggregationWorklet.run('pa-worklet');
}
crossOriginCall();

Конечная точка javascript с несколькими источниками должна будет ответить заголовками Shared-Storage-Cross-Origin-Worklet-Allowed и отметить, что CORS включен для запроса.

Shared-Storage-Cross-Origin-Worklet-Allowed : ?1

Рабочие модули, созданные с помощью createWorklet() будут иметь selectURL и run() . addModule() для этого недоступен.

Примечание. addModule() можно использовать для создания рабочих модулей из разных источников. Однако использование createWorklet() предпочтительнее, поскольку оно позволяет создавать разделы данных из разных источников и может создавать несколько рабочих модулей в отличие от addModule() .

class CrossOriginWorklet {
  async run(data){
    // Other code goes here.
    bucket = getBucket(...);
    value = getValue(...);
    privateAggregation.contributeToHistogram({
      bucket,
      value
    });
  }
}

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

На следующих страницах объясняются важные аспекты 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.

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