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 para cada sitio en lugar de hacerlo de manera 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.

Precedencia del patrón

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 todas las URLs)

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 tan alto porque, si bien 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, la configuración de contentSettings.notifications se basa en la URL que se muestra en el cuadro multifunción. Esta URL se denomina "principal".

Algunos tipos de contenido pueden tener en cuenta URLs adicionales. Por ejemplo, se decide si un sitio puede configurar un contentSettings.cookies 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 principales y secundarios, prevalece la regla con el patrón principal más específico. Si hay varias reglas que tienen el mismo patrón principal, prevalece la que tenga 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 la configuración del contenido de las 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

CameraContentSetting

Chrome 46 y versiones posteriores

Enum

"ask"

ClipboardContentSetting

Chrome 121 y versiones posteriores

Enum

ContentSetting

Propiedades

  • borrar

    void

    Promesa

    Borra todas las reglas de configuración de contenido establecidas por 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 de URL determinado.

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

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

    • detalles

      objeto

      • incógnito

        booleano opcional

        Establece si se debe verificar la configuración de contenido de una sesión en modo Incógnito. (el valor predeterminado es falso)

      • primaryUrl

        string

        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

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

      • secondaryUrl

        string 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

      Promesa<objeto>

      Chrome 96 y versiones posteriores

      Las 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.

  • 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

        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

        El identificador de recurso para el tipo de contenido.

      • alcance

        Alcance opcional

        Dónde establecer la configuración (predeterminado: normal).

      • secondaryPattern

        string opcional

        El patrón de la URL secundaria. La configuración predeterminada coincide con todas las URL. 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

FullscreenContentSetting

Chrome 44 y versiones posteriores

Valor

ImagesContentSetting

Chrome 44 y versiones posteriores

Enum

JavascriptContentSetting

Chrome 44 y versiones posteriores

Enum

LocationContentSetting

Chrome 44 y versiones posteriores

Enum

"ask"

MicrophoneContentSetting

Chrome 46 y versiones posteriores

Enum

"ask"

MouselockContentSetting

Chrome 44 y versiones posteriores

Valor

MultipleAutomaticDownloadsContentSetting

Chrome 44 y versiones posteriores

Enum

"ask"

NotificationsContentSetting

Chrome 44 y versiones posteriores

Enum

"ask"

PluginsContentSetting

Chrome 44 y versiones posteriores

Valor

PopupsContentSetting

Chrome 44 y versiones posteriores

Enum

PpapiBrokerContentSetting

Chrome 44 y versiones posteriores

Valor

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

    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 alcance de ContentSetting. Una de las siguientes opciones: regular: configuración del perfil normal (que hereda el perfil de incógnito si no se anula en otro lugar) incognito\_session\_only: parámetro de configuración del perfil de incógnito que solo se puede establecer durante una sesión en modo incógnito y que se borra cuando finaliza la sesión en ese modo (se anula la configuración normal).

Enum

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 desea descargar archivos automáticamente después del primer archivo. El valor predeterminado es ask. La URL principal es la URL del marco de nivel superior. La URL secundaria no se usa.

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&lt;CameraContentSetting&gt;

clipboard

Chrome 121 y versiones posteriores

Indica si se permite que los sitios accedan al portapapeles a través de las funciones avanzadas de la API de Async Clipboard. Las funciones "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 allow: Permite que los sitios usen las funciones avanzadas del portapapeles. block: No permite que los sitios usen funciones avanzadas del portapapeles. ask: Pregunta cuando un sitio desea usar las 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. Una de las siguientes opciones: allow: Aceptar cookies; block: Bloquear cookies; session\_only: Aceptar cookies solo de 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&lt;CookiesContentSetting&gt;

fullscreen

Obsoleto. Ya no tiene ningún efecto. El permiso de pantalla completa ahora 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

Establece 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&lt;JavascriptContentSetting&gt;

location

Indica si se debe permitir la ubicación geográfica. Una de las siguientes opciones: allow: Permitir que los sitios hagan un seguimiento de tu ubicación física. block: No permitir que los sitios hagan un seguimiento de tu ubicación física. ask: Preguntar antes de permitir que los sitios hagan un seguimiento de 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&lt;LocationContentSetting&gt;

microphone

Chrome 46 y versiones posteriores

Indica 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 desea 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 &quot;allow&quot; no es válido si ambos patrones son &quot;&#39;&quot;.

Tipo

ContentSetting&lt;MicrophoneContentSetting&gt;

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 es siempre allow.

Tipo

ContentSetting&lt;MouselockContentSetting&gt;

notifications

Especifica 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&lt;NotificationsContentSetting&gt;

plugins

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

Tipo

ContentSetting<PluginsContentSetting>

popups

Indica si se permite que los sitios muestren ventanas emergentes. Una de allow: Permitir que los sitios muestren ventanas emergentes; block: No permite 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&lt;PopupsContentSetting&gt;

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&lt;PpapiBrokerContentSetting&gt;