chrome.contentSettings

Descripción

Usa la API de chrome.contentSettings para cambiar parámetros de configuración que controlen 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 y no 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 (/*). En el caso de las URLs file, la ruta 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 coincidirá con los sitios web que tengan ese puerto. Si no se especifica un número de puerto, el patrón coincidirá con todos los puertos.

Prioridad del patrón

Cuando se aplica más de una regla de configuración de contenido a un sitio determinado, prevalece la que tenga el patrón más específico.

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> (que coincida 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, 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 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 toma en cuenta para decidir la configuración de contenido que se aplica 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 URL "principal".

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

Si varias reglas tienen patrones primarios y secundarios, prevalecerá la que tenga el patrón principal más específico. Si varias reglas tienen el mismo patrón principal, prevalecerá la que tenga el patrón secundario más específico. Por ejemplo, la siguiente lista de pares de patrones primarios y secundarios se ordena 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 el que un identificador de recursos identifica un complemento específico. Cuando apliques la configuración de contenido, primero se verificará la configuración del complemento específico. Si no se encontró ninguna configuración para el complemento específico, se verificará la configuración general de contenido de 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 ni 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 para 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 estables los identificadores en todas las actualizaciones de complementos.

Ejemplos

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

Tipos

AutoVerifyContentSetting

Chrome 113 y versiones posteriores

Enum

CameraContentSetting

Chrome 46 y versiones posteriores

Enum

ClipboardContentSetting

Chrome 121 y versiones posteriores

Enum

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

      • permiso

        Alcance opcional

        Dónde borrar la configuración (configuración predeterminada: regular)

    • callback

      Función opcional

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

      ()=>void

    • resultados

      Promise<void>

      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.

  • 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

        Si se debe verificar la configuración de contenido para una sesión de incógnito. (valor predeterminado falso)

      • primaryUrl

        cadena

        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

        cadena opcional

        La URL secundaria para la que se debe recuperar la configuración de contenido. La configuración predeterminada 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 la configuración de contenido. Consulta la descripción de los objetos individuales de ContentSetting para conocer los valores posibles.

    • resultados

      Promise<object>

      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

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

    • resultados

      Promise<ResourceIdentifier[]>

      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.

  • 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

        cadena

        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 recurso para el tipo de contenido.

      • permiso

        Alcance opcional

        Dónde establecer la configuración (configuración predeterminada: regular)

      • secondaryPattern

        cadena 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 la configuración que aplica esta regla. Consulta la descripción de los objetos individuales de ContentSetting para conocer los valores posibles.

    • callback

      Función opcional

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

      ()=>void

    • resultados

      Promise<void>

      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.

CookiesContentSetting

Chrome 44 y versiones posteriores

Enum

"session_only"

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

MicrophoneContentSetting

Chrome 46 y versiones posteriores

Enum

MouselockContentSetting

Chrome 44 y versiones posteriores

Valor

MultipleAutomaticDownloadsContentSetting

Chrome 44 y versiones posteriores

Enum

NotificationsContentSetting

Chrome 44 y versiones posteriores

Enum

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

    Es una descripción legible del recurso.

  • id

    cadena

    El identificador de recursos para el tipo de contenido determinado.

Scope

Chrome 44 y versiones posteriores

El alcance de la configuración de ContentSetting. Uno de regular: configuración del perfil normal (que el perfil de incógnito hereda 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 de incógnito y se borra cuando finaliza la sesión de incógnito (anula la configuración normal).

Enum

"regular"

Propiedades

automaticDownloads

Si se debe permitir que los sitios descarguen varios archivos automáticamente. Uno de los siguientes: allow: Permitir que los sitios descarguen varios archivos de forma automática. 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. No se usa la URL secundaria.

Tipo

ContentSetting<MultipleAutomaticDownloadsContentSetting>

autoVerify

Chrome 113 y versiones posteriores

Indica si se debe permitir que los sitios usen la API de Private State Tokens. Uno de los siguientes 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. No se usa la URL secundaria. NOTA: Cuando llamas a set(), el patrón principal debe ser

Tipo

ContentSetting<AutoVerifyContentSetting>

camera

Chrome 46 y versiones posteriores

Si se debe permitir que los sitios accedan a la cámara. Uno de los siguientes 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ó el acceso a la cámara. No se usa la URL secundaria. NOTA: La configuración "allow" no es válida si ambos patrones son "".

Tipo

ContentSetting<CameraContentSetting>

clipboard

Chrome 121 y versiones posteriores

Indica si se debe permitir que los sitios accedan al portapapeles a través de las capacidades avanzadas de la API de Async Clipboard. Las capacidades “avanzadas” incluyen cualquier otra cosa además de escribir formatos integrados después de un gesto del usuario; es decir, la capacidad de leer, la capacidad de escribir formatos personalizados y la capacidad de escribir sin un gesto del usuario. Uno de los siguientes valores: allow: Permite que los sitios usen las funciones avanzadas del portapapeles. block: No permite que los sitios utilicen funciones avanzadas del portapapeles. ask: Pregunta 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ó el acceso al portapapeles. No se usa la URL secundaria.

Tipo

ContentSetting<ClipboardContentSetting>

cookies

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

Tipo

ContentSetting<FullscreenContentSetting>

images

Indica si se deben mostrar las imágenes. Uno de los siguientes: 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 ejecuta 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

Permitir la ubicación geográfica. Uno de los siguientes: allow: Permitir que los sitios hagan un seguimiento de 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 hagan un seguimiento de tu ubicación física. El valor predeterminado es ask. La URL principal es la URL del documento que solicitó los datos de ubicación. La URL secundaria es la URL del marco de nivel superior (que puede diferir de la URL que realiza la solicitud o no).

Tipo

ContentSetting<LocationContentSetting>

microphone

Chrome 46 y versiones posteriores

Si se debe permitir que los sitios accedan al micrófono. Uno de los siguientes: 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ó el acceso al micrófono. No se usa la URL secundaria. NOTA: La configuración "allow" no es válida si ambos patrones son "".

Tipo

ContentSetting<MicrophoneContentSetting>

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

notifications

Si se debe permitir 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 tendrá ningún efecto. El valor es siempre block. Se ignorarán las llamadas a set() y clear().

Tipo

ContentSetting<PluginsContentSetting>

popups

Si se debe permitir que los sitios muestren ventanas emergentes. Uno de los siguientes valores: 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 fuera de la zona de pruebas. Sin embargo, como se quitó el proceso del agente de Flash en Chrome 88, este permiso ya no tenía ningún efecto. El valor es siempre block. Se ignorarán las llamadas a set() y clear().

Tipo

ContentSetting<PpapiBrokerContentSetting>