chrome.contentSettings

Descripción

Usa la API de chrome.contentSettings para cambiar la configuración que controla si los sitios web pueden usar funciones como cookies, JavaScript y complementos. En términos más generales, la configuración de contenido te permite personalizar el comportamiento de Chrome por sitio en lugar de hacerlo de forma global.

Permisos

contentSettings

Para usar la API, debes declarar el permiso "contentSettings" en el manifiesto de tu extensión. Por ejemplo:

{
  "name": "My extension",
  ...
  "permissions": [
    "contentSettings"
  ],
  ...
}

Conceptos y uso

Patrones de configuración de contenido

Puedes usar patrones para especificar los sitios web a los que afecta cada configuración de contenido. Por ejemplo, https://*.youtube.com/* especifica youtube.com y todos sus subdominios. La sintaxis de los patrones de configuración de contenido es la misma que la de los patrones de coincidencia, con algunas diferencias:

  • Para las URLs http, https y ftp, la ruta de acceso debe ser un comodín (/*). Para las URLs file, la ruta de acceso debe especificarse por completo y no debe contener comodines.
  • A diferencia de los patrones de coincidencia, los patrones de configuración de contenido pueden especificar un número de puerto. Si se especifica un número de puerto, el patrón solo coincide con los sitios web que tienen ese puerto. Si no se especifica un número de puerto, el patrón coincide con todos los puertos.

Prioridad de los patrones

Cuando se aplica más de una regla de configuración de contenido para un sitio determinado, la regla con el patrón más específico tiene prioridad.

Por ejemplo, los siguientes patrones se ordenan por prioridad:

  1. https://www.example.com/*
  2. https://*.example.com/* (coincide con example.com y todos los subdominios)
  3. <all_urls> (coincide con cada URL)

Hay tres tipos de comodines que afectan la especificidad de un patrón:

  • Comodines en el puerto (por ejemplo, https://www.example.com:*/*)
  • Comodines en el esquema (por ejemplo, *://www.example.com:123/*)
  • Comodines en el nombre de host (por ejemplo, https://*.example.com:123/*)

Si un patrón es más específico que otro en una parte, pero menos específico en otra, las diferentes partes se verifican en el siguiente orden: nombre de host, esquema y puerto. Por ejemplo, los siguientes patrones se ordenan por prioridad:

  1. https://www.example.com:*/* Especifica el nombre de host y el esquema.
  2. *:/www.example.com:123/* No es tan alto, ya que, aunque especifica el nombre de host, no especifica el esquema.
  3. https://*.example.com:123/* Es inferior porque, aunque especifica el puerto y el esquema, tiene un comodín en el nombre de host.

Patrones primarios y secundarios

La URL que se tiene en cuenta para decidir qué configuración de contenido aplicar depende del tipo de contenido. Por ejemplo, para contentSettings.notifications, la configuración se basa en la URL que se muestra en la barra de direcciones. Esta URL se denomina "principal".

Algunos tipos de contenido pueden tener en cuenta URLs adicionales. Por ejemplo, si un sitio puede configurar un contentSettings.cookies se decide en función de la URL de la solicitud HTTP (que es la URL principal en este caso) y de la URL que se muestra en la barra omni (que se denomina URL "secundaria").

Si varias reglas tienen patrones primarios y secundarios, la regla con el patrón primario más específico tiene precedencia. Si varias reglas tienen el mismo patrón principal, prevalece la regla con el patrón secundario más específico. Por ejemplo, la siguiente lista de pares de patrones primarios y secundarios está ordenada por prioridad:

PrioridadPatrón principalPatrón secundario
1https://www.moose.com/*,https://www.wombat.com/*
2https://www.moose.com/*,<all_urls>
3<all_urls>,https://www.wombat.com/*
4<all_urls>,<all_urls>

Los patrones secundarios no son compatibles con el parámetro de configuración de contenido de imágenes.

Identificadores de recursos

Los identificadores de recursos te permiten especificar la configuración de contenido para subtipos específicos de un tipo de contenido. Actualmente, el único tipo de contenido que admite identificadores de recursos es contentSettings.plugins, en el que un identificador de recursos identifica un complemento específico. Cuando se aplica la configuración de contenido, primero se verifica la configuración del complemento específico. Si no se encuentra ninguna configuración para el complemento específico, se verifica la configuración general de contenido de los complementos.

Por ejemplo, si una regla de configuración de contenido tiene el identificador de recurso adobe-flash-player y el patrón <all_urls>, tiene prioridad sobre una regla sin un identificador de recurso y el patrón https://www.example.com/*, incluso si ese patrón es más específico.

Para obtener una lista de identificadores de recursos de un tipo de contenido, llama al método contentSettings.ContentSetting.getResourceIdentifiers(). La lista que se muestra puede cambiar con el conjunto de complementos instalados en la máquina del usuario, pero Chrome intenta mantener los identificadores estables en todas las actualizaciones de complementos.

Ejemplos

Para probar esta API, instala el ejemplo de la API de contentSettings desde el repositorio chrome-extension-samples.

Tipos

AutoVerifyContentSetting

Chrome 113 y versiones posteriores

Enum

"allow"

"block"

CameraContentSetting

Chrome 46 y versiones posteriores

Enum

"allow"

"block"

"ask"

ClipboardContentSetting

Chrome 121 y versiones posteriores

Enum

"allow"

"block"

"ask"

ContentSetting

Propiedades

  • borrar

    void

    Promesa

    Borra todas las reglas de configuración de contenido que estableció esta extensión.

    La función clear se ve de la siguiente manera: 

    (details: object, callback?: function) => {...}

    • detalles

      objeto

      • alcance

        Alcance opcional

        Dónde borrar la configuración (predeterminada: normal).

    • callback

      función opcional

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

      () => void

    • muestra

      Promise<void>

      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.

  • get

    void

    Promesa

    Obtiene la configuración de contenido actual para un par determinado de URLs.

    La función get se ve de la siguiente manera: 

    (details: object, callback?: function) => {...}

    • detalles

      objeto

      • incógnito

        booleano opcional

        Indica si se debe verificar la configuración de contenido para una sesión en modo Incógnito. (predeterminado: falso)

      • primaryUrl

        string

        Es la URL principal para la que se debe recuperar la configuración de contenido. Ten en cuenta que el significado de una URL principal depende del tipo de contenido.

      • resourceIdentifier

        ResourceIdentifier opcional

        Es un identificador más específico del tipo de contenido para el que se debe recuperar la configuración.

      • secondaryUrl

        cadena opcional

        Es la URL secundaria para la que se debe recuperar la configuración de contenido. El valor predeterminado es la URL principal. Ten en cuenta que el significado de una URL secundaria depende del tipo de contenido, y no todos los tipos de contenido usan URLs secundarias.

    • callback

      función opcional

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

      (details: object) => void

      • detalles

        objeto

        • Estableciendo

          T

          Es el parámetro de configuración de contenido. Consulta la descripción de los objetos ContentSetting individuales para conocer los valores posibles.

    • muestra

      Promise<object>

      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.

  • getResourceIdentifiers

    void

    Promesa

    La función getResourceIdentifiers se ve de la siguiente manera: 

    (callback?: function) => {...}

    • callback

      función opcional

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

      (resourceIdentifiers?: ResourceIdentifier[]) => void

      • resourceIdentifiers

        ResourceIdentifier[] opcional

        Es una lista de identificadores de recursos para este tipo de contenido o undefined si este tipo de contenido no usa identificadores de recursos.

    • muestra

      Promise<ResourceIdentifier[]>

      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.

  • set

    void

    Promesa

    Aplica una nueva regla de configuración de contenido.

    La función set se ve de la siguiente manera: 

    (details: object, callback?: function) => {...}

    • detalles

      objeto

      • primaryPattern

        string

        Es el patrón de la URL principal. Para obtener detalles sobre el formato de un patrón, consulta Patrones de configuración de contenido.

      • resourceIdentifier

        ResourceIdentifier opcional

        Es el identificador de recursos del tipo de contenido.

      • alcance

        Alcance opcional

        Dónde establecer el parámetro de configuración (predeterminado: normal).

      • secondaryPattern

        cadena opcional

        Es el patrón de la URL secundaria. De forma predeterminada, coincide con todas las URLs. Para obtener detalles sobre el formato de un patrón, consulta Patrones de configuración de contenido.

      • Estableciendo

        cualquiera

        Es el parámetro de configuración que aplica esta regla. Consulta la descripción de los objetos ContentSetting individuales para conocer los valores posibles.

    • callback

      función opcional

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

      () => void

    • muestra

      Promise<void>

      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.

CookiesContentSetting

Chrome 44 y versiones posteriores

Enum

"allow"

"block"

"session_only"

FullscreenContentSetting

Chrome 44 y versiones posteriores

Valor

"allow"

ImagesContentSetting

Chrome 44 y versiones posteriores

Enum

"allow"

"block"

JavascriptContentSetting

Chrome 44 y versiones posteriores

Enum

"allow"

"block"

LocationContentSetting

Chrome 44 y versiones posteriores

Enum

"allow"

"block"

"ask"

MicrophoneContentSetting

Chrome 46 y versiones posteriores

Enum

"allow"

"block"

"ask"

MouselockContentSetting

Chrome 44 y versiones posteriores

Valor

"allow"

MultipleAutomaticDownloadsContentSetting

Chrome 44 y versiones posteriores

Enum

"allow"

"block"

"ask"

NotificationsContentSetting

Chrome 44 y versiones posteriores

Enum

"allow"

"block"

"ask"

PluginsContentSetting

Chrome 44 y versiones posteriores

Valor

"block"

PopupsContentSetting

Chrome 44 y versiones posteriores

Enum

"allow"

"block"

PpapiBrokerContentSetting

Chrome 44 y versiones posteriores

Valor

"block"

ResourceIdentifier

El único tipo de contenido que usa identificadores de recursos es contentSettings.plugins. Para obtener más información, consulta Identificadores de recursos.

Propiedades

  • descripción

    cadena opcional

    Es una descripción legible por humanos del recurso.

  • id

    string

    Es el identificador de recursos del tipo de contenido determinado.

Scope

Chrome 44 y versiones posteriores

El permiso de ContentSetting. Uno de los siguientes: regular: Configuración para el perfil normal (que hereda el perfil incógnito si no se anula en otro lugar) incognito\_session\_only: Configuración para el perfil incógnito que solo se puede establecer durante una sesión incógnita y se borra cuando finaliza (anula la configuración normal).

Enum

"regular"

"incognito_session_only"

Propiedades

automaticDownloads

Permite que los sitios descarguen varios archivos automáticamente. Una de las siguientes opciones: allow: Permitir que los sitios descarguen varios archivos automáticamente, block: No permitir que los sitios descarguen varios archivos automáticamente, ask: Preguntar cuando un sitio quiere descargar archivos automáticamente después del primero. El valor predeterminado es ask. La URL principal es la URL del marco de nivel superior. No se usa la URL secundaria.

Tipo

ContentSetting<MultipleAutomaticDownloadsContentSetting>

autoVerify

Chrome 113 y versiones posteriores

Si se permite que los sitios usen la API de Private State Tokens Una de las siguientes opciones: allow: Permitir que los sitios usen la API de Private State Tokens, block: Bloquear los sitios para que no usen la API de Private State Tokens. El valor predeterminado es allow. La URL principal es la URL del marco de nivel superior. No se usa la URL secundaria. NOTA: Cuando llames a set(), el patrón principal debe ser .

Tipo

ContentSetting<AutoVerifyContentSetting>

camera

Chrome 46 y versiones posteriores

Si permites que los sitios accedan a la cámara. Una de las siguientes opciones: allow: Permitir que los sitios accedan a la cámara, block: No permitir que los sitios accedan a la cámara, ask: Preguntar cuando un sitio quiera acceder a la cámara. El valor predeterminado es ask. La URL principal es la URL del documento que solicitó acceso a la cámara. No se usa la URL secundaria. NOTA: El parámetro de configuración "allow" no es válido si ambos patrones son "'".

Tipo

ContentSetting<CameraContentSetting>

clipboard

Chrome 121 y versiones posteriores

Permite que los sitios accedan al portapapeles a través de las funciones avanzadas de la API de Async Clipboard. Las capacidades "avanzadas" incluyen todo lo que no sea escribir formatos integrados después de un gesto del usuario, es decir, la capacidad de leer, escribir formatos personalizados y escribir sin un gesto del usuario. Una de las siguientes opciones: allow: Permitir que los sitios usen funciones avanzadas del portapapeles, block: No permitir que los sitios usen funciones avanzadas del portapapeles, ask: Preguntar cuando un sitio quiera usar funciones avanzadas del portapapeles. El valor predeterminado es ask. La URL principal es la URL del documento que solicitó acceso al portapapeles. No se usa la URL secundaria.

Tipo

ContentSetting<ClipboardContentSetting>

cookies

Permite que los sitios web establezcan cookies y otros datos locales. Uno de los siguientes: allow: Aceptar cookies, block: Bloquear cookies, session\_only: Aceptar cookies solo para la sesión actual. El valor predeterminado es allow. La URL principal es la que representa el origen de la cookie. La URL secundaria es la URL del marco de nivel superior.

Tipo

ContentSetting<CookiesContentSetting>

fullscreen

Obsoleto. Ya no tiene ningún efecto. Ahora, el permiso de pantalla completa se otorga automáticamente para todos los sitios. El valor siempre es allow.

Tipo

ContentSetting<FullscreenContentSetting>

images

Si se mostrarán imágenes. Una de las siguientes opciones: allow: Mostrar imágenes, block: No mostrar imágenes. El valor predeterminado es allow. La URL principal es la URL del marco de nivel superior. La URL secundaria es la URL de la imagen.

Tipo

ContentSetting<ImagesContentSetting>

javascript

Indica si se debe ejecutar JavaScript. Uno de los siguientes: allow: Ejecuta JavaScript, block: No ejecutes JavaScript. El valor predeterminado es allow. La URL principal es la URL del marco de nivel superior. No se usa la URL secundaria.

Tipo

ContentSetting<JavascriptContentSetting>

location

Indica si se debe permitir la ubicación geográfica. Una de las siguientes opciones: allow: Permitir que los sitios rastreen tu ubicación física, block: No permitir que los sitios rastreen tu ubicación física, ask: Preguntar antes de permitir que los sitios rastreen tu ubicación física. El valor predeterminado es ask. La URL principal es la URL del documento que solicitó datos de ubicación. La URL secundaria es la URL del marco de nivel superior (que puede diferir o no de la URL de solicitud).

Tipo

ContentSetting<LocationContentSetting>

microphone

Chrome 46 y versiones posteriores

Si se permite que los sitios accedan al micrófono. Una de las siguientes opciones: allow: Permitir que los sitios accedan al micrófono, block: No permitir que los sitios accedan al micrófono, ask: Preguntar cuando un sitio quiera acceder al micrófono. El valor predeterminado es ask. La URL principal es la URL del documento que solicitó acceso al micrófono. No se usa la URL secundaria. NOTA: El parámetro de configuración "allow" no es válido si ambos patrones son "'".

Tipo

ContentSetting<MicrophoneContentSetting>

mouselock

Obsoleto. Ya no tiene ningún efecto. Ahora, el permiso de bloqueo del mouse se otorga automáticamente para todos los sitios. El valor siempre es allow.

Tipo

ContentSetting<MouselockContentSetting>

notifications

Si se permite que los sitios muestren notificaciones de escritorio. Una de las siguientes opciones: allow: Permitir que los sitios muestren notificaciones de escritorio, block: No permitir que los sitios muestren notificaciones de escritorio, ask: Preguntar cuando un sitio quiera mostrar notificaciones de escritorio. El valor predeterminado es ask. La URL principal es la URL del documento que desea mostrar la notificación. No se usa la URL secundaria.

Tipo

ContentSetting<NotificationsContentSetting>

plugins

Obsoleto. Dado que se quitó la compatibilidad con Flash en Chrome 88, este permiso ya no tiene ningún efecto. El valor siempre es block. Se ignorarán las llamadas a set() y clear().

Tipo

ContentSetting<PluginsContentSetting>

popups

Permite que los sitios muestren ventanas emergentes. Una de las siguientes opciones: allow: Permitir que los sitios muestren ventanas emergentes, block: No permitir que los sitios muestren ventanas emergentes. El valor predeterminado es block. La URL principal es la URL del marco de nivel superior. No se usa la URL secundaria.

Tipo

ContentSetting<PopupsContentSetting>

unsandboxedPlugins

Obsoleto. Anteriormente, se controlaba si se permitía que los sitios ejecutaran complementos sin el entorno de pruebas. Sin embargo, como se quitó el proceso del agente de Flash en Chrome 88, este permiso ya no tiene ningún efecto. El valor siempre es block. Se ignorarán las llamadas a set() y clear().

Tipo

ContentSetting<PpapiBrokerContentSetting>