Документ: метод requestStorageAccessFor()

Метод requestStorageAccessFor() интерфейса Document позволяет сайтам верхнего уровня запрашивать доступ к сторонним файлам cookie от имени встраиваемого содержимого, происходящего с другого сайта в том же наборе связанных веб-сайтов. Он возвращает Promise, который выполняется, если доступ предоставлен, и отклоняется, если доступ запрещён.

requestedOrigin

Строка, представляющая URL источника, для которого запрашивается доступ к сторонним файлам cookie.

A Promise, который выполняется с undefined , если доступ к сторонним файлам cookie предоставлен, и отклоняется, если доступ запрещен.

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

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

InvalidStateError DOMException

Выбрасывается, если текущий Document еще не активен.

NotAllowedError DOMException

Выбрасывается, если:

• Окно документа не является безопасным контекстом.
• Документ не является документом верхнего уровня.
• Документ имеет null источник.
• Предоставленный requestedOrigin является непрозрачным.
• Сайты верхнего уровня и встраиваемые сайты не находятся в одном наборе связанных веб-сайтов.
• Встраиваемый <iframe> имеет ограничение, и токен allow-storage-access-by-user-activation не установлен.
• Использование заблокировано политикой storage-access Политики разрешений.
• Использование запрещено запросом пользователя на разрешение использования API.

TypeError

Выбрасывается, если requestedOrigin не является допустимым URL.

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

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

Чтобы проверить, было ли предоставлено разрешение на доступ к сторонним файлам cookie через requestStorageAccessFor(), можно вызвать Permissions.query(), указав имя функции "top-level-storage-access". Это отличается от имени функции, используемого для обычного метода Document.requestStorageAccess(), которое является "storage-access".

Вызов Permissions.query() должен указывать встраиваемый источник; например:

navigator.permissions.query({
  name: "top-level-storage-access",
  requestedOrigin: "https://www.example.com",
});

function rSAFor() {
  if ("requestStorageAccessFor" in document) {
    document.requestStorageAccessFor("https://example.com").then(
      (res) => {
        // Use storage access
        doThingsWithCookies();
      },
      (err) => {
        // Handle errors
      },
    );
  }
}

После успешного вызова requestStorageAccessFor(), запросы с другого сайта будут включать файлы cookie, если они включают CORS / crossorigin, поэтому сайты могут захотеть подождать перед запуском запроса. Такие запросы должны использовать опцию credentials: "include", а ресурсы должны включать атрибут crossorigin="use-credentials".

Например:

function checkCookie() {
  fetch("https://example.com/getcookies.json", {
    method: "GET",
    credentials: "include",
  })
    .then((response) => response.json())
    .then((json) => {
      // Do something
    });
}

• Document.hasStorageAccess(), Document.hasUnpartitionedCookieAccess(), Document.requestStorageAccess()
• Использование API доступа к хранилищу
• Введение в API доступа к хранилищу (блог WebKit)