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

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

Одним из основных источников проблем с конфиденциальностью и безопасностью в сети является использование файлов cookie, установленных на стороннем контенте, встроенном в сайты (например, через <iframe> элементы). Эти файлы cookie могут использоваться для отслеживания и профилирования пользователей и обмена информацией между сайтами.

Для предотвращения отслеживания между сайтами браузеры стремятся разделить все типы хранения, включая Файлы cookie, Хранилище веб-страницы, IndexedDB и API кэширования. Однако основным препятствием для достижения этого является необходимость в нескольких законных вариантах использования, которые полагаются на совместный обмен информацией между сайтами. Примерами таких вариантов использования являются желание рекламодателей измерять охват своих объявлений по разным сайтам и составлять отчеты, а также желание владельцев сайтов настраивать пользовательский опыт на основе группы, к которой принадлежит пользователь, или его прошлых взаимодействий с сайтом.

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

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

Чтобы получить полезные результаты из worklet общего хранилища, необходимо использовать шлюз вывода. Эти шлюзы предназначены для конкретных целей, таких как выбор URL-адреса из предоставленного списка для отображения пользователю на основе данных общего хранилища. Результаты, предназначенные для пользователя, отображаются в безопасной среде fenced frame, к которой нет доступа с страницы встраивания.

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

Шлюз вывода Выбор URL-адреса, доступный через метод selectURL(), используется для выбора URL-адреса из предоставленного списка для отображения пользователю на основе данных общего хранилища. Этот шлюз можно использовать для следующих целей:

• Вращение креативов: Используйте сохранённые данные, такие как идентификаторы креативов, количество просмотров и взаимодействие пользователя, чтобы определить, какой креативный контент видит пользователь на разных сайтах. Этот подход помогает сбалансировать просмотры и предотвратить чрезмерное воздействие определённого контента, что, в свою очередь, может помочь избежать негативного пользовательского опыта.
• A/B-тестирование: Назначайте пользователя к группе экспериментов, затем сохраняйте данные о группе в общем хранилище для доступа между сайтами.
• Настраиваемый пользовательский опыт: Обменивайтесь настраиваемым контентом и призывами к действию, исходя из статуса регистрации пользователя или других состояний пользователя.

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

API частного агрегирования может использовать шлюз вывода «Запуск» для обработки данных общего хранилища и генерации агрегированных отчетов. Эти отчеты могут использоваться в следующих вариантах использования:

• Отчёт об уникальном охвате: Производители контента и рекламодатели часто хотят знать количество уникальных зрителей для своего контента. Вы можете использовать общее хранилище для отслеживания первого просмотра пользователем вашего объявления или встроенного материала и предотвращения двойного подсчёта для одного и того же пользователя на разных сайтах, что даст вам агрегированный шумный отчёт об приблизительном уникальном охвате.
• Отчёт о демографических данных пользователей: Производители контента часто хотят понять демографические данные своей аудитории. Вы можете использовать общее хранилище для записи демографических данных пользователя на вашем главном сайте и использовать агрегированные отчёты для отчётности о них на других сайтах во встроенных контекстах.
• Измерение частоты K+: Иногда описывается как «эффективная частота», K+ частота относится к минимальному количеству просмотров, необходимому до того, как пользователь распознает или вспомнит определённый контент (часто используется в контексте просмотров рекламы). Вы можете использовать общее хранилище для составления отчётов об уникальных пользователях, которые просмотрели фрагмент контента как минимум K раз.

Использование API общего хранилища состоит из двух частей — записи данных в хранилище и чтения/обработки их. Чтобы дать вам представление о том, как обрабатываются эти части, мы рассмотрим базовый пример A/B-тестирования из developer.chrome.com. В этом примере пользователю назначается группа эксперимента, а сведения о группе сохраняются в общем хранилище. Другие сайты могут использовать эти данные при выборе URL-адреса для отображения в fenced frame.

Запись данных в общее хранилище проста — вы используете методы, определённые в интерфейсе SharedStorage, чтобы установить, добавить или удалить/очистить данные.

Эта функциональность доступна в двух различных контекстах:

• В основном контексте просмотра, где работает ваш сайт или приложение, на WindowSharedStorage. Это доступно через window.sharedStorage.
• В контексте worklet общего хранилища, на WorkletSharedStorage. Это доступно через this.sharedStorage.

В нашем примере A/B-тестирования мы определяем функцию в контексте нашего приложения, которая генерирует случайное число — 0 или 1 — для представления группы эксперимента. Затем мы запускаем функцию window.sharedStorage.set(), чтобы назначить пользователю группу и сохранить результат в общем хранилище:

// Randomly assigns a user to a group 0 or 1
function getExperimentGroup() {
  return Math.round(Math.random());
}

async function injectContent() {
  // Assign user to a random group (0 or 1) and store it in shared storage
  window.sharedStorage.set("ab-testing-group", getExperimentGroup(), {
    ignoreIfPresent: true,
  });
}

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

Для использования выходной заслонки необходимо:

1. Определить операцию в скрипте модуля worklet для обработки выбора URL-адреса и зарегистрировать её.
2. Добавить модуль в модуль общего хранилища.
3. Выбрать URL-адрес с помощью операции worklet и загрузить его в ограниченную рамку.

Ниже мы рассмотрим эти шаги по одному.

Определение операции в модуле worklet

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

Операция выбора URL — это класс JavaScript, который должен следовать следующим правилам (эти правила различаются для каждой выходной заслонки в зависимости от их предполагаемого использования):

• Фактическая функциональность должна содержаться в асинхронном run() методе, который принимает в качестве первого параметра массив объектов, содержащих URL-адреса, а в качестве второго — объект данных (при вызове аргумент data является необязательным).
• Метод run() должен возвращать число, которое будет соответствовать номеру выбранного URL-адреса.

После определения операции необходимо зарегистрировать её с помощью SharedStorageWorkletGlobalScope.register().

// ab-testing-worklet.js
class SelectURLOperation {
  async run(urls, data) {
    // Read the user's experiment group from shared storage
    const experimentGroup = await this.sharedStorage.get("ab-testing-group");

    // Return the group number
    return experimentGroup;
  }
}

register("ab-testing", SelectURLOperation);

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

Добавление модуля в worklet общего хранилища

Для использования операции, определённой в модуле worklet, её необходимо добавить в worklet общего хранилища с помощью window.sharedStorage.worklet.addModule(). В главном контексте приложения это делается до установки значения группы эксперимента, чтобы оно было готово к использованию при необходимости:

async function injectContent() {
  // Add the module to the shared storage worklet
  await window.sharedStorage.worklet.addModule("ab-testing-worklet.js");

  // Assign user to a random group (0 or 1) and store it in shared storage
  window.sharedStorage.set("ab-testing-group", getExperimentGroup(), {
    ignoreIfPresent: true,
  });
}

Выбор URL-адреса и загрузка его в ограниченную рамку

Для выполнения операции, определённой в worklet, мы вызываем WindowSharedStorage.selectURL(). Этот метод выступает в качестве прокси для нашей операции worklet, безопасно обращаясь к ней и возвращая результат без утечки данных. selectURL() — это правильный метод для вызова нашей пользовательской операции worklet, поскольку она была определена с соответствующей структурой класса для операции выбора URL, как обсуждалось выше.

selectURL() ожидает массив объектов, содержащих URL-адреса для выбора, необязательный объект options и для того, чтобы основная операция возвращала целое число, которое может быть использовано для выбора URL-адреса.

// Run the URL selection operation
const fencedFrameConfig = await window.sharedStorage.selectURL(
  "ab-testing",
  [
    { url: `https://your-server.example/content/default-content.html` },
    { url: `https://your-server.example/content/experiment-content-a.html` },
  ],
  {
    resolveToConfig: true,
  },
);

Поскольку объект options содержит resolveToConfig: true, возвращаемый Promise будет разрешен с объектом FencedFrameConfig. Этот объект может быть установлен в качестве значения свойства HTMLFencedFrameElement.config, что приведет к отображению содержимого выбранного URL-адреса в соответствующем элементе <fencedframe>:

document.getElementById("content-slot").config = fencedFrameConfig;

Полный скрипт приложения выглядит следующим образом:

// Randomly assigns a user to a group 0 or 1
function getExperimentGroup() {
  return Math.round(Math.random());
}

async function injectContent() {
  // Add the module to the shared storage worklet
  await window.sharedStorage.worklet.addModule("ab-testing-worklet.js");

  // Assign user to a random group (0 or 1) and store it in shared storage
  window.sharedStorage.set("ab-testing-group", getExperimentGroup(), {
    ignoreIfPresent: true,
  });

  // Run the URL selection operation
  const fencedFrameConfig = await window.sharedStorage.selectURL(
    "ab-testing",
    [
      { url: `https://your-server.example/content/default-content.html` },
      { url: `https://your-server.example/content/experiment-content-a.html` },
    ],
    {
      resolveToConfig: true,
    },
  );

  // Render the chosen URL into a fenced frame
  document.getElementById("content-slot").config = fencedFrameConfig;
}

injectContent();

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

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

Еще одно важное различие между общим хранилищем и хранилищем веб-страниц заключается в том, что чтение из общего хранилища защищено (запись в хранилище ведёт себя аналогично). С localStorage и sessionStorage, вы можете свободно читать. С общим хранилищем чтение может происходить только внутри worklet общего хранилища, и источник, используемый для чтения в worklet, совпадает с контекстом просмотра, который его создал.

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

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

SharedStorage

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

WindowSharedStorage

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

WorkletSharedStorage

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

SharedStorageWorklet

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

SharedStorageWorkletGlobalScope

Представляет глобальную область видимости модуля SharedStorageWorklet. Он содержит функциональность для регистрации определённой операции и доступа к общему хранилищу.

SharedStorageOperation

Представляет базовый класс для всех типов операций выходных заслонок.

SharedStorageRunOperation

Представляет операцию выходной заслонки "Запуск".

SharedStorageSelectURLOperation

Представляет операцию выходной заслонки "Выбор URL".

Window.sharedStorage

Возвращает объект WindowSharedStorage для текущего источника.

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

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

chrome://flags/#privacy-sandbox-enrollment-overrides

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

• Общий хранилище на developers.google.com
• Песочница конфиденциальности на developers.google.com