chrome.permissions

Descripción

Usa la API de chrome.permissions para solicitar permisos opcionales declarados durante el tiempo de ejecución en lugar del tiempo de 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 que otorga una API, pero es posible que algunas de estas advertencias no sean evidentes. La API de Permissions permite a los desarrolladores explicar las advertencias de permisos y presentar funciones nuevas de forma gradual, lo que les brinda a los usuarios una introducción sin riesgos a la extensión. De esta manera, los usuarios pueden especificar qué nivel de acceso están dispuestos a otorgar y qué funciones quieren habilitar.

Por ejemplo, la funcionalidad principal de la extensión de permisos opcionales anula 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.
Un botón de extensión que habilita funciones adicionales.

Para mostrar los sitios principales del usuario, se requiere el permiso topSites, que tiene la siguiente advertencia.

Advertencia de extensión para la API de topSites.
Una advertencia de extensión para la API de topSites

Cómo implementar 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, debes 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 indicaciones: Una extensión puede solicitarle al usuario una vez que acepte todos los permisos.
  • Desarrollo más simple: Se garantiza que los permisos necesarios estén presentes.

Ventajas de los permisos opcionales:

  • Mayor 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 fáciles: Cuando actualices tu extensión, Chrome no la inhabilitará 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 el manifiesto de la extensión con la clave optional_permissions, con 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 en 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 que coincida.

Permisos que no se pueden especificar como opcionales

La mayoría de los permisos de extensiones de Chrome se pueden especificar como opcionales, con las siguientes excepciones.

Permiso Descripción
"debugger" La API de chrome.debugger funciona como un 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 Chrome DevTools.
"geolocation" Permite que la extensión use la API de ubicación geográfica 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 ya vio y aceptó. Por ejemplo, el código anterior podría generar un mensaje como el siguiente:

Ejemplo de mensaje de confirmación de permisos.
Ejemplo de mensaje de confirmación de permisos.

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

Debes quitar los permisos cuando ya no los necesites. Después de quitar un permiso, llamar a permissions.request() suele volver a agregarlo sin solicitarle 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

    La lista de permisos de host, incluidos los especificados en las claves optional_permissions o permissions del manifiesto y los asociados con las secuencias de comandos de contenido

  • permisos

    string[] opcional

    Es una lista de permisos con nombre (no incluye hosts ni orígenes).

Métodos

addSiteAccessRequest()

Promesa PendienteMV3+ 
chrome.permissions.addSiteAccessRequest(
  request: object,
  callback?: function,
)

Agrega una solicitud de acceso al sitio. La solicitud solo se indicará al usuario si se le puede otorgar acceso al sitio en la solicitud. La solicitud se restablecerá en la navegación de origen cruzado. Cuando se acepta, otorga acceso persistente al origen principal del sitio.

Parámetros

  • request

    objeto

    • documentId

      cadena opcional

      Es el ID de un documento en el que se pueden mostrar las solicitudes de acceso al sitio. Debe ser el documento de nivel superior dentro de una pestaña. Si se proporciona, la solicitud se muestra en la pestaña del documento especificado y se quita cuando el documento navega a un origen nuevo. Si agregas una solicitud nueva, se anulará cualquier solicitud existente para tabId. Se debe especificar esto o tabId.

    • patrón

      cadena opcional

      Es el patrón de URL en el que se pueden mostrar las solicitudes de acceso al sitio. Si se proporciona, las solicitudes de acceso al sitio solo se mostrarán en las URLs que coincidan con este patrón.

    • tabId

      número opcional

      Es el ID de la pestaña en la que se pueden mostrar las solicitudes de acceso al sitio. Si se proporciona, la solicitud se muestra en la pestaña especificada y se quita cuando la pestaña navega a un origen nuevo. Si agregas una solicitud nueva, se anulará una solicitud existente para documentId. Se debe especificar esto o documentId.

  • callback

    función opcional

    El parámetro callback se ve de la siguiente manera: 

    () => void

Muestra

  • Promise<void>

    Las promesas son compatibles con el manifiesto V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para la 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.

contains()

Promesa 
chrome.permissions.contains(
  permissions: Permissions,
  callback?: function,
)

Verifica si la extensión tiene los permisos especificados.

Parámetros

  • permisos

    Permisos

  • callback

    función opcional

    El parámetro callback se ve de la siguiente manera: 

    (result: boolean) => void

    • resultado

      booleano

      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 de contenido, se mostrará false, a menos que se otorguen ambos permisos.

Muestra

  • Promise<boolean>

    Chrome 96 y versiones posteriores

    Las promesas son compatibles con el manifiesto V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para la 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()

Promesa 
chrome.permissions.getAll(
  callback?: function,
)

Obtiene el conjunto de permisos actual de la extensión.

Parámetros

  • callback

    función opcional

    El parámetro callback se ve de la siguiente manera: 

    (permissions: Permissions) => void

    • permisos

      Permisos

      Los permisos activos de la extensión Ten en cuenta que la propiedad origins contendrá los orígenes otorgados de los especificados en las claves permissions y optional_permissions del manifiesto y los asociados con las secuencias de comandos de contenido.

Muestra

  • Promise<Permissions>

    Chrome 96 y versiones posteriores

    Las promesas son compatibles con el manifiesto V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para la 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()

Promesa 
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

    Permisos

  • callback

    función opcional

    El parámetro callback se ve de la siguiente manera: 

    (removed: boolean) => void

    • quitado

      booleano

      Es verdadero si se quitaron los permisos.

Muestra

  • Promise<boolean>

    Chrome 96 y versiones posteriores

    Las promesas son compatibles con el manifiesto V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para la 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.

removeSiteAccessRequest()

Promesa PendienteMV3+ 
chrome.permissions.removeSiteAccessRequest(
  request: object,
  callback?: function,
)

Quita una solicitud de acceso al sitio, si existe.

Parámetros

  • request

    objeto

    • documentId

      cadena opcional

      Es el ID de un documento en el que se quitará la solicitud de acceso al sitio. Debe ser el documento de nivel superior dentro de una pestaña. Se debe especificar esto o tabId.

    • patrón

      cadena opcional

      Es el patrón de URL en el que se quitará la solicitud de acceso al sitio. Si se proporciona, debe coincidir exactamente con el patrón de una solicitud de acceso al sitio existente.

    • tabId

      número opcional

      Es el ID de la pestaña en la que se quitará la solicitud de acceso al sitio. Se debe especificar esto o documentId.

  • callback

    función opcional

    El parámetro callback se ve de la siguiente manera: 

    () => void

Muestra

  • Promise<void>

    Las promesas son compatibles con el manifiesto V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para la 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()

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

    Permisos

  • callback

    función opcional

    El parámetro callback se ve de la siguiente manera: 

    (granted: boolean) => void

    • concedido

      booleano

      Es verdadero si el usuario otorgó los permisos especificados.

Muestra

  • Promise<boolean>

    Chrome 96 y versiones posteriores

    Las promesas son compatibles con el manifiesto V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para la 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

    función

    El parámetro callback se ve de la siguiente manera: 

    (permissions: Permissions) => void

onRemoved

chrome.permissions.onRemoved.addListener(
  callback: function,
)

Se activa cuando se quita el acceso a los permisos de la extensión.

Parámetros

  • callback

    función

    El parámetro callback se ve de la siguiente manera: 

    (permissions: Permissions) => void