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 personalizar o comportamento do Chrome por site, e não globalmente.
Permissões
contentSettings
Manifesto
É necessário declarar a permissão "contentSettings" no manifesto da extensão para usar a API. Exemplo:
{
"name": "My extension",
...
"permissions": [
"contentSettings"
],
...
}
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
eftp
, o caminho precisa ser um caractere curinga (/*
). Para URLsfile
, o caminho precisa ser totalmente 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 vai corresponder apenas os 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:
https://www.example.com/*
https://*.example.com/*
(exemplo.com correspondente e todos os subdomínios)<all_urls>
(corresponde a cada URL)
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 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:
https://www.example.com:*/*
Especifica o nome do host e o esquema.*:/www.example.com:123/*
Não tão alto, porque embora o nome do host seja especificado, ele não define o esquema.https://*.example.com:123/*
Inferior 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 URL "principal".
Alguns tipos de conteúdo podem levar URLs adicionais em consideração. 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 neste caso), bem como 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 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ência | Padrão principal | Padrão secundário |
---|---|---|
1 | https://www.moose.com/* , | https://www.wombat.com/* |
2 | https://www.moose.com/* , | <all_urls> |
3 | <all_urls> , | https://www.wombat.com/* |
4 | <all_urls> , | <all_urls> |
Identificadores de recursos
Os identificadores de recurso permitem definir configurações de conteúdo para subtipos específicos de um tipo de conteúdo.
Atualmente, o único tipo de conteúdo compatível com identificadores de recursos é 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 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 conseguir 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 do plug-in.
Exemplos
Para testar essa API, instale o exemplo da API contentSettings no repositório chrome-extension-samples.
Tipos
AutoVerifyContentSetting
Tipo enumerado
CameraContentSetting
Tipo enumerado
ClipboardContentSetting
Tipo enumerado
ContentSetting
Propriedades
-
limpar
void
PromessaLimpa 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 optional
O parâmetro
callback
tem esta aparência:() => void
-
retorna
Promise<void>
Chrome 96 ou mais recentePromessas são compatíveis apenas com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.
-
-
get
void
PromessaRecebe a configuração de conteúdo atual para um determinado par de URLs.
A função
get
tem esta aparência:(details: object, callback?: function) => {...}
-
detalhes
objeto
-
navegação anônima
booleano opcional
Define se as configurações de conteúdo para uma sessão anônima devem ser verificadas. (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 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 usam URLs secundários.
-
-
callback
função optional
O parâmetro
callback
tem esta aparência:(details: object) => void
-
detalhes
objeto
-
Configuração
T
A configuração de conteúdo. Consulte a descrição dos objetos ContentSetting individuais para saber os valores possíveis.
-
-
-
retorna
Promise<object>
Chrome 96 ou mais recentePromessas são compatíveis apenas com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.
-
-
getResourceIdentifiers
void
PromessaA função
getResourceIdentifiers
tem esta aparência:(callback?: function) => {...}
-
callback
função optional
O parâmetro
callback
tem esta aparência:(resourceIdentifiers?: ResourceIdentifier[]) => void
-
resourceIdentifiers
ResourceIdentifier[] opcional
Uma lista de identificadores de recurso para este tipo de conteúdo, ou
undefined
se esse tipo de conteúdo não usa identificadores de recurso.
-
-
retorna
Promise<ResourceIdentifier[]>
Chrome 96 ou mais recentePromessas são compatíveis apenas com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.
-
-
set
void
PromessaAplica uma nova regra de configuração de conteúdo.
A função
set
tem esta aparência:(details: object, callback?: function) => {...}
-
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. O padrão é a correspondência de todos os URLs. Para acessar detalhes 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 esta regra. Consulte a descrição dos objetos ContentSetting individuais para saber os valores possíveis.
-
-
callback
função optional
O parâmetro
callback
tem esta aparência:() => void
-
retorna
Promise<void>
Chrome 96 ou mais recentePromessas são compatíveis apenas com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.
-
CookiesContentSetting
Tipo enumerado
"session_only"
FullscreenContentSetting
Valor
ImagesContentSetting
Tipo enumerado
JavascriptContentSetting
Tipo enumerado
LocationContentSetting
Tipo enumerado
MicrophoneContentSetting
Tipo enumerado
MouselockContentSetting
Valor
MultipleAutomaticDownloadsContentSetting
Tipo enumerado
NotificationsContentSetting
Tipo enumerado
PluginsContentSetting
Valor
PopupsContentSetting
Tipo enumerado
PpapiBrokerContentSetting
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 especificado.
Scope
O escopo da ContentSetting. Uma destas
regular
: configuração para o perfil normal (que é herdada pelo perfil de navegação anônima se não for modificada em outro lugar),
incognito\_session\_only
: configuração para perfil de navegação anônima que só pode ser definida durante uma sessão anônima e é excluída quando a sessão anônima termina (substitui as configurações normais).
Tipo enumerado
Propriedades
automaticDownloads
Define se os sites podem fazer o download de vários arquivos automaticamente. Uma destas opções:
allow
: permitir que os sites façam o download de vários arquivos automaticamente.
block
: não permite que os sites façam o download de vários arquivos automaticamente.
ask
: pergunta quando um site quer fazer o download automático de arquivos depois do primeiro.
O padrão é ask
.
O URL principal é o URL do frame de nível superior. O URL secundário não é usado.
autoVerify
Define se os sites podem usar a API Private State Tokens. Uma destas 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
.
O URL principal é o URL do frame de nível superior. O URL secundário não é usado. OBSERVAÇÃO: ao chamar set()
, o padrão principal precisa ser .
camera
Define se os sites podem acessar a câmera. 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 URL 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 os dois padrões forem ''.
clipboard
Define se os sites devem acessar a área de transferência por meio de recursos avançados da API Async Clipboard. Os recursos "avançados" incluem tudo além de escrever formatos integrados após um gesto do usuário, como as capacidades de leitura, de formatos personalizados e de escrita sem um gesto do usuário. Uma destas 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 esses recursos.
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.
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 é aquele que representa a origem do cookie. O URL secundário é o URL do frame de nível superior.
fullscreen
Obsoleto. Não tem mais efeito. A permissão de tela cheia agora é concedida automaticamente para todos os sites. O valor é sempre allow
.
images
Indica se imagens serão mostradas. Uma destas 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.
javascript
Define se o JavaScript será executado. Uma destas
allow
: executar o JavaScript,
block
: não executa o JavaScript.
O padrão é allow
.
O URL principal é o URL do frame de nível superior. O URL secundário não é usado.
location
Define se a geolocalização será permitida. Uma destas opções: allow
: permitir que os sites rastreiem sua localização física, block
: não permitir que os 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 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 solicitante).
microphone
Define se os sites podem acessar 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 URL do documento que solicitou o acesso ao microfone. O URL secundário não é usado.
OBSERVAÇÃO: a configuração ''permitir'' não será válida se os dois padrões forem ''.
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
.
notifications
Define se os sites podem mostrar notificações na área de trabalho. Uma destas 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 quer mostrar notificações na área de trabalho.
O padrão é ask
.
O URL principal é o URL do documento que deseja mostrar a notificação. O URL secundário não é usado.
plugins
Obsoleto. Com a remoção do suporte ao Flash no Chrome 88, essa permissão não terá mais efeito. O valor é sempre block
. As chamadas para set()
e clear()
serão ignoradas.
popups
Define se os sites podem mostrar 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 URL do frame de nível superior. O URL secundário não é usado.
unsandboxedPlugins
Obsoleto. Antes controlada se os sites podiam executar plug-ins fora da sandbox, mas com o processo do Flash agente 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.