Descrição
Use a API chrome.permissions
para solicitar permissões opcionais declaradas no momento da execução, em vez de no momento da instalação. Assim, os usuários entendem por que as permissões são necessárias e concedem apenas as necessárias.
Conceitos e uso
Os avisos de permissão descrevem os recursos concedidos por uma API, mas alguns deles podem não ser óbvios. Com a API Permissions, os desenvolvedores podem explicar avisos de permissão e introduzir novos recursos gradualmente, oferecendo aos usuários uma introdução à extensão sem riscos. Dessa forma, os usuários podem especificar a quantidade de acesso que querem conceder e quais recursos querem ativar.
Por exemplo, a funcionalidade principal da extensão de permissões opcionais é modificar a página "Nova guia". Um recurso é exibir a meta do dia do usuário. Esse recurso exige apenas a permissão storage, que não inclui um aviso. A extensão tem um recurso adicional que os usuários podem ativar clicando no seguinte botão:
![Um botão de extensão que ativa recursos adicionais.](https://developer.chrome.com/static/docs/extensions/reference/api/permissions/images/extension-button-enables-c53fe17733b8f.png?authuser=6&hl=pt)
Para exibir os principais sites do usuário, é preciso ter a permissão topSites, que tem o aviso a seguir.
![Aviso de maior intensidade para a API topSites.](https://developer.chrome.com/static/docs/extensions/reference/api/permissions/images/extension-warning-topsit-8927d6b7cb863.png?authuser=6&hl=pt)
topSites
Implementar permissões opcionais
Etapa 1: decidir quais permissões são necessárias e opcionais
Uma extensão pode declarar permissões obrigatórias e opcionais. Em geral, você deve:
- Use as permissões necessárias quando elas forem necessárias para a funcionalidade básica da sua extensão.
- Use permissões opcionais quando elas forem necessárias para recursos opcionais na extensão.
Vantagens das permissões necessárias:
- Menos solicitações:uma extensão pode solicitar que o usuário aceite todas as permissões uma vez.
- Desenvolvimento mais simples:as permissões necessárias têm a garantia de estar presentes.
Vantagens das permissões opcionais:
- Mais segurança:as extensões são executadas com menos permissões porque os usuários só ativam as permissões necessárias.
- Informações melhores para os usuários:uma extensão pode explicar por que precisa de uma permissão específica quando o usuário ativa o recurso relevante.
- Upgrades mais fáceis:quando você fizer upgrade da extensão, o Chrome não a desativará para seus usuários se o upgrade adicionar permissões opcionais em vez de obrigatórias.
Etapa 2: declarar permissões opcionais no manifesto
Declare permissões opcionais no manifesto de extensões com a chave optional_permissions
,
usando o mesmo formato do campo permissions:
{
"name": "My extension",
...
"optional_permissions": ["tabs"],
"optional_host_permissions": ["https://www.google.com/"],
...
}
Se você quiser solicitar hosts que você só descobre no momento da execução, inclua "https://*/*"
no campo optional_host_permissions
da extensão. Isso permite especificar qualquer origem em "Permissions.origins"
, desde que tenha um esquema
correspondente.
Permissões que não podem ser especificadas como opcionais
A maioria das permissões de extensão do Chrome pode ser especificada como opcional, com as seguintes exceções.
Permissão | Descrição |
---|---|
"debugger" |
A API chrome.debugger serve como um transporte alternativo para o protocolo de depuração remota do Chrome. |
"declarativeNetRequest" |
Concede à extensão acesso à API chrome.declarativeNetRequest. |
"devtools" |
Permite que a extensão expanda a funcionalidade do Chrome DevTools. |
"geolocation" |
Permite que a extensão use a API geolocation do HTML5. |
"mdns" |
Concede à extensão acesso à API chrome.mdns. |
"proxy" |
Concede à extensão acesso à API chrome.proxy para gerenciar as configurações de proxy do Chrome. |
"tts" |
A API chrome.tts reproduz a conversão de texto em voz (TTS, na sigla em inglês) sintetizada. |
"ttsEngine" |
A API chrome.ttsEngine implementa um mecanismo de conversão de texto em voz (TTS) usando uma extensão. |
"wallpaper" |
Somente ChromeOS. Use a API chrome.wallpaper para mudar o plano de fundo do ChromeOS. |
Consulte Declarar permissões para mais informações sobre as permissões disponíveis e os respectivos avisos.
Etapa 3: solicitar permissões opcionais
Solicite as permissões de um gesto do usuário usando permissions.request()
:
document.querySelector('#my-button').addEventListener('click', (event) => {
// Permissions must be requested from inside a user gesture, like a button's
// click handler.
chrome.permissions.request({
permissions: ['tabs'],
origins: ['https://www.google.com/']
}, (granted) => {
// The callback argument will be true if the user granted the permissions.
if (granted) {
doSomething();
} else {
doSomethingElse();
}
});
});
O Chrome perguntará ao usuário se a adição das permissões resulta em mensagens de aviso diferentes das que o usuário já viu e aceitou. Por exemplo, o código anterior pode resultar em uma solicitação como este:
![Um exemplo de prompt de confirmação de permissão.](https://developer.chrome.com/static/docs/extensions/reference/api/permissions/images/perms-optional.png?authuser=6&hl=pt)
Etapa 4: verificar as permissões atuais da extensão
Para verificar se a extensão tem uma permissão específica ou um conjunto de permissões, use permission.contains()
:
chrome.permissions.contains({
permissions: ['tabs'],
origins: ['https://www.google.com/']
}, (result) => {
if (result) {
// The extension has the permissions.
} else {
// The extension doesn't have the permissions.
}
});
Etapa 5: remover as permissões
Remova permissões quando não precisar mais delas. Depois que uma permissão é removida,
chamar permissions.request()
geralmente adiciona a permissão novamente, sem notificar o usuário.
chrome.permissions.remove({
permissions: ['tabs'],
origins: ['https://www.google.com/']
}, (removed) => {
if (removed) {
// The permissions have been removed.
} else {
// The permissions have not been removed (e.g., you tried to remove
// required permissions).
}
});
Tipos
Permissions
Propriedades
-
origens
string[] opcional
A lista de permissões de host, incluindo as especificadas nas chaves
optional_permissions
oupermissions
no manifesto e aquelas associadas a scripts de conteúdo. -
permissões
string[] opcional
Lista de permissões nomeadas (não inclui hosts ou origens).
Métodos
contains()
chrome.permissions.contains(
permissions: Permissions,
callback?: function,
)
Verifica se a extensão tem as permissões especificadas.
Parâmetros
-
permissões
-
callback
função optional
O parâmetro
callback
tem esta aparência:(result: boolean) => void
-
resultado
boolean
Verdadeiro se a extensão tiver as permissões especificadas. Se uma origem for especificada como uma permissão opcional e um padrão de correspondência de script de conteúdo, retornará
false
, a menos que as duas permissões sejam concedidas.
-
Retorna
-
Promise<boolean>
Chrome 96 ou mais recentePromessas são compatíveis com o Manifest V3 e versões mais recentes, mas 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 que é passado para o callback.
getAll()
chrome.permissions.getAll(
callback?: function,
)
Extrai o conjunto de permissões atual da extensão.
Parâmetros
-
callback
função optional
O parâmetro
callback
tem esta aparência:(permissions: Permissions) => void
-
permissões
As permissões ativas da extensão. Observe que a propriedade
origins
contém origens concedidas daquelas especificadas nas chavespermissions
eoptional_permissions
do manifesto e aquelas associadas aos scripts de conteúdo.
-
Retorna
-
Promessa<Permissões>
Chrome 96 ou mais recentePromessas são compatíveis com o Manifest V3 e versões mais recentes, mas 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 que é passado para o callback.
remove()
chrome.permissions.remove(
permissions: Permissions,
callback?: function,
)
Remove o acesso às permissões especificadas. Se houver algum problema ao remover as permissões, runtime.lastError
será definido.
Parâmetros
-
permissões
-
callback
função optional
O parâmetro
callback
tem esta aparência:(removed: boolean) => void
-
removido
boolean
Verdadeiro se as permissões tiverem sido removidas.
-
Retorna
-
Promise<boolean>
Chrome 96 ou mais recentePromessas são compatíveis com o Manifest V3 e versões mais recentes, mas 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 que é passado para o callback.
request()
chrome.permissions.request(
permissions: Permissions,
callback?: function,
)
Solicita acesso às permissões especificadas, exibindo uma solicitação ao usuário, se necessário. Essas permissões precisam ser definidas no campo optional_permissions
do manifesto ou ser permissões obrigatórias retidas pelo usuário. Os caminhos em padrões de origem serão ignorados. É possível solicitar subconjuntos de permissões de origem opcionais. Por exemplo, se você especificar *://*\/*
na seção optional_permissions
do manifesto, será possível solicitar http://example.com/
. Caso haja algum problema ao solicitar as permissões, o runtime.lastError
será definido.
Parâmetros
-
permissões
-
callback
função optional
O parâmetro
callback
tem esta aparência:(granted: boolean) => void
-
concedido
boolean
Verdadeiro se o usuário concedeu as permissões especificadas.
-
Retorna
-
Promise<boolean>
Chrome 96 ou mais recentePromessas são compatíveis com o Manifest V3 e versões mais recentes, mas 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 que é passado para o callback.
Eventos
onAdded
chrome.permissions.onAdded.addListener(
callback: function,
)
Disparado quando a extensão adquire novas permissões.
Parâmetros
-
callback
função
O parâmetro
callback
tem esta aparência:(permissions: Permissions) => void
-
permissões
-
onRemoved
chrome.permissions.onRemoved.addListener(
callback: function,
)
Disparado quando o acesso às permissões é removido da extensão.
Parâmetros
-
callback
função
O parâmetro
callback
tem esta aparência:(permissions: Permissions) => void
-
permissões
-