Descripción
Usa la API de chrome.permissions
para solicitar permisos opcionales declarados durante el tiempo de ejecución en lugar de la instalación, de modo que los usuarios comprendan por qué se necesitan los permisos y otorguen solo los que sean necesarios.
Conceptos y uso
Las advertencias de permisos existen para describir las capacidades otorgadas por una API, pero es posible que algunas de estas advertencias no sean evidentes. La API de Permissions permite a los desarrolladores explicar advertencias de permisos e introducir nuevas funciones gradualmente, lo que brinda a los usuarios una introducción sin riesgos a la extensión. De esta forma, los usuarios pueden especificar la cantidad de acceso que están dispuestos a otorgar y las funciones que quieren habilitar.
Por ejemplo, la funcionalidad principal de la extensión de permisos opcional es la anulación de la página Nueva pestaña. Una función muestra el objetivo del día del usuario. Esta función solo requiere el permiso de almacenamiento, que no incluye una advertencia. La extensión tiene una función adicional que los usuarios pueden habilitar haciendo clic en el siguiente botón:
![Un botón de extensión que habilita funciones adicionales](https://developer.chrome.google.cn/static/docs/extensions/reference/api/permissions/images/extension-button-enables-c53fe17733b8f.png?authuser=9&hl=es)
Para mostrar los sitios principales del usuario, se requiere el permiso topSites, que incluye la siguiente advertencia.
![Advertencia de extensión para la API de topSites.](https://developer.chrome.google.cn/static/docs/extensions/reference/api/permissions/images/extension-warning-topsit-8927d6b7cb863.png?authuser=9&hl=es)
topSites
Implementa permisos opcionales
Paso 1: Decide qué permisos son obligatorios y cuáles son opcionales
Una extensión puede declarar permisos obligatorios y opcionales. En general, deberías hacer lo siguiente:
- Usa los permisos necesarios cuando sean necesarios para la funcionalidad básica de tu extensión.
- Usa permisos opcionales cuando sean necesarios para las funciones opcionales de tu extensión.
Ventajas de los permisos obligatorios:
- Menos mensajes: Una extensión puede solicitarle al usuario que acepte todos los permisos una vez.
- Desarrollo más sencillo: Se garantiza la presencia de los permisos necesarios.
Ventajas de los permisos opcionales:
- Mejor seguridad: Las extensiones se ejecutan con menos permisos, ya que los usuarios solo habilitan los permisos necesarios.
- Mejor información para los usuarios: Una extensión puede explicar por qué necesita un permiso en particular cuando el usuario habilita la función relevante.
- Actualizaciones más sencillas: Cuando actualizas tu extensión, Chrome no la inhabilita para los usuarios si la actualización agrega permisos opcionales en lugar de obligatorios.
Paso 2: Declara permisos opcionales en el manifiesto
Declara permisos opcionales en tu manifiesto de extensión con la clave optional_permissions
y usa el mismo formato que el campo permissions:
{
"name": "My extension",
...
"optional_permissions": ["tabs"],
"optional_host_permissions": ["https://www.google.com/"],
...
}
Si deseas solicitar hosts que solo descubres durante el tiempo de ejecución, incluye "https://*/*"
en el campo optional_host_permissions
de tu extensión. Esto te permite especificar cualquier origen en "Permissions.origins"
, siempre que tenga un esquema coincidente.
Permisos que no se pueden especificar como opcionales
La mayoría de los permisos de las extensiones de Chrome se pueden especificar como opcionales, con las siguientes excepciones.
Permisos | Descripción |
---|---|
"debugger" |
La API de chrome.debugger sirve como transporte alternativo para el protocolo de depuración remota de Chrome. |
"declarativeNetRequest" |
Otorga a la extensión acceso a la API de chrome.declarativeNetRequest. |
"devtools" |
Permite que la extensión expanda la funcionalidad de las Herramientas para desarrolladores de Chrome. |
"geolocation" |
Permite que la extensión use la API de geolocation de HTML5. |
"mdns" |
Otorga a la extensión acceso a la API de chrome.mdns. |
"proxy" |
Otorga a la extensión acceso a la API de chrome.proxy para administrar la configuración de proxy de Chrome. |
"tts" |
La API de chrome.tts reproduce texto a voz (TTS) sintetizado. |
"ttsEngine" |
La API de chrome.ttsEngine implementa un motor de texto a voz (TTS) con una extensión. |
"wallpaper" |
Solo para ChromeOS. Usa la API de chrome.wallpaper para cambiar el fondo de pantalla de ChromeOS. |
Consulta Cómo declarar permisos para obtener más información sobre los permisos disponibles y sus advertencias.
Paso 3: Solicita permisos opcionales
Solicita los permisos desde un gesto del usuario con 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();
}
});
});
Chrome le pregunta al usuario si agregar los permisos genera mensajes de advertencia diferentes de los que el usuario ya vio y aceptó. Por ejemplo, el código anterior puede generar un mensaje como el siguiente:
![Un ejemplo de mensaje de confirmación de permiso.](https://developer.chrome.google.cn/static/docs/extensions/reference/api/permissions/images/perms-optional.png?authuser=9&hl=es)
Paso 4: Verifica los permisos actuales de la extensión
Para verificar si tu extensión tiene un permiso o un conjunto de permisos específicos, usa
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.
}
});
Paso 5: Quita los permisos
Quita los permisos cuando ya no los necesites. Después de quitar un permiso, cuando se llama a permissions.request()
, por lo general, se vuelve a agregar el permiso sin pedirle al usuario.
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
Propiedades
-
orígenes
string[] opcional
Lista de permisos de host, incluidos aquellos especificados en las claves
optional_permissions
opermissions
del manifiesto, y aquellos asociados con Secuencias de comandos de contenido. -
permisos
string[] opcional
Lista de permisos con nombre (no incluye orígenes ni hosts).
Métodos
contains()
chrome.permissions.contains(
permissions: Permissions,
callback?: function,
)
Comprueba si la extensión tiene los permisos especificados.
Parámetros
-
permisos
-
callback
Función opcional
El parámetro
callback
se ve de la siguiente manera:(result: boolean) => void
-
resultado
boolean
Es verdadero si la extensión tiene los permisos especificados. Si se especifica un origen como un permiso opcional y un patrón de coincidencia de secuencia de comandos del contenido, se mostrará
false
a menos que se otorguen ambos permisos.
-
Devuelve
-
Promise<boolean>
Chrome 96 y versiones posterioresLas promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para brindar retrocompatibilidad. No puedes usar ambos en la misma llamada a función. La promesa se resuelve con el mismo tipo que se pasa a la devolución de llamada.
getAll()
chrome.permissions.getAll(
callback?: function,
)
Obtiene el conjunto actual de permisos de la extensión.
Parámetros
-
callback
Función opcional
El parámetro
callback
se ve de la siguiente manera:(permissions: Permissions) => void
-
permisos
Los permisos activos de la extensión. Ten en cuenta que la propiedad
origins
contendrá orígenes otorgados de aquellos especificados en las clavespermissions
yoptional_permissions
del manifiesto y aquellos asociados con Content Script.
-
Devuelve
-
Promesa<Permisos>
Chrome 96 y versiones posterioresLas promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para brindar retrocompatibilidad. No puedes usar ambos en la misma llamada a función. La promesa se resuelve con el mismo tipo que se pasa a la devolución de llamada.
remove()
chrome.permissions.remove(
permissions: Permissions,
callback?: function,
)
Quita el acceso a los permisos especificados. Si hay algún problema para quitar los permisos, se establecerá runtime.lastError
.
Parámetros
-
permisos
-
callback
Función opcional
El parámetro
callback
se ve de la siguiente manera:(removed: boolean) => void
-
eliminada
boolean
Es verdadero si se quitaron los permisos.
-
Devuelve
-
Promise<boolean>
Chrome 96 y versiones posterioresLas promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para brindar retrocompatibilidad. No puedes usar ambos en la misma llamada a función. La promesa se resuelve con el mismo tipo que se pasa a la devolución de llamada.
request()
chrome.permissions.request(
permissions: Permissions,
callback?: function,
)
Solicita acceso a los permisos especificados y muestra un mensaje al usuario si es necesario. Estos permisos deben definirse en el campo optional_permissions
del manifiesto o deben ser permisos obligatorios que el usuario retuvo. Se ignorarán las rutas de acceso en los patrones de origen. Puedes solicitar subconjuntos de permisos de origen opcionales. Por ejemplo, si especificas *://*\/*
en la sección optional_permissions
del manifiesto, puedes solicitar http://example.com/
. Si hay algún problema para solicitar los permisos, se establecerá runtime.lastError
.
Parámetros
-
permisos
-
callback
Función opcional
El parámetro
callback
se ve de la siguiente manera:(granted: boolean) => void
-
concedido
boolean
Es verdadero si el usuario otorgó los permisos especificados.
-
Devuelve
-
Promise<boolean>
Chrome 96 y versiones posterioresLas promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para brindar retrocompatibilidad. No puedes usar ambos en la misma llamada a función. La promesa se resuelve con el mismo tipo que se pasa a la devolución de llamada.
Eventos
onAdded
chrome.permissions.onAdded.addListener(
callback: function,
)
Se activa cuando la extensión adquiere permisos nuevos.
Parámetros
-
callback
la función
El parámetro
callback
se ve de la siguiente manera:(permissions: Permissions) => void
-
permisos
-
onRemoved
chrome.permissions.onRemoved.addListener(
callback: function,
)
Se activa cuando se quita el acceso a los permisos de la extensión.
Parámetros
-
callback
la función
El parámetro
callback
se ve de la siguiente manera:(permissions: Permissions) => void
-
permisos
-