chrome.contentSettings

Description

Utilisez l'API chrome.contentSettings pour modifier les paramètres qui déterminent si les sites Web peuvent utiliser des fonctionnalités telles que des cookies, du code JavaScript et des plug-ins. Plus généralement, les paramètres de contenu vous permettent de personnaliser le comportement de Chrome par site plutôt que de manière globale.

Autorisations

contentSettings

Pour utiliser l'API, vous devez déclarer l'autorisation "contentSettings" dans le fichier manifeste de votre extension. Exemple :

{
  "name": "My extension",
  ...
  "permissions": [
    "contentSettings"
  ],
  ...
}

Concepts et utilisation

Modèles de paramètres de contenu

Vous pouvez utiliser des modèles pour spécifier les sites Web concernés par chaque paramètre de contenu. Par exemple, https://*.youtube.com/* spécifie youtube.com et tous ses sous-domaines. La syntaxe des modèles de paramètres de contenu est la même que celle des modèles de correspondance, à quelques différences près:

  • Pour les URL http, https et ftp, le chemin doit être un caractère générique (/*). Pour les URL file, le chemin doit être complètement spécifié et ne doit pas contenir de caractères génériques.
  • Contrairement aux modèles de correspondance, les modèles de paramètres de contenu peuvent spécifier un numéro de port. Si vous spécifiez un numéro de port, le format ne correspond qu'aux sites Web associés à ce port. Si aucun numéro de port n'est spécifié, le format correspond à tous les ports.

Priorité des modèles

Lorsqu'une règle de paramètre de contenu s'applique à un site donné, la règle avec le modèle le plus spécifique prévaut.

Par exemple, les modèles suivants sont classés par ordre de priorité:

  1. https://www.example.com/*
  2. https://*.example.com/* (correspond à example.com et à tous les sous-domaines)
  3. <all_urls> (correspond à toutes les URL)

Trois types de caractères génériques affectent le niveau de spécificité d'un modèle:

  • Caractères génériques dans le port (par exemple, https://www.example.com:*/*)
  • Caractères génériques dans le schéma (par exemple, *://www.example.com:123/*)
  • Caractères génériques dans le nom d'hôte (par exemple, https://*.example.com:123/*)

Si un modèle est plus spécifique qu'un autre dans une partie, mais moins spécifique dans une autre, les différentes parties sont vérifiées dans l'ordre suivant: nom d'hôte, schéma, port. Par exemple, les modèles suivants sont classés par ordre de priorité:

  1. https://www.example.com:*/* Spécifie le nom d'hôte et le schéma.
  2. *:/www.example.com:123/* Moins élevé, car bien qu'il spécifie le nom d'hôte, il ne spécifie pas le schéma.
  3. https://*.example.com:123/* inférieur, car bien qu'il spécifie le port et le schéma, il comporte un caractère générique dans le nom d'hôte.

Modèles principaux et secondaires

L'URL prise en compte pour déterminer le paramètre de contenu à appliquer dépend du type de contenu. Par exemple, pour contentSettings.notifications, les paramètres sont basés sur l'URL affichée dans la barre d'adresse. Cette URL est appelée "principale".

Certains types de contenus peuvent prendre en compte des URL supplémentaires. Par exemple, la possibilité pour un site d'utiliser un contentSettings.cookies est déterminée en fonction de l'URL de la requête HTTP (qui est l'URL principale dans ce cas) ainsi que de l'URL affichée dans la barre omnibox (appelée URL "secondaire").

Si plusieurs règles comportent des modèles principaux et secondaires, la règle avec le modèle principal le plus spécifique prévaut. Si plusieurs règles ont le même modèle principal, la règle avec le modèle secondaire le plus spécifique est prioritaire. Par exemple, la liste suivante de paires de modèles primaires/secondaires est triée par ordre de priorité:

PrioritéModèle principalModèle secondaire
1https://www.moose.com/*,https://www.wombat.com/*
2https://www.moose.com/*,<all_urls>
3<all_urls>,https://www.wombat.com/*
4<all_urls>,<all_urls>

Les modèles secondaires ne sont pas compatibles avec le paramètre de contenu des images.

Identifiants de ressource

Les identifiants de ressources vous permettent de spécifier des paramètres de contenu pour des sous-types spécifiques d'un type de contenu. Actuellement, le seul type de contenu compatible avec les identifiants de ressources est contentSettings.plugins, où un identifiant de ressource identifie un plug-in spécifique. Lorsque vous appliquez des paramètres de contenu, les paramètres du plug-in spécifique sont d'abord vérifiés. Si aucun paramètre n'est trouvé pour le plug-in spécifique, les paramètres de contenu généraux des plug-ins sont vérifiés.

Par exemple, si une règle de paramètre de contenu comporte l'identifiant de ressource adobe-flash-player et le modèle <all_urls>, elle prévaut sur une règle sans identifiant de ressource et le modèle https://www.example.com/*, même si ce modèle est plus spécifique.

Vous pouvez obtenir la liste des identifiants de ressources pour un type de contenu en appelant la méthode contentSettings.ContentSetting.getResourceIdentifiers(). La liste renvoyée peut changer en fonction de l'ensemble des plug-ins installés sur la machine de l'utilisateur, mais Chrome essaie de maintenir les identifiants stables entre les mises à jour des plug-ins.

Exemples

Pour essayer cette API, installez l'exemple d'API contentSettings à partir du dépôt chrome-extension-samples.

Types

AutoVerifyContentSetting

Chrome 113 ou version ultérieure

Énumération

"allow"

"block"

CameraContentSetting

Chrome 46 ou version ultérieure

Énumération

"allow"

"block"

"ask"

ClipboardContentSetting

Chrome 121 ou version ultérieure

Énumération

"allow"

"block"

"ask"

ContentSetting

Propriétés

  • effacer

    vide

    Promesse

    Supprimez toutes les règles de paramètres de contenu définies par cette extension.

    La fonction clear se présente comme suit : 

    (details: object, callback?: function) => {...}

    • détails

      objet

      • champ d'application

        Portée facultatif

        Emplacement où effacer le paramètre (par défaut : "regular").

    • rappel

      fonction facultatif

      Le paramètre callback se présente comme suit : 

      () => void

    • retours

      Promise<void>

      Chrome 96 ou version ultérieure

      Les promesses sont compatibles avec la version 3 du fichier manifeste et les versions ultérieures, mais des rappels sont fournis pour assurer la rétrocompatibilité. Vous ne pouvez pas utiliser les deux dans le même appel de fonction. La promesse se résout avec le même type que celui transmis au rappel.

  • get

    vide

    Promesse

    Récupère le paramètre de contenu actuel pour une paire d'URL donnée.

    La fonction get se présente comme suit : 

    (details: object, callback?: function) => {...}

    • détails

      objet

      • navigation privée

        booléen facultatif

        Indique si les paramètres de contenu doivent être vérifiés pour une session en mode navigation privée. (par défaut, "false")

      • primaryUrl

        chaîne

        URL principale pour laquelle le paramètre de contenu doit être récupéré. Notez que la signification d'une URL principale dépend du type de contenu.

      • resourceIdentifier

        ResourceIdentifier facultatif

        Identifiant plus spécifique du type de contenu pour lequel les paramètres doivent être récupérés.

      • secondaryUrl

        chaîne facultatif

        URL secondaire pour laquelle le paramètre de contenu doit être récupéré. Correspond par défaut à l'URL principale. Notez que la signification d'une URL secondaire dépend du type de contenu, et que tous les types de contenu n'utilisent pas d'URL secondaire.

    • rappel

      fonction facultatif

      Le paramètre callback se présente comme suit : 

      (details: object) => void

      • détails

        objet

        • Paramètre

          T

          Paramètre de contenu. Consultez la description des objets ContentSetting individuels pour connaître les valeurs possibles.

    • retours

      Promise<object>

      Chrome 96 ou version ultérieure

      Les promesses sont compatibles avec la version 3 du fichier manifeste et les versions ultérieures, mais des rappels sont fournis pour assurer la rétrocompatibilité. Vous ne pouvez pas utiliser les deux dans le même appel de fonction. La promesse se résout avec le même type que celui transmis au rappel.

  • getResourceIdentifiers

    vide

    Promesse

    La fonction getResourceIdentifiers se présente comme suit : 

    (callback?: function) => {...}

    • rappel

      fonction facultatif

      Le paramètre callback se présente comme suit : 

      (resourceIdentifiers?: ResourceIdentifier[]) => void

      • resourceIdentifiers

        ResourceIdentifier[] facultatif

        Liste des identifiants de ressources pour ce type de contenu, ou undefined si ce type de contenu n'utilise pas d'identifiants de ressources.

    • retours

      Promise<ResourceIdentifier[]>

      Chrome 96 ou version ultérieure

      Les promesses sont compatibles avec la version 3 du fichier manifeste et les versions ultérieures, mais des rappels sont fournis pour assurer la rétrocompatibilité. Vous ne pouvez pas utiliser les deux dans le même appel de fonction. La promesse se résout avec le même type que celui transmis au rappel.

  • set

    vide

    Promesse

    Applique une nouvelle règle de paramètres de contenu.

    La fonction set se présente comme suit : 

    (details: object, callback?: function) => {...}

    • détails

      objet

      • primaryPattern

        chaîne

        Format de l'URL principale. Pour en savoir plus sur le format d'un modèle, consultez Modèles de paramètres de contenu.

      • resourceIdentifier

        ResourceIdentifier facultatif

        Identifiant de la ressource pour le type de contenu.

      • champ d'application

        Portée facultatif

        Emplacement du paramètre (par défaut : "regular")

      • secondaryPattern

        chaîne facultatif

        Format de l'URL secondaire. Par défaut, toutes les URL correspondent. Pour en savoir plus sur le format d'un format, consultez Formats de paramètres de contenu.

      • Paramètre

        tous

        Paramètre appliqué par cette règle. Consultez la description des objets ContentSetting individuels pour connaître les valeurs possibles.

    • rappel

      fonction facultatif

      Le paramètre callback se présente comme suit : 

      () => void

    • retours

      Promise<void>

      Chrome 96 ou version ultérieure

      Les promesses sont compatibles avec la version 3 du fichier manifeste et les versions ultérieures, mais des rappels sont fournis pour assurer la rétrocompatibilité. Vous ne pouvez pas utiliser les deux dans le même appel de fonction. La promesse se résout avec le même type que celui transmis au rappel.

CookiesContentSetting

Chrome 44 ou version ultérieure

Énumération

"allow"

"block"

"session_only"

FullscreenContentSetting

Chrome 44 ou version ultérieure

Valeur

"allow"

ImagesContentSetting

Chrome 44 ou version ultérieure

Énumération

"allow"

"block"

JavascriptContentSetting

Chrome 44 ou version ultérieure

Énumération

"allow"

"block"

LocationContentSetting

Chrome 44 ou version ultérieure

Énumération

"allow"

"block"

"ask"

MicrophoneContentSetting

Chrome 46 ou version ultérieure

Énumération

"allow"

"block"

"ask"

MouselockContentSetting

Chrome 44 ou version ultérieure

Valeur

"allow"

MultipleAutomaticDownloadsContentSetting

Chrome 44 ou version ultérieure

Énumération

"allow"

"block"

"ask"

NotificationsContentSetting

Chrome 44 ou version ultérieure

Énumération

"allow"

"block"

"ask"

PluginsContentSetting

Chrome 44 ou version ultérieure

Valeur

"block"

PopupsContentSetting

Chrome 44 ou version ultérieure

Énumération

"allow"

"block"

PpapiBrokerContentSetting

Chrome 44 ou version ultérieure

Valeur

"block"

ResourceIdentifier

Le seul type de contenu qui utilise des identifiants de ressources est contentSettings.plugins. Pour en savoir plus, consultez la section Identifiants de ressources.

Propriétés

  • description

    chaîne facultatif

    Description lisible de la ressource.

  • id

    chaîne

    Identifiant de la ressource pour le type de contenu donné.

Scope

Chrome 44 ou version ultérieure

Champ d'application de ContentSetting. L'un des éléments suivants : regular : paramètre pour le profil standard (qui est hérité par le profil de navigation privée s'il n'est pas remplacé ailleurs) incognito\_session\_only : paramètre pour le profil de navigation privée qui ne peut être défini que pendant une session de navigation privée et qui est supprimé à la fin de la session (remplace les paramètres standards).

Énumération

"regular"

"incognito_session_only"

Propriétés

automaticDownloads

Indique si les sites sont autorisés à télécharger automatiquement plusieurs fichiers. L'une des options suivantes : allow: Autoriser les sites à télécharger automatiquement plusieurs fichiers block: Ne pas autoriser les sites à télécharger automatiquement plusieurs fichiers ask: Demander à un site s'il souhaite télécharger automatiquement des fichiers après le premier La valeur par défaut est ask. L'URL principale est l'URL du frame de premier niveau. L'URL secondaire n'est pas utilisée.

Type

ContentSetting<MultipleAutomaticDownloadsContentSetting>

autoVerify

Chrome 113 ou version ultérieure

Indique si les sites sont autorisés à utiliser l'API Private State Tokens. L'une des options suivantes : allow : autoriser les sites à utiliser l'API Private State Tokens, block : empêcher les sites d'utiliser l'API Private State Tokens. La valeur par défaut est allow. L'URL principale est l'URL du frame de premier niveau. L'URL secondaire n'est pas utilisée. REMARQUE: Lorsque vous appelez set(), le modèle principal doit être .

Type

ContentSetting<AutoVerifyContentSetting>

camera

Chrome 46 ou version ultérieure

Indique si les sites sont autorisés à accéder à l'appareil photo. L'une des options suivantes : allow : Autoriser les sites à accéder à l'appareil photo block : Ne pas autoriser les sites à accéder à l'appareil photo ask : Demander à un site s'il souhaite accéder à l'appareil photo La valeur par défaut est ask. L'URL principale est l'URL du document ayant demandé l'accès à l'appareil photo. L'URL secondaire n'est pas utilisée. REMARQUE: Le paramètre "allow" n'est pas valide si les deux formats sont ''.

Type

ContentSetting<CameraContentSetting>

clipboard

Chrome 121 ou version ultérieure

Indique si les sites sont autorisés à accéder au presse-papiers via les fonctionnalités avancées de l'API Async Clipboard. Les fonctionnalités avancées incluent tout ce qui n'est pas l'écriture de formats intégrés après un geste de l'utilisateur, c'est-à-dire la possibilité de lire, d'écrire des formats personnalisés et d'écrire sans geste de l'utilisateur. L'une des options suivantes : allow : Autoriser les sites à utiliser les fonctionnalités avancées du presse-papiers, block : Ne pas autoriser les sites à utiliser les fonctionnalités avancées du presse-papiers, ask : Demander quand un site souhaite utiliser les fonctionnalités avancées du presse-papiers. La valeur par défaut est ask. L'URL principale est l'URL du document ayant demandé l'accès au presse-papiers. L'URL secondaire n'est pas utilisée.

Type

ContentSetting<ClipboardContentSetting>

cookies

Indique si les sites Web sont autorisés à définir des cookies et d'autres données locales. L'une des options suivantes : allow : Accepter les cookies, block : Bloquer les cookies, session\_only : Accepter les cookies uniquement pour la session en cours. La valeur par défaut est allow. L'URL principale est l'URL représentant l'origine du cookie. L'URL secondaire est l'URL du frame de premier niveau.

Type

ContentSetting<CookiesContentSetting>

fullscreen

Obsolète. n'a plus aucun effet. L'autorisation de plein écran est désormais accordée automatiquement pour tous les sites. La valeur est toujours allow.

Type

ContentSetting<FullscreenContentSetting>

images

Indique si les images doivent être affichées. L'une des options suivantes : allow : Afficher les images, block : Ne pas afficher les images. La valeur par défaut est allow. L'URL principale est l'URL du frame de premier niveau. L'URL secondaire est l'URL de l'image.

Type

ContentSetting<ImagesContentSetting>

javascript

Indique si JavaScript doit être exécuté. L'une des options suivantes : allow : exécuter JavaScript, block : ne pas exécuter JavaScript. La valeur par défaut est allow. L'URL principale est l'URL du frame de premier niveau. L'URL secondaire n'est pas utilisée.

Type

ContentSetting<JavascriptContentSetting>

location

Indique si la géolocalisation doit être autorisée. L'une des options suivantes : allow: Autoriser les sites à suivre votre position géographique block: Interdire aux sites de suivre votre position géographique ask: Demander avant d'autoriser les sites à suivre votre position géographique La valeur par défaut est ask. L'URL principale est l'URL du document qui a demandé des données de localisation. L'URL secondaire est l'URL du frame de niveau supérieur (qui peut ou non différer de l'URL de requête).

Type

ContentSetting<LocationContentSetting>

microphone

Chrome 46 ou version ultérieure

Indique si les sites sont autorisés à accéder au micro. L'une des options suivantes : allow: Autoriser les sites à accéder au micro, block: Ne pas autoriser les sites à accéder au micro, ask: Demander quand un site souhaite accéder au micro. La valeur par défaut est ask. L'URL principale est l'URL du document ayant demandé l'accès au micro. L'URL secondaire n'est pas utilisée. REMARQUE: Le paramètre "allow" n'est pas valide si les deux formats sont ''.

Type

ContentSetting<MicrophoneContentSetting>

mouselock

Obsolète. n'a plus aucun effet. L'autorisation de verrouillage de la souris est désormais accordée automatiquement pour tous les sites. La valeur est toujours allow.

Type

ContentSetting<MouselockContentSetting>

notifications

Indique si les sites sont autorisés à afficher des notifications sur le bureau. L'une des options suivantes : allow : Autoriser les sites à afficher des notifications sur le bureau, block : Ne pas autoriser les sites à afficher des notifications sur le bureau, ask : Demander à un site s'il souhaite afficher des notifications sur le bureau. La valeur par défaut est ask. L'URL principale est l'URL du document qui souhaite afficher la notification. L'URL secondaire n'est pas utilisée.

Type

ContentSetting<NotificationsContentSetting>

plugins

Obsolète. La compatibilité avec Flash ayant été supprimée dans Chrome 88, cette autorisation n'a plus aucun effet. La valeur est toujours block. Les appels à set() et clear() seront ignorés.

Type

ContentSetting<PluginsContentSetting>

popups

Indique si les sites sont autorisés à afficher des pop-ups. L'une des options suivantes : allow : Autoriser les sites à afficher des pop-ups, block : Interdire aux sites d'afficher des pop-ups. La valeur par défaut est block. L'URL principale est l'URL du frame de premier niveau. L'URL secondaire n'est pas utilisée.

Type

ContentSetting<PopupsContentSetting>

unsandboxedPlugins

Obsolète. Auparavant, cette autorisation permettait de contrôler si les sites pouvaient exécuter des plug-ins sans bac à sable. Toutefois, avec la suppression du processus de courtier Flash dans Chrome 88, cette autorisation n'a plus aucun effet. La valeur est toujours block. Les appels à set() et clear() seront ignorés.

Type

ContentSetting<PpapiBrokerContentSetting>