chrome.contentSettings

Descrição

Use a API chrome.contentSettings para mudar as configurações que controlam se os sites podem usar recursos como cookies, JavaScript e plug-ins. De modo mais geral, as configurações de conteúdo permitem que você personalize o comportamento do Chrome para cada site, e não globalmente.

Permissões

contentSettings

É necessário declarar a permissão "contentSettings" no manifesto da extensão para usar a API. Por exemplo:

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

Conceitos e uso

Padrões de configuração de conteúdo

Você pode usar padrões para especificar os sites que cada configuração de conteúdo afeta. Por exemplo, https://*.youtube.com/* especifica youtube.com e todos os subdomínios. A sintaxe dos padrões de configuração de conteúdo é a mesma dos padrões de correspondência, com algumas diferenças:

  • Para URLs http, https e ftp, o caminho precisa ser um caractere curinga (/*). Para URLs file, o caminho precisa ser completamente especificado e não pode conter caracteres curinga.
  • Diferente dos padrões de correspondência, os padrões de configuração de conteúdo podem especificar um número de porta. Se um número de porta for especificado, o padrão só vai corresponder a sites com essa porta. Se nenhum número de porta for especificado, o padrão corresponderá a todas as portas.

Precedência do padrão

Quando mais de uma regra de configuração de conteúdo se aplica a um determinado site, a regra com o padrão mais específico tem precedência.

Por exemplo, os seguintes padrões são ordenados por precedência:

  1. https://www.example.com/*
  2. https://*.example.com/* (correspondente a example.com e todos os subdomínios)
  3. <all_urls> (correspondente a todos os URLs)

Três tipos de curingas afetam a especificidade de um padrão:

  • Caracteres curinga na porta (por exemplo, https://www.example.com:*/*)
  • Caracteres curinga no esquema (por exemplo, *://www.example.com:123/*)
  • Caracteres curinga no nome do host (por exemplo, https://*.example.com:123/*)

Se um padrão for mais específico que outro em uma parte, mas menos específico em outra, as diferentes partes serão verificadas na seguinte ordem: nome do host, esquema, porta. Por exemplo, os seguintes padrões são ordenados por precedência:

  1. https://www.example.com:*/* Especifica o nome do host e o esquema.
  2. *:/www.example.com:123/* Não tão alto porque, embora especifique o nome do host, ele não especifica o esquema.
  3. https://*.example.com:123/* Menor porque, embora especifique a porta e o esquema, tem um caractere curinga no nome do host.

Padrões primários e secundários

O URL considerado ao decidir qual configuração de conteúdo aplicar depende do tipo de conteúdo. Por exemplo, as configurações de contentSettings.notifications são baseadas no URL mostrado na omnibox. Esse URL é chamado de "principal".

Alguns tipos de conteúdo podem levar outros URLs em consideração. Por exemplo, se um site pode definir um contentSettings.cookies é decidido com base no URL da solicitação HTTP (que é o URL principal neste caso) e no URL mostrado na caixa de pesquisa (chamado de URL "secundário").

Se várias regras tiverem padrões primários e secundários, a regra com o padrão principal mais específico terá precedência. Se várias regras tiverem o mesmo padrão principal, a regra com o padrão secundário mais específico terá precedência. Por exemplo, a lista a seguir de pares de padrões primários/secundários é ordenada por precedência:

PrecedênciaPadrão principalPadrão secundário
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>

A configuração de conteúdo de imagens não oferece suporte a padrões secundários.

Identificadores de recursos

Os identificadores de recursos permitem especificar configurações de conteúdo para subtipos específicos de um tipo de conteúdo. Atualmente, o único tipo de conteúdo com suporte a identificadores de recurso é contentSettings.plugins, em que um identificador de recurso identifica um plug-in específico. Ao aplicar configurações de conteúdo, primeiro as configurações do plug-in específico são verificadas. Se não houver configurações encontradas para o plug-in específico, as configurações de conteúdo gerais para plug-ins serão verificadas.

Por exemplo, se uma regra de configuração de conteúdo tiver o identificador de recurso adobe-flash-player e o padrão <all_urls>, ela terá precedência sobre uma regra sem identificador de recurso e o padrão https://www.example.com/*, mesmo que esse padrão seja mais específico.

Para conferir uma lista de identificadores de recursos de um tipo de conteúdo, chame o método contentSettings.ContentSetting.getResourceIdentifiers(). A lista retornada pode mudar com o conjunto de plug-ins instalados na máquina do usuário, mas o Chrome tenta manter os identificadores estáveis nas atualizações do plug-in.

Exemplos

Para testar essa API, instale o exemplo da API contentSettings no repositório chrome-extension-samples.

Tipos

AutoVerifyContentSetting

Chrome 113 e versões mais recentes

Enumeração

"allow"

"block"

CameraContentSetting

Chrome 46 ou mais recente

Enumeração

"allow"

"block"

"ask"

ClipboardContentSetting

Chrome 121 e versões mais recentes

Enumeração

"allow"

"block"

ContentSetting

Propriedades

  • limpar

    void

    Promessa

    Limpa todas as regras de configuração de conteúdo definidas por esta extensão.

    A função clear tem esta aparência: 

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

    • detalhes

      objeto

      • escopo

        Escopo opcional

        Onde limpar a configuração (padrão: normal).

    • callback

      função opcional

      O parâmetro callback tem este formato: 

      () => void

    • retorna

      Promessa<void>

      Chrome 96 ou versões mais recentes

      O Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar ambos na mesma chamada de função. A promessa é resolvida com o mesmo tipo passado para o callback.

  • get

    void

    Promessa

    Extrai a configuração de conteúdo atual para um determinado par de URLs.

    A função get é semelhante a esta: 

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

    • detalhes

      objeto

      • navegação anônima

        booleano opcional

        Define se as configurações de conteúdo para uma sessão de navegação anônima serão verificadas. (padrão: false)

      • primaryUrl

        string

        O URL principal para o qual a configuração de conteúdo precisa ser recuperada. O significado de um URL principal depende do tipo de conteúdo.

      • resourceIdentifier

        ResourceIdentifier opcional

        Um identificador mais específico do tipo de conteúdo para o qual as configurações precisam ser recuperadas.

      • secondaryUrl

        string opcional

        O URL secundário para o qual a configuração de conteúdo precisa ser recuperada. O padrão é o URL principal. O significado de um URL secundário depende do tipo de conteúdo, e nem todos eles usam URLs secundários.

    • callback

      função opcional

      O parâmetro callback tem este formato: 

      (details: object) => void

      • detalhes

        objeto

        • Configuração

          T

          A configuração de conteúdo. Consulte a descrição dos objetos ContentSetting individuais para ver os possíveis valores.

    • retorna

      Promessa de<objeto>

      Chrome 96 e versões mais recentes

      As promessas têm suporte no Manifest V3 e versões mais recentes, mas os callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo passado para o callback.

  • getResourceIdentifiers

    void

    Promessa

    A função getResourceIdentifiers é semelhante a esta: 

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

    • callback

      função opcional

      O parâmetro callback tem este formato: 

      (resourceIdentifiers?: ResourceIdentifier[]) => void

      • resourceIdentifiers

        ResourceIdentifier[] opcional

        Uma lista de identificadores de recursos para esse tipo de conteúdo ou undefined se esse tipo de conteúdo não usar identificadores de recursos.

    • retorna

      Promise&lt;ResourceIdentifier[]&gt;

      Chrome 96 ou versões mais recentes

      As promessas têm suporte no Manifest V3 e versões mais recentes, mas os callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo passado para o callback.

  • set

    void

    Promessa

    Aplica uma nova regra de configuração de conteúdo.

    A função set é semelhante a esta: 

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

    • detalhes

      objeto

      • primaryPattern

        string

        O padrão do URL principal. Para mais detalhes sobre o formato de um padrão, consulte Padrões de configuração de conteúdo.

      • resourceIdentifier

        ResourceIdentifier opcional

        O identificador de recurso para o tipo de conteúdo.

      • escopo

        Escopo opcional

        Onde definir a configuração (padrão: normal).

      • secondaryPattern

        string opcional

        O padrão do URL secundário. Por padrão, corresponde a todos os URLs. Para saber mais sobre o formato de um padrão, consulte Padrões de configuração de conteúdo.

      • Configuração

        qualquer um

        A configuração aplicada por essa regra. Consulte a descrição dos objetos individuais do ContentSetting para conferir os valores possíveis.

    • callback

      função opcional

      O parâmetro callback tem este formato: 

      () => void

    • retorna

      Promessa<void>

      Chrome 96 ou versões mais recentes

      O Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar ambos na mesma chamada de função. A promessa é resolvida com o mesmo tipo passado para o callback.

CookiesContentSetting

Chrome 44 e versões mais recentes

Enumeração

"allow"

"block"

"session_only"

FullscreenContentSetting

Chrome 44 ou superior

Valor

"allow"

ImagesContentSetting

Chrome 44 e versões mais recentes

Enumeração

"allow"

"block"

JavascriptContentSetting

Chrome 44 ou superior

Enumeração

"allow"

"block"

LocationContentSetting

Chrome 44 ou superior

Enumeração

"allow"

"block"

"ask"

MicrophoneContentSetting

Chrome 46 ou mais recente

Enumeração

"allow"

"block"

"ask"

MouselockContentSetting

Chrome 44 ou superior

Valor

"allow"

MultipleAutomaticDownloadsContentSetting

Chrome 44 e versões mais recentes

Enumeração

"allow"

"block"

"ask"

NotificationsContentSetting

Chrome 44 ou posterior

Enumeração

"allow"

"block"

"ask"

PluginsContentSetting

Chrome 44 e versões mais recentes

Valor

PopupsContentSetting

Chrome 44 ou superior

Enumeração

"allow"

"block"

PpapiBrokerContentSetting

Chrome 44 ou superior

Valor

ResourceIdentifier

O único tipo de conteúdo que usa identificadores de recurso é contentSettings.plugins. Para mais informações, consulte Identificadores de recursos.

Propriedades

  • descrição

    string opcional

    Uma descrição legível do recurso.

  • id

    string

    O identificador de recurso para o tipo de conteúdo fornecido.

Scope

Chrome 44 ou superior

O escopo da ContentSetting. Uma destas regular: configuração para o perfil normal (que é herdado pelo perfil de navegação anônima se não for substituída em outro lugar), incognito\_session\_only: configuração para perfil de navegação anônima que só pode ser definida durante uma sessão de navegação anônima e excluída quando a sessão de navegação anônima termina (substitui as configurações normais).

Enumeração

Propriedades

automaticDownloads

Permitir que os sites façam o download automático de vários arquivos. Uma destas opções: allow: permitir que os sites façam o download de vários arquivos automaticamente; block: não permitir que os sites façam o download de vários arquivos automaticamente; ask: perguntar quando um site quer fazer o download de arquivos automaticamente após o primeiro arquivo. O padrão é ask. O URL principal é o URL do frame de nível superior. O URL secundário não é usado.

Tipo

ContentSetting&lt;MultipleAutomaticDownloadsContentSetting&gt;

autoVerify

Chrome 113 ou versões mais recentes

Define se os sites podem usar a API Private State Tokens. Um dos seguintes: allow: permitir que os sites usem a API Private State Tokens, block: bloquear os sites de usar a API Private State Tokens. O padrão é allow. O URL principal é o do frame de nível superior. O URL secundário não é usado. OBSERVAÇÃO: ao chamar set(), o padrão principal precisa ser .

Tipo

ContentSetting&lt;AutoVerifyContentSetting&gt;

camera

Chrome 46 ou mais recente

Define se os sites podem acessar a câmera ou não. Uma destas opções: allow: permitir que sites acessem a câmera; block: não permitir que sites acessem a câmera; ask: perguntar quando um site quiser acessar a câmera. O padrão é ask. O URL principal é o do documento que solicitou o acesso à câmera. O URL secundário não é usado. OBSERVAÇÃO: a configuração "Permitir" não será válida se ambos os padrões forem "".

Tipo

ContentSetting&lt;CameraContentSetting&gt;

clipboard

Chrome 121 ou versões mais recentes

Define se os sites podem acessar a área de transferência usando recursos avançados da API Async Clipboard. Os recursos "avançados" incluem tudo além da gravação de formatos integrados após um gesto do usuário, ou seja, a capacidade de ler, gravar formatos personalizados e gravar sem um gesto do usuário. Uma destas opções: allow: permitir que os sites usem recursos avançados de área de transferência; block: não permitir que os sites usem recursos avançados de área de transferência; ask: perguntar quando um site quiser usar recursos avançados de área de transferência. O padrão é ask. O URL principal é o URL do documento que solicitou acesso à área de transferência. O URL secundário não é usado.

Tipo

ContentSetting&lt;ClipboardContentSetting&gt;

cookies

Define se cookies e outros dados locais serão definidos pelos sites. Uma destas opções: allow: aceitar cookies, block: bloquear cookies, session\_only: aceitar cookies apenas para a sessão atual. O padrão é allow. O URL principal é o que representa a origem do cookie. O URL secundário é o URL do frame de nível superior.

Tipo

ContentSetting<CookiesContentSetting>

fullscreen

Obsoleto. Não tem mais efeito. A permissão de tela cheia agora é concedida automaticamente para todos os sites. O valor é sempre allow.

Tipo

ContentSetting<FullscreenContentSetting>

images

Indica se as imagens vão ser mostradas. Um dos allow: mostrar imagens, block: não mostrar imagens. O padrão é allow. O URL principal é o do frame de nível superior. O URL secundário é o da imagem.

Tipo

ContentSetting<ImagesContentSetting>

javascript

Se o JavaScript será executado. Uma destas opções: allow: executar JavaScript; block: não executar JavaScript. O padrão é allow. O URL principal é o do frame de nível superior. O URL secundário não é usado.

Tipo

ContentSetting&lt;JavascriptContentSetting&gt;

location

Define se a geolocalização será permitida. Uma destas opções: allow: permitir que sites rastreiem sua localização física; block: não permitir que sites rastreiem sua localização física; ask: perguntar antes de permitir que sites rastreiem sua localização física. O padrão é ask. O URL principal é o do documento que solicitou dados de local. O URL secundário é o URL do frame de nível superior, que pode ou não ser diferente do URL solicitante.

Tipo

ContentSetting<LocationContentSetting>

microphone

Chrome 46 ou mais recente

Permite que os sites acessem o microfone. Uma destas opções: allow: permitir que sites acessem o microfone; block: não permitir que sites acessem o microfone; ask: perguntar quando um site quiser acessar o microfone. O padrão é ask. O URL principal é o do documento que solicitou o acesso ao microfone. O URL secundário não é usado. OBSERVAÇÃO: a configuração "permitir" não é válida se os dois padrões forem "#".

Tipo

ContentSetting&lt;MicrophoneContentSetting&gt;

mouselock

Obsoleto. Não tem mais efeito. A permissão de bloqueio do mouse agora é concedida automaticamente para todos os sites. O valor é sempre allow.

Tipo

ContentSetting&lt;MouselockContentSetting&gt;

notifications

Define se os sites podem mostrar notificações na área de trabalho. Uma das opções abaixo: allow: permitir que sites mostrem notificações na área de trabalho, block: não permitir que sites mostrem notificações na área de trabalho, ask: perguntar quando um site quiser mostrar notificações na área de trabalho. O padrão é ask. O URL principal é o URL do documento que deseja exibir a notificação. O URL secundário não é usado.

Tipo

ContentSetting&lt;NotificationsContentSetting&gt;

plugins

Obsoleto. Como o suporte ao Flash foi removido no Chrome 88, essa permissão não tem mais efeito. O valor é sempre block. As chamadas para set() e clear() serão ignoradas.

Tipo

ContentSetting&lt;PluginsContentSetting&gt;

popups

Permite que os sites mostrem pop-ups. Uma destas opções: allow: permitir que os sites mostrem pop-ups; block: não permitir que os sites mostrem pop-ups. O padrão é block. O URL principal é o do frame de nível superior. O URL secundário não é usado.

Tipo

ContentSetting<PopupsContentSetting>

unsandboxedPlugins

Obsoleto. Anteriormente, era possível controlar se os sites podiam executar plug-ins sem sandbox. No entanto, com a remoção do processo de intermediário do Flash no Chrome 88, essa permissão não tem mais efeito. O valor é sempre block. As chamadas para set() e clear() serão ignoradas.

Tipo

ContentSetting<PpapiBrokerContentSetting>