browser.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 geral, as configurações de conteúdo permitem personalizar o comportamento do Chrome por site, em vez de 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 afetados por cada configuração de conteúdo. Por exemplo, https://*.youtube.com/* especifica youtube.com e todos os subdomínios dele. A sintaxe dos padrões de configuração de conteúdo é igual à 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.
  • Ao contrário 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 caracteres curinga 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 do 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 padrões a seguir 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 alta, porque, embora especifique o nome do host, não especifica o esquema.
  3. https://*.example.com:123/* Menor porque, embora especifique a porta e o esquema, ele 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, para contentSettings.notifications, as configurações são baseadas no URL mostrado na omnibox. Esse URL é chamado de "principal".

Alguns tipos de conteúdo podem considerar URLs adicionais. Por exemplo, se um site tem permissão para definir um contentSettings.cookies, isso é decidido com base no URL da solicitação HTTP (que é o URL principal nesse caso) e no URL mostrado na omnibox (chamado de URL "secundário").

Se várias regras tiverem padrões primários e secundários, a regra com o padrão primário mais específico terá precedência. Se várias regras tiverem o mesmo padrão principal, aquela 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>

Não há suporte para padrões secundários na configuração de conteúdo de imagens.

Identificadores de recursos

Os identificadores de recursos permitem especificar configurações de conteúdo para subtipos específicos de um tipo de conteúdo. No momento, o único tipo de conteúdo que aceita identificadores de recursos é contentSettings.plugins, em que um identificador de recurso identifica um plug-in específico. Ao aplicar as configurações de conteúdo, primeiro as configurações do plug-in específico são verificadas. Se não houver configurações para o plug-in específico, as configurações gerais de conteúdo 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 um identificador de recurso e o padrão https://www.example.com/*, mesmo que esse padrão seja mais específico.

Para receber uma lista de identificadores de recursos para 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 de plug-ins.

Exemplos

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

Tipos

AutoVerifyContentSetting

Chrome 113+ browser.* desde o Chrome 148

Enumeração

"allow"

"block"

CameraContentSetting

Chrome 46+ browser.* desde o Chrome 148

Enumeração

"allow"

"block"

"ask"

ClipboardContentSetting

Chrome 121+ browser.* desde o Chrome 148

Enumeração

"allow"

"block"

"ask"

ContentSetting

Propriedades

  • limpar

    void

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

    A função clear é semelhante a: 

    (details: object) => {...}

    • detalhes

      objeto

      • escopo

        Escopo opcional

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

    • retorna

      Promessa<void>

      Chrome 96+ browser.* desde o Chrome 148
  • get

    void

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

    A função get é semelhante a: 

    (details: object) => {...}

    • detalhes

      objeto

      • incognito

        booleano opcional

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

      • primaryUrl

        string

        O URL principal para o qual a configuração de conteúdo deve 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 devem ser recuperadas.

      • secondaryUrl

        string opcional

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

    • retorna

      Promise<object>

      Chrome 96+ browser.* desde o Chrome 148
  • getResourceIdentifiers

    void

    A função getResourceIdentifiers é semelhante a: 

    () => {...}

  • set

    void

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

    A função set é semelhante a: 

    (details: object) => {...}

    • detalhes

      objeto

      • primaryPattern

        string

        O padrão do URL principal. Para 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, todos os URLs são correspondidos. Para detalhes sobre o formato de um padrão, consulte Padrões de configuração de conteúdo.

      • Configuração

        qualquer

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

    • retorna

      Promessa<void>

      Chrome 96+ browser.* desde o Chrome 148

CookiesContentSetting

Chrome 44+ browser.* desde o Chrome 148

Enumeração

"allow"

"block"

"session_only"

FullscreenContentSetting

Chrome 44+ browser.* desde o Chrome 148

Valor

"allow"

ImagesContentSetting

Chrome 44+ browser.* desde o Chrome 148

Enumeração

"allow"

"block"

JavascriptContentSetting

Chrome 44+ browser.* desde o Chrome 148

Enumeração

"allow"

"block"

LocationContentSetting

Chrome 44+ browser.* desde o Chrome 148

Enumeração

"allow"

"block"

"ask"

MicrophoneContentSetting

Chrome 46+ browser.* desde o Chrome 148

Enumeração

"allow"

"block"

"ask"

MouselockContentSetting

Chrome 44+ browser.* desde o Chrome 148

Valor

"allow"

MultipleAutomaticDownloadsContentSetting

Chrome 44+ browser.* desde o Chrome 148

Enumeração

"allow"

"block"

"ask"

NotificationsContentSetting

Chrome 44+ browser.* desde o Chrome 148

Enumeração

"allow"

"block"

"ask"

PluginsContentSetting

Chrome 44+ browser.* desde o Chrome 148

Valor

"block"

PopupsContentSetting

Chrome 44+ browser.* desde o Chrome 148

Enumeração

"allow"

"block"

PpapiBrokerContentSetting

Chrome 44+ browser.* desde o Chrome 148

Valor

"block"

ResourceIdentifier

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

Propriedades

  • descrição

    string opcional

    Uma descrição do recurso legível por humanos.

  • ID

    string

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

Scope

Chrome 44+ browser.* desde o Chrome 148

O escopo do ContentSetting. Um dos seguintes: regular: configuração para o perfil normal (que é herdada pelo perfil de navegação anônima se não for substituída em outro lugar). incognito\_session\_only: configuração para o 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 termina (substitui as configurações normais).

Enumeração

"regular"

"incognito_session_only"

SoundContentSetting

Chrome 141+ browser.* desde o Chrome 148

Enumeração

"allow"

"block"

Propriedades

automaticDownloads

Se os sites podem baixar vários arquivos automaticamente. Uma das seguintes 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 quiser 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<MultipleAutomaticDownloadsContentSetting>

autoVerify

Chrome 113+ browser.* desde o Chrome 148

Se os sites podem usar a API Private State Tokens. Uma das seguintes opções: allow: permitir que os sites usem a API Private State Tokens. block: impedir que os sites usem a API Private State Tokens. O padrão é allow. Ao chamar set(), o padrão do URL principal precisa ser <all_urls>. O URL secundário não é usado.

Tipo

ContentSetting<AutoVerifyContentSetting>

camera

Chrome 46+ browser.* desde o Chrome 148

Se os sites podem acessar a câmera. Uma das seguintes opções: allow: permitir que os sites acessem a câmera block: não permitir que os sites acessem a câmera ask: perguntar quando um site quiser acessar a câmera O padrão é ask. O URL principal é o URL do documento que solicitou acesso à câmera. O URL secundário não é usado. OBSERVAÇÃO: a configuração "allow" não é válida se os dois padrões forem "<all_urls>".

Tipo

ContentSetting<CameraContentSetting>

clipboard

Chrome 121+ browser.* desde o Chrome 148

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 de gravar formatos integrados após uma interação inicial, ou seja, a capacidade de ler, gravar formatos personalizados e gravar sem uma interação inicial. Uma das seguintes opções: allow: permitir que os sites usem recursos avançados da área de transferência block: não permitir que os sites usem recursos avançados da área de transferência ask: perguntar quando um site quiser usar recursos avançados da á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<ClipboardContentSetting>

cookies

Se os sites podem definir cookies e outros dados locais. 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 URL 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

Se as imagens devem ser mostradas. Uma das opções allow: mostrar imagens, block: não mostrar imagens. O padrão é allow. O URL principal é o URL do frame de nível superior. O URL secundário é o URL da imagem.

Tipo

ContentSetting<ImagesContentSetting>

javascript

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

Tipo

ContentSetting<JavascriptContentSetting>

location

Se a geolocalização é permitida. Uma das seguintes opções: allow: permitir que os sites rastreiem seu local físico, block: não permitir que os sites rastreiem seu local físico, ask: perguntar antes de permitir que os sites rastreiem seu local físico. O padrão é ask. O URL principal é o URL do documento que solicitou os dados de local. O URL secundário é o URL do frame de nível superior, que pode ou não ser diferente do URL de solicitação.

Tipo

ContentSetting<LocationContentSetting>

microphone

Chrome 46+ browser.* desde o Chrome 148

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

Tipo

ContentSetting<MicrophoneContentSetting>

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

notifications

Se os sites podem mostrar notificações na área de trabalho. Uma das seguintes opções: allow: permitir que os sites mostrem notificações na área de trabalho, block: não permitir que os 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 quer mostrar a notificação. O URL secundário não é usado.

Tipo

ContentSetting<NotificationsContentSetting>

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

popups

Se os sites podem mostrar pop-ups. Uma das seguintes 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 URL do frame de nível superior. O URL secundário não é usado.

Tipo

ContentSetting<PopupsContentSetting>

unsandboxedPlugins

Obsoleto. Antes, controlava se os sites podiam executar plug-ins sem sandbox. No entanto, com a remoção do processo do agente 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>