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 les cookies, JavaScript et les plug-ins. Plus généralement, les paramètres de contenu vous permettent de personnaliser le comportement de Chrome pour chaque site, et non pour l'ensemble.

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

Schémas des paramètres de contenu

Vous pouvez utiliser des formats pour indiquer 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 pour les formats de correspondance, à quelques différences près:

  • Pour les URL http, https et ftp, le chemin d'accès doit être un caractère générique (/*). Pour les URL file, il doit être entièrement 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 un numéro de port est spécifié, le format ne correspond qu'aux sites Web utilisant ce port. Si aucun numéro de port n'est spécifié, le modèle correspond à tous les ports.

Priorité des formats

Lorsque plusieurs règles de paramètre de contenu s'appliquent à un site donné, la règle avec le format le plus spécifique est prioritaire.

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

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

Trois types de caractères génériques affectent le degré 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/* Pas aussi élevée, car bien que le nom d'hôte soit spécifié, le schéma n'est pas précisé.
  3. https://*.example.com:123/* Cette valeur est inférieure, car bien que le port et le schéma soient spécifiés, le nom d'hôte comporte un caractère générique.

Schémas primaires et secondaires

L'URL prise en compte lors du choix du 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 l'omnibox. Il s'agit de l'URL "principale".

Certains types de contenus peuvent tenir compte d'autres URL. Par exemple, l'autorisation d'un site à définir une contentSettings.cookies dépend de l'URL de la requête HTTP (qui est l'URL principale dans le cas présent) et de l'URL affichée dans l'omnibox (appelée URL "secondaire").

Si plusieurs règles ont des formats principaux et secondaires, la règle associée au format principal le plus spécifique est prioritaire. Si plusieurs règles ont le même format principal, la règle associée au format secondaire plus spécifique est prioritaire. Par exemple, la liste suivante de paires de modèles primaires/secondaires est classée par priorité:

PrioritéSchéma 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>

Identifiants de ressources

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 ressource est contentSettings.plugins, où un identifiant de ressource identifie un plug-in spécifique. Lorsque vous appliquez des paramètres de contenu, ceux 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 possède l'identifiant de ressource adobe-flash-player et le format <all_urls>, elle est prioritaire sur une règle sans identifiant de ressource et le format https://www.example.com/*, même si ce format 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 l'ordinateur de l'utilisateur, mais Chrome tente de conserver les identifiants stables lors des mises à jour de 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 et versions ultérieures

Enum

"allow"

"block"

CameraContentSetting

Chrome 46 ou version ultérieure

Enum

"allow"

"block"

ClipboardContentSetting

Chrome 121 et versions ultérieures

Enum

"allow"

"block"

ContentSetting

Propriétés

  • effacer

    void

    Promesse

    Effacez toutes les règles de paramètre 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

        Champ d'application facultatif

        Où effacer ce paramètre (par défaut: standard) ?

    • rappel

      fonction facultative

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

      ()=>void

    • retours

      Promise<void>

      Chrome 96 et versions ultérieures

      Les promesses sont compatibles avec Manifest V3 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 est résolue avec le même type que celui transmis au rappel.

  • get

    void

    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 de 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

        string facultatif

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

    • rappel

      fonction facultative

      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 différents objets ContentSetting pour connaître les valeurs possibles.

    • retours

      Promise<object>

      Chrome 96 et versions ultérieures

      Les promesses sont compatibles avec Manifest V3 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 est résolue avec le même type que celui transmis au rappel.

  • getResourceIdentifiers

    void

    Promesse

    La fonction getResourceIdentifiers se présente comme suit : 

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

    • rappel

      fonction facultative

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

      (resourceIdentifiers?: ResourceIdentifier[])=>void

      • resourceIdentifiers

        ResourceIdentifier[] facultatif

        Liste d'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 et versions ultérieures

      Les promesses sont compatibles avec Manifest V3 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 est résolue avec le même type que celui transmis au rappel.

  • set

    void

    Promesse

    Applique une nouvelle règle de paramètre 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 format, consultez Formats de paramètres de contenu.

      • resourceIdentifier

        ResourceIdentifier facultatif

        Identifiant de ressource pour le type de contenu.

      • champ d'application

        Champ d'application facultatif

        Où définir le paramètre (par défaut: standard).

      • secondaryPattern

        string facultatif

        Format de l'URL secondaire. La valeur par défaut correspond à toutes les URL. Pour en savoir plus sur le format d'un format, consultez l'article Formats des paramètres de contenu.

      • Paramètre

        toutes

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

    • rappel

      fonction facultative

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

      ()=>void

    • retours

      Promise<void>

      Chrome 96 et versions ultérieures

      Les promesses sont compatibles avec Manifest V3 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 est résolue avec le même type que celui transmis au rappel.

CookiesContentSetting

Chrome 44 ou version ultérieure

Enum

"allow"

"block"

"session_only"

FullscreenContentSetting

Chrome 44 ou version ultérieure

Valeur

"allow"

ImagesContentSetting

Chrome 44 ou version ultérieure

Enum

"allow"

"block"

JavascriptContentSetting

Chrome 44 ou version ultérieure

Enum

"allow"

"block"

LocationContentSetting

Chrome 44 ou version ultérieure

Enum

"allow"

"block"

MicrophoneContentSetting

Chrome 46 ou version ultérieure

Enum

"allow"

"block"

MouselockContentSetting

Chrome 44 ou version ultérieure

Valeur

"allow"

MultipleAutomaticDownloadsContentSetting

Chrome 44 ou version ultérieure

Enum

"allow"

"block"

NotificationsContentSetting

Chrome 44 ou version ultérieure

Enum

"allow"

"block"

PluginsContentSetting

Chrome 44 ou version ultérieure

Valeur

"block"

PopupsContentSetting

Chrome 44 ou version ultérieure

Enum

"allow"

"block"

PpapiBrokerContentSetting

Chrome 44 ou version ultérieure

Valeur

"block"

ResourceIdentifier

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

Propriétés

  • description

    string facultatif

    Description de la ressource dans un format lisible.

  • id

    chaîne

    Identifiant de ressource pour le type de contenu donné.

Scope

Chrome 44 ou version ultérieure

Champ d'application du paramètre ContentSetting. L'un des regular: paramètre du profil de navigation privée (hérité par le profil de navigation privée s'il n'est pas remplacé ailleurs), incognito\_session\_only: paramètre du 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 de navigation privée (remplace les paramètres standards).

Enum

"incognito_session_only"

Propriétés

automaticDownloads

Permet d'autoriser ou non les sites à 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 lorsqu'un site souhaite télécharger des fichiers automatiquement après le premier fichier. 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 et versions ultérieures

Permet d'autoriser ou non les sites à utiliser l'API Private State Tokens. L'un des allow (permet aux sites d'utiliser l'API Private State Tokens), block : empêche 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 format principal doit être .

Type

ContentSetting<AutoVerifyContentSetting>

camera

Chrome 46 ou version ultérieure

Permet d'autoriser ou non les sites à accéder à l'appareil photo. L'une des options suivantes : allow : autoriser les sites à accéder à la caméra, block : ne pas autoriser les sites à accéder à la caméra, ask : demander lorsqu'un site souhaite accéder à la caméra. La valeur par défaut est ask. L'URL principale est celle du document qui a 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 et versions ultérieures

Permet d'autoriser ou non les sites à accéder au presse-papiers via les fonctionnalités avancées de l'API Async Clipboard. Les capacités "avancées" incluent tout autre élément que l'écriture de formats intégrés après un geste de l'utilisateur, c'est-à-dire la lecture, la rédaction de formats personnalisés et la rédaction 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 lorsqu'un site souhaite utiliser les fonctionnalités avancées du presse-papiers. La valeur par défaut est ask. L'URL principale est celle du document qui a demandé l'accès au presse-papiers. L'URL secondaire n'est pas utilisée.

Type

ContentSetting<ClipboardContentSetting>

cookies

Permet d'autoriser ou non les cookies et d'autres données locales à être définis par les sites Web. 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 celle qui représente l'origine du cookie. L'URL secondaire est l'URL du frame de premier niveau.

Type

ContentSetting<CookiesContentSetting>

fullscreen

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

Type

ContentSetting<FullscreenContentSetting>

images

Permet d'afficher ou non les images. L'une des valeurs suivantes : allow : Afficher les images. block : N'affiche pas les images. La valeur par défaut est allow. L'URL principale est l'URL du frame de premier niveau. L'URL secondaire est celle de l'image.

Type

ContentSetting<ImagesContentSetting>

javascript

Indique si JavaScript doit être exécuté. L'une des valeurs suivantes : allow : exécuter JavaScript. block : n'exécutez pas 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

Permet d'autoriser ou non la géolocalisation. L'une des allow: autoriser les sites à suivre ma position géographique ; block: ne pas autoriser les sites à suivre votre position géographique ; ask: demandez avant d'autoriser les sites à suivre votre position. La valeur par défaut est ask. L'URL principale est celle du document qui a demandé les données de localisation. L'URL secondaire est l'URL de la trame de premier niveau (qui peut être différente de l'URL à l'origine de la demande ou non).

Type

ContentSetting<LocationContentSetting>

microphone

Chrome 46 ou version ultérieure

Permet d'autoriser ou non les sites à 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 lorsqu'un site souhaite accéder au micro. La valeur par défaut est ask. L'URL principale est celle du document qui a 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. Ce paramètre n'a plus aucun effet. L'autorisation de verrouillage de la souris est désormais automatiquement accordée pour tous les sites. La valeur est toujours allow.

Type

ContentSetting<MouselockContentSetting>

notifications

Permet d'autoriser ou non les sites à 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 lorsqu'un site souhaite afficher des notifications sur le bureau. La valeur par défaut est ask. L'URL principale est celle du document sur lequel la notification doit être affichée. L'URL secondaire n'est pas utilisée.

Type

ContentSetting<NotificationsContentSetting>

plugins

Obsolète. Comme Flash n'est plus compatible avec 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

Permet d'autoriser ou non les sites à afficher des pop-ups. L'une des valeurs suivantes : allow : autoriser les sites à afficher des pop-ups, block : ne pas autoriser les sites à 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, il était possible d'autoriser ou non les sites à exécuter des plug-ins hors bac à sable. Toutefois, comme le processus de courtier Flash a été supprimé 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>