Document : méthode requestStorageAccessFor()

Syntaxe

requestStorageAccessFor(requestedOrigin)

Paramètres

requestedOrigin

Une chaîne de caractères représentant l'URL de l'origine pour laquelle vous demandez l'accès aux cookies tiers.

Valeur de retour

Une promesse (Promise) qui se résout avec undefined si l'accès aux cookies tiers a été accordé et se rejette si l'accès a été refusé.

Les requêtes à requestStorageAccessFor() sont automatiquement refusées sauf si le contenu de niveau supérieur traite actuellement un geste utilisateur·ice comme un appui ou un clic (activation transitoire), ou si l'autorisation a déjà été accordée précédemment. Si l'autorisation n'a pas été accordée auparavant, elles doivent être exécutées dans un gestionnaire d'évènement basé sur un geste utilisateur·ice. Le comportement du geste utilisateur·ice dépend de l'état de la promesse :

• Si la promesse est résolue (c'est-à-dire si l'autorisation a été accordée), alors le geste utilisateur·ice n'a pas été consommé, donc le script peut ensuite appeler des API qui nécessitent un geste utilisateur·ice.
• Si la promesse est rejetée (c'est-à-dire si l'autorisation n'a pas été accordée), alors le geste utilisateur·ice a été consommé, donc le script ne peut rien faire qui nécessite un geste. Cela empêche les scripts d'appeler requestStorageAccessFor() à nouveau si l'autorisation est refusée.

Exceptions

InvalidStateError DOMException

Levée si le Document actuel n'est pas encore actif.

NotAllowedError DOMException

Levée si :

• La fenêtre du document n'est pas un contexte sécurisé.
• Le document n'est pas le document de niveau supérieur.
• Le document a une origine null.
• L'origine fournie requestedOrigin est opaque ^(angl.).
• Les sites de niveau supérieur et intégrés ne sont pas dans le même ensemble de sites liés.
• Le <iframe> intégré est sandboxé, et le jeton allow-storage-access-by-user-activation n'est pas défini.
• L'utilisation est bloquée par une politique d'autorisations storage-access.
• L'utilisation est refusée par la demande d'autorisation de l'agent utilisateur pour utiliser l'API.

TypeError

Levée si requestedOrigin n'est pas une URL valide.

Description

La méthode requestStorageAccessFor() répond aux défis liés à l'adoption de l'API Storage Access sur les sites de niveau supérieur qui utilisent des images ou des scripts inter-sites nécessitant des cookies. Elle concerne les agents utilisateurs qui, par défaut, bloquent l'accès aux cookies tiers, non compartimentés pour améliorer la confidentialité (par exemple, pour empêcher le pistage), et constitue une extension proposée de l'API Storage Access.

requestStorageAccessFor() peut permettre l'accès aux cookies tiers pour des ressources inter-sites directement intégrées dans un site de niveau supérieur qui ne peuvent pas demander elles-mêmes l'accès au stockage, par exemple des éléments HTML <img>. Le contenu inter-site intégré dans des <iframe> qui possède sa propre logique et ses propres ressources et nécessite l'accès aux cookies tiers doit demander l'accès au stockage en appelant Document.requestStorageAccess().

Pour vérifier si l'autorisation d'accéder aux cookies tiers a déjà été accordée en appelant requestStorageAccessFor(), vous pouvez appeler Permissions.query() en définissant le nom de la fonctionnalité à "top-level-storage-access". Cela diffère du nom de fonctionnalité utilisé pour la méthode régulière Document.requestStorageAccess(), qui est "storage-access".

L'appel à Permissions.query() doit définir l'origine intégrée :

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

Exemples

function rSAFor() {
  if ("requestStorageAccessFor" in document) {
    document.requestStorageAccessFor("https://exemple.com").then(
      (res) => {
        // Utiliser l'accès au stockage
        faireUnTrucAvecLesCookies();
      },
      (err) => {
        // Gérer les erreurs
      },
    );
  }
}

Après un appel réussi à requestStorageAccessFor(), les requêtes inter-sites incluront les cookies si elles incluent CORS / crossorigin, donc les sites peuvent vouloir attendre avant de déclencher une requête. Ces requêtes doivent utiliser l'option credentials: "include" et les ressources doivent inclure l'attribut crossorigin="use-credentials".

Par exemple :

function checkCookie() {
  fetch("https://exemple.com/getcookies.json", {
    method: "GET",
    credentials: "include",
  })
    .then((response) => response.json())
    .then((json) => {
      // Faire quelque chose
    });
}

Spécifications

Compatibilité des navigateurs

Voir aussi

• Les méthodes Document.hasStorageAccess(), Document.hasUnpartitionedCookieAccess(), Document.requestStorageAccess()
• Utiliser l'API d'accès au stockage
• Introduction à l'API d'accès au stockage ^(angl.) (Blog WebKit)