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
Manifest
Para usar la API, debes declarar el permiso "contentSettings" en el manifiesto de tu extensión. Por ejemplo:
{
"name": "My extension",
...
"permissions": [
"contentSettings"
],
...
}
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
yftp
, la ruta de acceso debe ser un comodín (/*
). En el caso de las URLsfile
, 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:
https://www.example.com/*
https://*.example.com/*
(coincide con example.com y todos los subdominios)<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:
https://www.example.com:*/*
Especifica el nombre de host y el esquema.*:/www.example.com:123/*
No es tan alto porque, aunque especifica el nombre de host, no especifica el esquema.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:
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> |
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
Enum
CameraContentSetting
Enum
ClipboardContentSetting
Enum
ContentSetting
Propiedades
-
borrar
void
PromesaBorra 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 posterioresLas promesas solo son compatibles con Manifest V3 y versiones posteriores; otras plataformas deben usar devoluciones de llamada.
-
-
get
void
PromesaObtiene 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 posterioresLas promesas solo son compatibles con Manifest V3 y versiones posteriores; otras plataformas deben usar devoluciones de llamada.
-
-
getResourceIdentifiers
void
PromesaLa 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 posterioresLas promesas solo son compatibles con Manifest V3 y versiones posteriores; otras plataformas deben usar devoluciones de llamada.
-
-
set
void
PromesaAplica 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 posterioresLas promesas solo son compatibles con Manifest V3 y versiones posteriores; otras plataformas deben usar devoluciones de llamada.
-
CookiesContentSetting
Enum
"session_only"
FullscreenContentSetting
Valor
ImagesContentSetting
Enum
JavascriptContentSetting
Enum
LocationContentSetting
Enum
MicrophoneContentSetting
Enum
MouselockContentSetting
Valor
MultipleAutomaticDownloadsContentSetting
Enum
NotificationsContentSetting
Enum
PluginsContentSetting
Valor
PopupsContentSetting
Enum
PpapiBrokerContentSetting
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
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.
autoVerify
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
camera
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 "".
clipboard
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.
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.
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
.
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.
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.
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).
microphone
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 "".
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
.
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.
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()
.
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.
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()
.