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 afectará cada configuración de contenido. Por ejemplo: https://*.youtube.com/* especifica youtube.com y todos sus subdominios. Sintaxis del contenido establecer patrones es lo mismo que para 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 completamente 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 un puerto un número, el patrón solo coincide con los sitios web con ese puerto. Si no se indica ningún número de puerto especificado, 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 a un sitio determinado, la que tenga la este patrón 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)

Tres tipos de comodines 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, puerto. Por ejemplo, el los siguientes patrones se ordenan por precedencia:

  1. https://www.example.com:*/* Especifica el nombre de host y el esquema.
  2. *:/www.example.com:123/* No es tan alto porque, aunque especifica el nombre de host, no especifica el esquema.
  3. https://*.example.com:123/* Es menor 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 la cuadro multifunción. Esta URL se denomina "principal" URL.

Algunos tipos de contenido pueden tener en cuenta URLs adicionales. Por ejemplo, si un sitio puede establecer un contentSettings.cookies se decide en función de la URL de la solicitud HTTP (que es la URL principal en este caso), así como la URL que se muestra en el cuadro multifunción (que se denomina "secundaria" URL).

Si varias reglas tienen patrones primarios y secundarios, la regla con el principal más específico este patrón tiene prioridad. Si hay varias reglas con el mismo patrón principal, un patrón secundario más específico tiene prioridad. Por ejemplo, la siguiente lista de Los pares de patrones primario/secundario se ordenan 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>

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 la que un identificador de recursos identifica un complemento específico. Cuando apliques la configuración de contenido, primero se configuración del complemento específico. Si no se encuentran parámetros de configuración complemento, se verifica la configuración general de contenido para los complementos.

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

Puedes obtener una lista de identificadores de recursos para un tipo de contenido si llamas al contentSettings.ContentSetting.getResourceIdentifiers(). La lista que se devuelve puede cambiar con el conjunto de complementos instalados en la máquina del usuario, pero Chrome intenta mantener estables los identificadores en las actualizaciones de complementos.

Ejemplos

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

Tipos

AutoVerifyContentSetting

Chrome 113 y versiones posteriores

Enum

“allow”

“bloquear”

CameraContentSetting

Chrome 46 y versiones posteriores

Enum

“allow”

“bloquear”

“preguntar”

ClipboardContentSetting

Chrome 121 y versiones posteriores

Enum

“allow”

“bloquear”

“preguntar”

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 el parámetro de configuración (predeterminado: normal)

    • callback

      función opcional

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

      () => void

    • muestra

      Promesa<void>

      Chrome 96 y versiones posteriores

      Las promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para retrocompatibilidad. No puedes usar ambos en la misma llamada a función. El 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

        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 utilizan URLs secundarias.

    • callback

      función opcional

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

      (details: object) => void

      • detalles

        objeto

        • Estableciendo

          T

          Es la configuración de contenido. Consulta la descripción de los objetos ContentSetting individuales para obtener los valores posibles.

    • muestra

      Promise&lt;object&gt;

      Chrome 96 y versiones posteriores

      Las promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para retrocompatibilidad. No puedes usar ambos en la misma llamada a función. El 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

        Una lista de identificadores de recursos para este tipo de contenido, o undefined si este tipo de contenido no usa identificadores de recursos.

    • muestra

      Promesa<ResourceIdentifier[]>

      Chrome 96 y versiones posteriores

      Las promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para retrocompatibilidad. No puedes usar ambos en la misma llamada a función. El 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 es que coincida con todas las URLs. Para obtener detalles sobre el formato de un patrón, consulta Patrones de configuración de contenido.

      • Estableciendo

        cualquiera

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

    • callback

      función opcional

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

      () => void

    • muestra

      Promesa<void>

      Chrome 96 y versiones posteriores

      Las promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para retrocompatibilidad. No puedes usar ambos en la misma llamada a función. El se resuelve con el mismo tipo que se pasa a la devolución de llamada.

CookiesContentSetting

Chrome 44 y versiones posteriores

Enum

“allow”

“bloquear”

&quot;session_only&quot;

FullscreenContentSetting

Chrome 44 y versiones posteriores

Valor

“allow”

ImagesContentSetting

Chrome 44 y versiones posteriores

Enum

“allow”

“bloquear”

JavascriptContentSetting

Chrome 44 y versiones posteriores

Enum

“allow”

“bloquear”

LocationContentSetting

Chrome 44 y versiones posteriores

Enum

“allow”

“bloquear”

“preguntar”

MicrophoneContentSetting

Chrome 46 y versiones posteriores

Enum

“allow”

“bloquear”

“preguntar”

MouselockContentSetting

Chrome 44 y versiones posteriores

Valor

“allow”

MultipleAutomaticDownloadsContentSetting

Chrome 44 y versiones posteriores

Enum

“allow”

“bloquear”

“preguntar”

NotificationsContentSetting

Chrome 44 y versiones posteriores

Enum

“allow”

“bloquear”

“preguntar”

PluginsContentSetting

Chrome 44 y versiones posteriores

Valor

“bloquear”

PopupsContentSetting

Chrome 44 y versiones posteriores

Enum

“allow”

“bloquear”

PpapiBrokerContentSetting

Chrome 44 y versiones posteriores

Valor

“bloquear”

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

    string opcional

    Es una descripción legible del recurso.

  • id

    string

    Es el identificador de recurso para el tipo de contenido determinado.

Scope

Chrome 44 y versiones posteriores

El alcance de ContentSetting. Uno de regular: Es la configuración del perfil normal (que hereda el perfil de incógnito si no se anula en otro lugar). incognito\_session\_only: Es el parámetro de configuración del perfil en modo Incógnito que solo se puede establecer durante una sesión en modo Incógnito y se borra cuando esta finaliza (se anula la configuración normal).

Enum

“normal”

“ Incógnito_session_only”

Propiedades

automaticDownloads

Indica si se permite que los sitios descarguen varios archivos automáticamente. Uno de 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 quiera 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&lt;MultipleAutomaticDownloadsContentSetting&gt;

autoVerify

Chrome 113 y versiones posteriores

Indica si se permite que los sitios usen la API de Private State Tokens. Uno de allow: Permite que los sitios usen la API de Private State Tokens. block: Impide que los sitios usen la API de Private State Tokens. El valor predeterminado es allow. La URL principal es la URL del marco de nivel superior. La URL secundaria no se usa. NOTA: Cuando llamas a set(), el patrón principal debe ser .

Tipo

ContentSetting&lt;AutoVerifyContentSetting&gt;

camera

Chrome 46 y versiones posteriores

Indica si se permite el acceso de los sitios a la cámara. Uno de allow: Permite 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. La URL secundaria no se usa. NOTA: La opció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. “Avanzado” incluyen cualquier cosa además de la escritura de 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. Uno de allow: Permite que los sitios usen las funciones avanzadas del portapapeles. block: No permitir que los sitios usen funciones avanzadas del portapapeles, ask: Preguntar cuando un sitio quiera usar las funciones avanzadas del portapapeles. El valor predeterminado es ask. La URL principal es la URL del documento que solicitó acceso al portapapeles. La URL secundaria no se usa.

Tipo

ContentSetting&lt;ClipboardContentSetting&gt;

cookies

Indica si se deben permitir o no que los sitios web establezcan cookies y otros datos locales. Uno de allow: Aceptar cookies, block: Bloquear cookies, session\_only: Acepta las 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 es siempre allow.

Tipo

ContentSetting&lt;FullscreenContentSetting&gt;

images

Establece si se deben mostrar las imágenes. Uno de allow: Muestra 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&lt;ImagesContentSetting&gt;

javascript

Establece si se debe ejecutar JavaScript. Uno de allow: Ejecutar JavaScript. block: No ejecutas JavaScript. El valor predeterminado es allow. La URL principal es la URL del marco de nivel superior. La URL secundaria no se usa.

Tipo

ContentSetting&lt;JavascriptContentSetting&gt;

location

Indica si se debe permitir la ubicación geográfica. Uno de 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 o no diferir de la URL solicitante).

Tipo

ContentSetting&lt;LocationContentSetting&gt;

microphone

Chrome 46 y versiones posteriores

Indica si se permite que los sitios accedan al micrófono. Uno de allow: Permite 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. La URL secundaria no se usa. NOTA: La opción "allow" no es válido si ambos patrones son ''.

Tipo

ContentSetting&lt;MicrophoneContentSetting&gt;

mouselock

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

Tipo

ContentSetting&lt;MouselockContentSetting&gt;

notifications

Indica si se permite que los sitios muestren notificaciones de escritorio. Uno de 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. La URL secundaria no se usa.

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 es siempre block. Se ignorarán las llamadas a set() y clear().

Tipo

ContentSetting&lt;PluginsContentSetting&gt;

popups

Indica si se permite que los sitios muestren ventanas emergentes. Uno de 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. La URL secundaria no se usa.

Tipo

ContentSetting&lt;PopupsContentSetting&gt;

unsandboxedPlugins

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

Tipo

ContentSetting&lt;PpapiBrokerContentSetting&gt;