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 del contenido te permite personalizar el comportamiento de Chrome por sitio en lugar de hacerlo de forma global.
Permisos
contentSettingsDebes declarar el permiso "contentSettings" en el manifiesto de tu extensión para usar la API. Por ejemplo:
{ "name": "My extension", ... "permissions": [ "contentSettings" ], ... } Conceptos y uso
Patrones de configuración de contenido
Puedes usar patrones para especificar los sitios web que afecta cada parámetro de 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:
- En el caso de las URLs de
http,httpsyftp, la ruta debe ser un comodín (/*). En el caso de las URLs defile, 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 coincide con los sitios web que tienen ese puerto. Si no se especifica ningún número de puerto, el patrón coincide con todos los puertos.
Precedencia de patrones
Cuando se aplica más de una regla de configuración de contenido a un sitio determinado, prevalece la regla con el patrón más específico.
Por ejemplo, los siguientes patrones se ordenan por prioridad:
https://www.example.com/*https://*.example.com/*(coincide con example.com y todos los subdominios)<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:
https://www.example.com:*/*Especifica el nombre de host y el esquema.*:/www.example.com:123/*No es tan alta, ya que, si bien especifica el nombre de host, no especifica el esquema.https://*.example.com:123/*Es más baja porque, aunque especifica el puerto y el esquema, tiene un comodín en el nombre de host.
Patrones principales y secundarios
La URL que se tiene en cuenta cuando se decide qué parámetro de 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 barra de direcciones. Esta URL se denomina "principal".
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) y la URL que se muestra en el cuadro multifunción (que se denomina URL "secundaria").
Si varias reglas tienen patrones principales y secundarios, la regla con el patrón principal más específico tiene prioridad. 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:
| Prioridad | Patrón principal | Patrón secundario |
|---|---|---|
| 1 | https://www.moose.com/*, | https://www.wombat.com/* |
| 2 | https://www.moose.com/*, | <all_urls> |
| 3 | <all_urls>, | https://www.wombat.com/* |
| 4 | <all_urls>, | <all_urls> |
No se admiten patrones secundarios para el parámetro de configuración de contenido de imágenes.
Identificadores de recursos
Los identificadores de recursos te permiten especificar la configuración del 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 aplican los parámetros de configuración del contenido, primero se verifican los parámetros de configuración del complemento específico. Si no se encuentra ningún parámetro de configuración para el complemento específico, se verifican los parámetros de configuración generales del contenido para 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>, tendrá prioridad sobre una regla sin identificador de recurso 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 llamando al método 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 los identificadores estables en las actualizaciones de complementos.
Ejemplos
Para probar esta API, instala el ejemplo de la API de contentSettings desde el repositorio de chrome-extension-samples.
Tipos
AutoVerifyContentSetting
Enum
"allow"
"block"
CameraContentSetting
Enum
"allow"
"block"
"ask"
ClipboardContentSetting
Enum
"allow"
"block"
"ask"
ContentSetting
Propiedades
- borrar
void
Borra todos los parámetros de configuración de contenido establecidos por esta extensión.
La función
clearse ve de la siguiente manera:(details: object) => {...}
- detalles
objeto
- alcance
Scope opcional
Dónde borrar el parámetro de configuración (el valor predeterminado es regular).
-
- returns
Promise<void>
Chrome 96 y versiones posteriores
-
- get
void
Obtiene el parámetro de configuración de contenido actual para un par de URLs determinado.
La función
getse ve de la siguiente manera:(details: object) => {...}
- detalles
objeto
- Incógnito
booleano opcional
Indica si se deben verificar los parámetros de configuración del contenido para una sesión de incógnito. (el valor predeterminado es falso)
- primaryUrl
string
Es la URL principal para la que se debe recuperar el parámetro de configuración del 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 deben recuperar los parámetros de configuración.
- secondaryUrl
cadena opcional
Es la URL secundaria para la que se debe recuperar el parámetro de configuración del 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.
-
- returns
Promise<object>
Chrome 96 y versiones posteriores
-
- getResourceIdentifiers
void
La función
getResourceIdentifiersse ve de la siguiente manera:() => {...}- returns
Promise<ResourceIdentifier[]>
Chrome 96 y versiones posteriores
-
- set
void
Aplica una nueva regla de configuración de contenido.
La función
setse ve de la siguiente manera:(details: object) => {...}
- 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 del recurso para el tipo de contenido.
- alcance
Scope opcional
Dónde establecer el parámetro de configuración (predeterminado: regular).
- 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 se aplica con esta regla. Consulta la descripción de los objetos ContentSetting individuales para conocer los valores posibles.
-
- returns
Promise<void>
Chrome 96 y versiones posteriores
-
CookiesContentSetting
Enum
"allow"
"block"
"session_only"
FullscreenContentSetting
Valor
"allow"
ImagesContentSetting
Enum
"allow"
"block"
JavascriptContentSetting
Enum
"allow"
"block"
LocationContentSetting
Enum
"allow"
"block"
"ask"
MicrophoneContentSetting
Enum
"allow"
"block"
"ask"
MouselockContentSetting
Valor
"allow"
MultipleAutomaticDownloadsContentSetting
Enum
"allow"
"block"
"ask"
NotificationsContentSetting
Enum
"allow"
"block"
"ask"
PluginsContentSetting
Valor
"block"
PopupsContentSetting
Enum
"allow"
"block"
PpapiBrokerContentSetting
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 del recurso.
- id
string
Es el identificador del recurso para el tipo de contenido determinado.
Scope
Es el alcance de ContentSetting. Uno de los siguientes: regular: Es el parámetro de 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 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"
"incognito_session_only"
Propiedades
automaticDownloads
Indica si se 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 quiera descargar archivos automáticamente después del primer archivo. El valor predeterminado es ask. La URL principal es la del marco de nivel superior. No se usa la URL secundaria.
autoVerify
Indica si se permite que los sitios usen la API de Private State Tokens. Una de las siguientes opciones: allow: Permite que los sitios usen la API de Private State Tokens. block: Bloquea el uso de la API de Private State Tokens en los sitios. El valor predeterminado es allow. Cuando se llama a set(), el patrón de URL principal debe ser <all_urls>. No se usa la URL secundaria.
camera
Indica si se permite que los sitios accedan a la cámara. Una de las siguientes opciones: allow: Permite que los sitios accedan a la cámara. block: No permite que los sitios accedan a la cámara. ask: Pregunta 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 "<all_urls>".
clipboard
Indica si se permite que los sitios accedan al portapapeles a través de las capacidades 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, la capacidad de escribir formatos personalizados y la capacidad de escribir sin un gesto del usuario. Uno de los siguientes: allow: Permite que los sitios usen funciones avanzadas del portapapeles. block: No permite que los sitios usen funciones avanzadas del portapapeles. ask: Pregunta 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.
cookies
Indica si se permiten las cookies y otros datos locales que establecen los sitios web. 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.
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.
images
Indica si se deben mostrar 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 del marco de nivel superior. La URL secundaria es la URL de la imagen.
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 del marco de nivel superior. No se usa la URL secundaria.
location
Indica si se permite la ubicación geográfica. Una de las siguientes opciones: allow: Permite que los sitios rastreen tu ubicación física. block: No permite que los sitios rastreen tu ubicación física. ask: Pregunta 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).
microphone
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 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 "<all_urls>".
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.
notifications
Indica si se permite que los sitios muestren notificaciones de escritorio. Una de las siguientes opciones: allow: Permite que los sitios muestren notificaciones de escritorio, block: No permite que los sitios muestren notificaciones de escritorio, ask: Pregunta 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.
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().
popups
Indica si se permite que los sitios muestren ventanas emergentes. Uno de los siguientes: 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 del marco de nivel superior. No se usa la URL secundaria.
unsandboxedPlugins
Obsoleto. Anteriormente, controlaba si se permitía que los sitios ejecutaran complementos sin aislamiento, pero, con la eliminación del proceso de intermediario 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().