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 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 a los 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:
- Para las URLs
http,httpsyftp, la ruta de acceso debe ser un comodín (/*). Para las URLsfile, 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 patrón
Cuando se aplica más de una regla de configuración de contenido para un sitio determinado, tiene prioridad la regla con el patrón más específico.
Por ejemplo, los siguientes patrones se ordenan por precedencia:
https://www.example.com/*https://*.example.com/*(coincide con example.com y todos los subdominios)<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 y puerto. Por ejemplo, los siguientes patrones se ordenan por precedencia:
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 primarios y secundarios
La URL que se tiene en cuenta para decidir qué parámetro de configuración de contenido se aplicará depende del tipo de contenido.
Por ejemplo, para contentSettings.notifications, la configuración 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 se permite que un sitio establezca 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 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, la regla con el patrón secundario más específico tiene prioridad. Por ejemplo, la siguiente lista de pares de patrones principales y secundarios se ordena por precedencia:
| 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 parámetros de 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 recurso 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 ningún parámetro de configuración para el complemento específico, se verifica la configuración de contenido general 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.
Puedes obtener una lista de identificadores de recursos para un tipo de contenido llamando 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 las actualizaciones de los complementos.
Ejemplos
Para probar esta API, instala el ejemplo de la API de contentSettings desde el repositorio chrome-extension-samples.
Tipos
AutoVerifyContentSetting
Enum
"allow"
"block"
CameraContentSetting
Enum
"allow"
"block"
"ask"
ClipboardContentSetting
Enum
"allow"
"block"
"ask"
ContentSetting
Propiedades
-
borrar
void
Borra todas las reglas de configuración de contenido que estableció esta extensión.
La función
clearse ve de la siguiente manera:(details: object) => {...}
-
detalles
objeto
-
alcance
Alcance opcional
Dónde borrar el parámetro de configuración (predeterminado: regular).
-
-
muestra
Promise<void>
Chrome 96 y versiones posteriores browser.* desde Chrome 148
-
-
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
-
incognito
booleano opcional
Indica si se debe verificar la configuración de contenido de una sesión en modo Incógnito. (falso de forma predeterminada)
-
primaryUrl
string
Es la URL principal para la que se debe recuperar el parámetro de 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
string opcional
Es la URL secundaria para la que se debe recuperar el parámetro de 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.
-
-
muestra
Promise<object>
Chrome 96 y versiones posteriores browser.* desde Chrome 148
-
-
getResourceIdentifiers
void
La función
getResourceIdentifiersse ve de la siguiente manera:() => {...}-
muestra
Promise<ResourceIdentifier[]>
Chrome 96 y versiones posteriores browser.* desde Chrome 148
-
-
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 de recurso para el tipo de contenido.
-
alcance
Alcance opcional
Dónde establecer el parámetro de configuración (predeterminado: regular).
-
secondaryPattern
string 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.
-
-
muestra
Promise<void>
Chrome 96 y versiones posteriores browser.* desde Chrome 148
-
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
string opcional
Es una descripción legible por humanos del recurso.
-
id
string
Es el identificador de recurso para el tipo de contenido determinado.
Scope
Es el alcance de ContentSetting. Uno de los siguientes:
regular: parámetro de configuración para el perfil normal (que hereda el perfil de incógnito si no se anula en otro lugar)
incognito\_session\_only: parámetro de configuración para el perfil de incógnito que solo se puede establecer durante una sesión en modo Incógnito y se borra cuando finaliza (anula los parámetros de configuración normales)
Enum
"regular"
"incognito_session_only"
SoundContentSetting
Enum
"allow"
"block"
Propiedades
automaticDownloads
Indica si se permite que los sitios descarguen varios archivos automáticamente. Uno de los siguientes valores:
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. No se usa la URL secundaria.
autoVerify
Indica si se permite que los sitios usen la API de Private State Tokens. 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.
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. Uno de los siguientes valores:
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 "<all_urls>".
clipboard
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, la capacidad de escribir formatos personalizados y la capacidad de escribir sin un gesto del usuario. Uno de los siguientes valores:
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.
cookies
Indica si se 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.
fullscreen
Obsoleto. Ya no tiene ningún efecto. Ahora, el permiso de pantalla completa se otorga automáticamente a todos los sitios. El valor siempre es allow.
images
Indica si se deben mostrar imágenes. Uno de los siguientes valores:
allow: Muestra imágenes.
block: No muestra 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.
javascript
Indica si se debe ejecutar JavaScript. Uno de los siguientes valores:
allow: Ejecutar JavaScript
block: No ejecutar JavaScript
El valor predeterminado es allow.
La URL principal es la URL del marco de nivel superior. No se usa la URL secundaria.
location
Indica si se debe permitir la ubicación geográfica. Uno de los siguientes valores:
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ó los datos de ubicación. La URL secundaria es la URL del marco de nivel superior (que puede diferir o no de la URL solicitante).
microphone
Indica si se permite 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ó 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 a todos los sitios. El valor siempre es allow.
notifications
Indica si se permite que los sitios muestren notificaciones de escritorio. Uno de los siguientes valores:
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 quiere 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 valores:
allow: Permite 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.
unsandboxedPlugins
Obsoleto. Anteriormente, controlaba si se permitía que los sitios ejecutaran complementos sin zona de pruebas. Sin embargo, con la eliminación del proceso de 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().