Descripción
Usa la API de chrome.cookies para consultar y modificar cookies, y recibir notificaciones cuando cambien.
Permisos
cookiesPara usar la API de cookies, declara el permiso "cookies" en tu manifiesto junto con los permisos de host para cualquier host a cuyas cookies desees acceder. Por ejemplo:
{
"name": "My extension",
...
"host_permissions": [
"*://*.google.com/"
],
"permissions": [
"cookies"
],
...
}
Partición
Las cookies particionadas permiten que un sitio marque que ciertas cookies deben estar vinculadas al origen del marco de nivel superior. Esto significa que, por ejemplo, si el sitio A se incorpora mediante un iframe en el sitio B y el sitio C, las versiones incorporadas de una cookie particionada desde A pueden tener valores diferentes en B y C.
De forma predeterminada, todos los métodos de API operan en cookies no particionadas. Se puede usar la propiedad partitionKey para anular este comportamiento.
Para obtener detalles sobre el impacto general de la partición de extensiones, consulta Almacenamiento y cookies.
Ejemplos
Puedes encontrar un ejemplo simple del uso de la API de cookies en el directorio examples/api/cookies. Para ver otros ejemplos y obtener ayuda con la visualización del código fuente, consulta Muestras.
Tipos
Cookie
Representa información sobre una cookie HTTP.
Propiedades
-
dominio
cadena
Indica el dominio de la cookie (p.ej., "www.google.com", "example.com").
-
expirationDate
número opcional
Fecha de vencimiento de la cookie como número de segundos desde la época UNIX. No se proporcionan para las cookies de sesión.
-
hostOnly
boolean
Es verdadero si la cookie es solo de host (es decir, el host de una solicitud debe coincidir exactamente con el dominio de la cookie).
-
httpOnly
boolean
Es verdadero si la cookie está marcada como HttpOnly (es decir, las secuencias de comandos del cliente no pueden acceder a la cookie).
-
name
cadena
El nombre de la galleta.
-
partitionKey
CookiePartitionKey opcional
Chrome 119 y versiones posterioresLa clave de partición para leer o modificar cookies con el atributo Particionada.
-
ruta de acceso
cadena
Es la ruta de la cookie.
-
sameSiteChrome 51 y versiones posteriores
El estado de la cookie en el mismo sitio (es decir, si la cookie se envía con solicitudes entre sitios).
-
seguro
boolean
Es verdadero si la cookie está marcada como segura (es decir, su alcance se limita a los canales seguros, generalmente HTTPS).
-
sesión
boolean
Es verdadero si la cookie es de sesión, en lugar de una cookie persistente con fecha de vencimiento.
-
storeId
cadena
ID de la tienda de cookies que contiene esta cookie, tal como se proporciona en getAllCookieStores().
-
value
cadena
El valor de la cookie.
CookieDetails
Detalles para identificar la cookie
Propiedades
-
name
cadena
El nombre de la cookie a la que se accederá.
-
partitionKey
CookiePartitionKey opcional
Chrome 119 y versiones posterioresLa clave de partición para leer o modificar cookies con el atributo Particionada.
-
storeId
cadena opcional
El ID de la tienda de cookies en la que se busca la cookie De forma predeterminada, se usará el almacén de cookies del contexto de ejecución actual.
-
url
cadena
La URL con la que está asociada la cookie de acceso. Este argumento puede ser una URL completa, en cuyo caso, simplemente se ignorará cualquier dato que siga a la ruta de la URL (p.ej., la cadena de consulta). Si no se especifican los permisos de host para esta URL en el archivo de manifiesto, la llamada a la API fallará.
CookiePartitionKey
Representa la clave de partición de una cookie particionada.
Propiedades
-
topLevelSite
cadena opcional
El sitio de nivel superior en el que está disponible la cookie particionada.
CookieStore
Representa un almacén de cookies en el navegador. Por ejemplo, una ventana de modo incógnito utiliza un almacén de cookies independiente de una ventana que no es de incógnito.
Propiedades
-
id
cadena
Es el identificador único del almacén de cookies.
-
tabIds
número
Los identificadores de todas las pestañas del navegador que comparten esta tienda de cookies.
OnChangedCause
El motivo subyacente del cambio de la cookie. Si se insertó una cookie o se quitó mediante una llamada explícita a "chrome.cookies.remove", "Cause" será "explícita". Si una cookie se quitó automáticamente debido al vencimiento, el campo " pronto" (causa) vencerá. Si se quitó una cookie debido al reemplazo con una fecha de vencimiento que ya venció, “ “causa” se configurará como “expired_overwrite”. Si una cookie se quitó automáticamente debido a la recolección de elementos no utilizados, la “causa” será “expulsada”. Si una cookie se quitó automáticamente debido a una llamada "set" que la reemplazó, "Cause" será "overwrite". Planifica tu respuesta según corresponda.
Enum
"expired_overwrite"
SameSiteStatus
El estado "SameSite" de una cookie (https://tools.ietf.org/html/draft-west-first-party-cookies). "no_restriction" corresponde a una cookie configurada con "SameSite=None", "lax" a "SameSite=Lax" y "strict" a "SameSite=Strict". "sin especificar" corresponde a un conjunto de cookies sin el atributo SameSite.
Enum
"no_restriction"
Métodos
get()
chrome.cookies.get(
details: CookieDetails,
callback?: function,
)
Recupera información sobre una sola cookie. Si existe más de una cookie con el mismo nombre para la URL dada, se mostrará la que tenga la ruta de acceso más larga. Para cookies con la misma ruta de interacciones, se mostrará la cookie con la hora de creación más antigua.
Parámetros
Devuelve
-
Promesa<Cookie|undefined>
Chrome 88 y versiones posterioresLas 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.
getAll()
chrome.cookies.getAll(
details: object,
callback?: function,
)
Recupera todas las cookies de un solo almacén de cookies que coinciden con la información especificada. Se ordenarán las cookies devueltas, con las que tengan la ruta más larga primero. Si varias cookies tienen la misma ruta de interacciones, las que tengan la fecha de creación más temprana aparecerán primero. Este método solo recupera cookies para los dominios para los que la extensión tiene permisos de host.
Parámetros
-
detalles
objeto
Información para filtrar las cookies que se recuperan.
-
dominio
cadena opcional
Restringe las cookies recuperadas a aquellas cookies cuyos dominios coinciden con este dominio o son subdominios de este.
-
name
cadena opcional
Filtra las cookies por nombre.
-
partitionKey
CookiePartitionKey opcional
Chrome 119 y versiones posterioresLa clave de partición para leer o modificar cookies con el atributo Particionada.
-
ruta de acceso
cadena opcional
Restringe las cookies recuperadas a aquellas cuya ruta de acceso coincide exactamente con esta cadena.
-
seguro
booleano opcional
Filtra las cookies por su propiedad Secure.
-
sesión
booleano opcional
Filtra la sesión frente a las cookies persistentes.
-
storeId
cadena opcional
El almacén de cookies del que se deben recuperar las cookies. Si se omite, se usará el almacén de cookies del contexto de ejecución actual.
-
url
cadena opcional
Restringe las cookies recuperadas a aquellas que coincidan con la URL determinada.
-
-
callback
Función opcional
El parámetro
callbackse ve de la siguiente manera:(cookies: Cookie[])=>void
-
cookies
Todas las cookies existentes, sin vencer que coincidan con la información de la cookie especificada.
-
Devuelve
-
Promise<Cookie[]>
Chrome 88 y versiones posterioresLas 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.
getAllCookieStores()
chrome.cookies.getAllCookieStores(
callback?: function,
)
Enumera todos los almacenes de cookies existentes.
Parámetros
-
callback
Función opcional
El parámetro
callbackse ve de la siguiente manera:(cookieStores: CookieStore[])=>void
-
cookieStores
Todos los almacenes de cookies existentes
-
Devuelve
-
Promise<CookieStore[]>
Chrome 88 y versiones posterioresLas 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.
remove()
chrome.cookies.remove(
details: CookieDetails,
callback?: function,
)
Borra una cookie por nombre.
Parámetros
-
detalles
-
callback
Función opcional
El parámetro
callbackse ve de la siguiente manera:(details?: object)=>void
-
detalles
objeto opcional
Contiene detalles sobre la cookie que se quitó. Si la eliminación no puede realizarse por algún motivo, este valor será "nulo" y se establecerá
runtime.lastError.-
name
cadena
El nombre de la cookie que se quitó.
-
partitionKey
CookiePartitionKey opcional
Chrome 119 y versiones posterioresLa clave de partición para leer o modificar cookies con el atributo Particionada.
-
storeId
cadena
El ID de la tienda de cookies de la que se quitó la cookie
-
url
cadena
La URL asociada con la cookie que se quitó.
-
-
Devuelve
-
Promise<object|undefined>
Chrome 88 y versiones posterioresLas 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()
chrome.cookies.set(
details: object,
callback?: function,
)
Establece una cookie con los datos de la cookie especificados; puede reemplazar las cookies equivalentes si existen.
Parámetros
-
detalles
objeto
Detalles sobre la cookie que se establece
-
dominio
cadena opcional
Indica el dominio de la cookie. Si se omite, la cookie se convierte en una cookie de solo host.
-
expirationDate
número opcional
Fecha de vencimiento de la cookie como número de segundos desde la época UNIX. Si se omite, la cookie se convierte en una cookie de sesión.
-
httpOnly
booleano opcional
Si la cookie debe marcarse como HttpOnly. La configuración predeterminada es "false".
-
name
cadena opcional
El nombre de la galleta. Si se omite, estará vacío de forma predeterminada.
-
partitionKey
CookiePartitionKey opcional
Chrome 119 y versiones posterioresLa clave de partición para leer o modificar cookies con el atributo Particionada.
-
ruta de acceso
cadena opcional
Es la ruta de la cookie. El valor predeterminado es la parte de la ruta de acceso del parámetro de URL.
-
sameSite
SameSiteStatus opcional
Chrome 51 y versiones posterioresEstado de la cookie en el mismo sitio El valor predeterminado es “sin especificar”, es decir, si se omite, la cookie se configura sin especificar un atributo de SameSite.
-
seguro
booleano opcional
Indica si la cookie debe marcarse como segura. La configuración predeterminada es "false".
-
storeId
cadena opcional
El ID de la tienda de cookies en la que se configura la cookie De forma predeterminada, la cookie se establece en el almacén de cookies del contexto de ejecución actual.
-
url
cadena
El URI de solicitud que se asociará con la configuración de la cookie. Este valor puede afectar los valores predeterminados del dominio y la ruta de la cookie creada. Si no se especifican los permisos de host para esta URL en el archivo de manifiesto, la llamada a la API fallará.
-
value
cadena opcional
El valor de la cookie. Si se omite, estará vacío de forma predeterminada.
-
-
callback
Función opcional
El parámetro
callbackse ve de la siguiente manera:(cookie?: Cookie)=>void
-
galleta
Cookie opcional
Contiene detalles sobre la cookie que se estableció. Si la configuración falla por algún motivo, este valor será "nulo" y se establecerá
runtime.lastError.
-
Devuelve
-
Promesa<Cookie|undefined>
Chrome 88 y versiones posterioresLas 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.
Eventos
onChanged
chrome.cookies.onChanged.addListener(
callback: function,
)
Se activa cuando se configura o quita una cookie. Como caso especial, ten en cuenta que la actualización de las propiedades de una cookie se implementa como un proceso de dos pasos: la cookie que se actualizará se quita primero por completo y se genera una notificación con la “causa” de “reemplazar”. Luego, se escribe una cookie nueva con los valores actualizados y se genera una segunda notificación con “causa” “explícita”.
Parámetros
-
callback
la función
El parámetro
callbackse ve de la siguiente manera:(changeInfo: object)=>void
-
changeInfo
objeto
-
cause
El motivo subyacente del cambio de la cookie.
-
galleta
Información sobre la cookie que se configuró o quitó.
-
eliminada
boolean
Es verdadero si se quitó una cookie.
-
-