Descrição
Use a API chrome.permissions
para solicitar permissões opcionais declaradas no ambiente de execução, e não no momento da instalação. Assim, os usuários entendem por que as permissões são necessárias e concedem apenas as que são necessárias.
Conceitos e uso
Há avisos de permissão para descrever os recursos concedidos por uma API, mas alguns deles podem não ser óbvios. A API Permissions permite que os desenvolvedores expliquem avisos de permissão e apresentem novos recursos gradualmente, oferecendo aos usuários uma introdução sem riscos à extensão. Dessa forma, os usuários podem especificar a quantidade de acesso que querem conceder e quais recursos querem ativar.
Por exemplo, o recurso principal da extensão de permissões opcionais é modificar a página "Nova guia". Um deles é exibir o objetivo do dia do usuário. Esse recurso requer 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 neste 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=19&hl=pt)
Para exibir os principais sites do usuário, é preciso ter a permissão topSites, que mostra o aviso a seguir.
![Aviso de axtensão da API topSites.](https://developer.chrome.com/static/docs/extensions/reference/api/permissions/images/extension-warning-topsit-8927d6b7cb863.png?authuser=19&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 sua extensão.
Vantagens das permissões obrigatórias:
- Menos solicitações:uma extensão pode solicitar que o usuário aceite todas as permissões uma vez.
- Desenvolvimento mais simples:é garantido que as permissões necessárias estarão presentes.
Vantagens das permissões opcionais:
- Maior segurança:as extensões são executadas com menos permissões, já que os usuários só dão acesso a elas. necessários.
- 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ê faz upgrade da sua extensão, o Chrome não a desativa para os usuários se o upgrade adiciona 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
.
com 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 só descobre durante a execução, inclua "https://*/*"
no campo optional_host_permissions
da extensão. Isso permite especificar qualquer origem em "Permissions.origins"
, desde que ela tenha uma
esquema.
Permissões que não podem ser especificadas como opcionais
A maioria das permissões de extensões do Chrome pode ser especificada como opcional, com as seguintes exceções.
Permissão | Descrição |
---|---|
"debugger" |
A API chrome.debugger serve como uma transporte alternativo para depuração remota do Google Chrome protocolo. |
"declarativeNetRequest" |
Concede à extensão acesso ao chrome.declarativeNetRequest. |
"devtools" |
Permite que a extensão expanda Chrome DevTools funcionalidade de armazenamento. |
"geolocation" |
Permite que a extensão use a API geolocation do HTML5. |
"mdns" |
Concede à extensão acesso ao chrome.mdns. |
"proxy" |
Concede à extensão acesso à API chrome.proxy para gerenciar o proxy do Chrome configurações. |
"tts" |
A API chrome.tts toca conversão de texto em voz (TTS). |
"ttsEngine" |
A API chrome.ttsEngine implementa uma conversão de texto em voz (TTS) usando uma extensão. |
"wallpaper" |
Somente ChromeOS. Usar a API chrome.wallpaper para mudar o ChromeOS plano de fundo. |
Consulte Declarar permissões para mais informações sobre permissões disponíveis e os alertas.
Etapa 3: solicitar permissões opcionais
Solicite as permissões a partir 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 avisa o usuário se a adição das permissões resulta em mensagens de aviso diferentes que o usuário já viu e aceitou. Por exemplo, o código anterior pode resultar em um comando como isso:
![Exemplo de solicitação de confirmação de permissão.](https://developer.chrome.com/static/docs/extensions/reference/api/permissions/images/perms-optional.png?authuser=19&hl=pt)
Etapa 4: verificar as permissões atuais da extensão
Para verificar se sua 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 as permissões quando não precisar mais delas. Depois que uma permissão é removida,
Chamar permissions.request()
geralmente adiciona a permissão de volta sem solicitar ao 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 as 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 opcional
O parâmetro
callback
tem esta aparência:(result: boolean) => void
-
resultado
booleano
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, será retornado
false
, a menos que as duas permissões sejam concedidas.
-
Retorna
-
Promise<boolean>
Chrome 96 ou versão mais recenteO Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para a 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 ao retorno de chamada.
getAll()
chrome.permissions.getAll(
callback?: function,
)
Recebe o conjunto atual de permissões da extensão.
Parâmetros
-
callback
função opcional
O parâmetro
callback
tem esta aparência:(permissions: Permissions) => void
-
permissões
As permissões ativas da extensão. A propriedade
origins
vai conter origens concedidas daquelas especificadas nas chavespermissions
eoptional_permissions
do manifesto e as associadas a scripts de conteúdo.
-
Retorna
-
Promise<Permissions>
Chrome 96 ou versão mais recenteO Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para a 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 ao retorno de chamada.
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 opcional
O parâmetro
callback
tem esta aparência:(removed: boolean) => void
-
removida
booleano
Verdadeiro se as permissões foram removidas.
-
Retorna
-
Promise<boolean>
Chrome 96 ou versão mais recenteO Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para a 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 ao retorno de chamada.
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 que foram retidas pelo usuário. Os caminhos nos 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, poderá solicitar http://example.com/
. Se houver algum problema ao solicitar as permissões, runtime.lastError
será definido.
Parâmetros
-
permissões
-
callback
função opcional
O parâmetro
callback
tem esta aparência:(granted: boolean) => void
-
concedido
booleano
Verdadeiro se o usuário tiver concedido as permissões especificadas.
-
Retorna
-
Promise<boolean>
Chrome 96 ou versão mais recenteO Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para a 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 ao retorno de chamada.
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 foi removido da extensão.
Parâmetros
-
callback
função
O parâmetro
callback
tem esta aparência:(permissions: Permissions) => void
-
permissões
-