browser.cookies

Descripción

Usa la API de chrome.cookies para consultar y modificar las cookies, y para recibir notificaciones cuando cambien.

Permisos

cookies

Para usar la API de cookies, declara el permiso "cookies" en tu manifiesto junto con los permisos de host para los hosts cuyas cookies quieras 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 tener una clave en función del origen del marco de nivel superior. Esto significa que, por ejemplo, si el sitio A se incorpora con un iframe en el sitio B y el sitio C, las versiones incorporadas de una cookie particionada de A pueden tener valores diferentes en B y C.

De forma predeterminada, todos los métodos de la API operan en cookies no particionadas. La propiedad partitionKey se puede usar para anular este comportamiento.

Para obtener detalles sobre el impacto general de la partición en las extensiones, consulta Almacenamiento y cookies.

Ejemplos

Puedes encontrar un ejemplo sencillo de uso de la API de cookies en el directorio examples/api/cookies. Para ver otros ejemplos y obtener ayuda para ver el código fuente, consulta Muestras.

Tipos

Representa información sobre una cookie HTTP.

Propiedades

  • dominio

    string

    Es el dominio de la cookie (p.ej., "www.google.com", "example.com").

  • expirationDate

    number opcional

    La fecha de vencimiento de la cookie como la cantidad de segundos transcurridos desde el tiempo Unix. No se proporciona para las cookies de sesión.

  • hostOnly

    booleano

    Es verdadero si la cookie es de solo host (es decir, el host de una solicitud debe coincidir exactamente con el dominio de la cookie).

  • httpOnly

    booleano

    Es verdadero si la cookie está marcada como HttpOnly (es decir, la cookie es inaccesible para las secuencias de comandos del cliente).

  • nombre

    string

    Es el nombre de la cookie.

  • partitionKey

    CookiePartitionKey opcional

    Chrome 119 y versiones posteriores browser.* desde Chrome 148

    Es la clave de partición para leer o modificar cookies con el atributo Partitioned.

  • ruta de acceso

    string

    Es la ruta de la cookie.

  • sameSite

    SameSiteStatus

    Chrome 51 y versiones posteriores browser.* desde Chrome 148

    El estado de SameSite de la cookie (es decir, si la cookie se envía con solicitudes entre sitios)

  • seguro

    booleano

    Es verdadero si la cookie está marcada como segura (es decir, su alcance se limita a canales seguros, por lo general, HTTPS).

  • sesión

    booleano

    Es verdadero si la cookie es de sesión, a diferencia de una cookie persistente con una fecha de vencimiento.

  • storeId

    string

    Es el ID del almacén de cookies que contiene esta cookie, como se proporciona en getAllCookieStores().

  • valor

    string

    Es el valor de la cookie.

CookieDetails

Chrome 88 y versiones posteriores browser.* desde Chrome 148

Son los detalles para identificar la cookie.

Propiedades

  • nombre

    string

    Es el nombre de la cookie a la que se accederá.

  • partitionKey

    CookiePartitionKey opcional

    Chrome 119 y versiones posteriores browser.* desde Chrome 148

    Es la clave de partición para leer o modificar cookies con el atributo Partitioned.

  • storeId

    string opcional

    Es el ID del almacén de cookies en el que se buscará la cookie. De forma predeterminada, se usará el almacén de cookies del contexto de ejecución actual.

  • url

    string

    Es la URL con la que se asocia la cookie a la que se accederá. Este argumento puede ser una URL completa, en cuyo caso se ignoran todos los datos que siguen a la ruta de 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

Chrome 119 y versiones posteriores browser.* desde Chrome 148

Representa la clave de partición de una cookie particionada.

Propiedades

  • hasCrossSiteAncestor

    booleano opcional

    Chrome 130 y versiones posteriores browser.* desde Chrome 148

    Indica si la cookie se estableció en un contexto de sitio cruzado. Esto evita que un sitio de nivel superior incorporado en un contexto entre sitios acceda a las cookies establecidas por el sitio de nivel superior en un contexto del mismo sitio.

  • topLevelSite

    string opcional

    Es 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 incógnito usa un almacén de cookies independiente de una ventana que no está en modo Incógnito.

Propiedades

  • id

    string

    Es el identificador único del almacén de cookies.

  • tabIds

    number[]

    Son los identificadores de todas las pestañas del navegador que comparten este almacén de cookies.

FrameDetails

Chrome 132 y versiones posteriores browser.* desde Chrome 148

Son los detalles para identificar el marco.

Propiedades

  • documentId

    string opcional

    Es el identificador único del documento. Si se proporcionan frameId o tabId, se validarán para que coincidan con el documento que se encontró con el ID de documento proporcionado.

  • frameId

    number opcional

    Es el identificador único del marco dentro de la pestaña.

  • tabId

    number opcional

    Es el identificador único de la pestaña que contiene el marco.

OnChangedCause

Chrome 44 y versiones posteriores browser.* desde Chrome 148

Es el motivo subyacente del cambio de la cookie. Si se insertó o quitó una cookie a través de una llamada explícita a "chrome.cookies.remove", "cause" será "explicit". Si una cookie se quitó automáticamente debido a su vencimiento, el valor de "cause" será "expired". Si se quitó una cookie porque se reemplazó por una fecha de vencimiento ya vencida, el valor de "cause" se establecerá en "expired_overwrite". Si una cookie se quitó automáticamente debido a la recolección de elementos no utilizados, el valor de "cause" será "evicted". 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

"evicted"

"expired"

"explicit"

"expired_overwrite"

"overwrite"

SameSiteStatus

Chrome 51 y versiones posteriores browser.* desde Chrome 148

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'. "unspecified" corresponde a una cookie establecida sin el atributo SameSite.

Enum

"no_restriction"

"lax"

"strict"

"unspecified"

Métodos

get()

browser.cookies.get(
  details: CookieDetails,
): Promise<Cookie | undefined>

Recupera información sobre una sola cookie. Si existe más de una cookie con el mismo nombre para la URL proporcionada, se devolverá la que tenga la ruta más larga. En el caso de las cookies con la misma ruta de interacciones, se devolverá la cookie con la hora de creación más antigua.

Parámetros

Muestra

  • Promise<Cookie | undefined>

    Chrome 88 y versiones posteriores browser.* desde Chrome 148

getAll()

browser.cookies.getAll(
  details: object,
): Promise<Cookie[]>

Recupera todas las cookies de un solo almacén de cookies que coincide con la información proporcionada. Las cookies devueltas se ordenarán, y las que tengan la ruta más larga aparecerán primero. Si varias cookies tienen la misma longitud de ruta, las que tengan la hora de creación más antigua serán las primeras. Este método solo recupera cookies de 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

      string opcional

      Restringe las cookies recuperadas a aquellas cuyos dominios coincidan con este o sean subdominios de este.

    • nombre

      string opcional

      Filtra las cookies por nombre.

    • partitionKey

      CookiePartitionKey opcional

      Chrome 119 y versiones posteriores browser.* desde Chrome 148

      Es la clave de partición para leer o modificar cookies con el atributo Partitioned.

    • ruta de acceso

      string opcional

      Restringe las cookies recuperadas a aquellas cuya ruta de acceso coincida exactamente con esta cadena.

    • seguro

      booleano opcional

      Filtra las cookies por su propiedad Secure.

    • sesión

      booleano opcional

      Filtra las cookies de sesión y las persistentes.

    • storeId

      string opcional

      Es el almacén de cookies del que se recuperarán las cookies. Si se omite, se usará el almacén de cookies del contexto de ejecución actual.

    • url

      string opcional

      Restringe las cookies recuperadas a aquellas que coincidan con la URL proporcionada.

Muestra

  • Promise<Cookie[]>

    Chrome 88 y versiones posteriores browser.* desde Chrome 148

getAllCookieStores()

browser.cookies.getAllCookieStores(): Promise<CookieStore[]>

Enumera todos los almacenes de cookies existentes.

Muestra

  • Promise<CookieStore[]>

    Chrome 88 y versiones posteriores browser.* desde Chrome 148

getPartitionKey()

Chrome 132 y versiones posteriores browser.* desde Chrome 148 
browser.cookies.getPartitionKey(
  details: FrameDetails,
): Promise<object>

Es la clave de partición del marco indicado.

Parámetros

Muestra

  • Promise<object>

remove()

browser.cookies.remove(
  details: CookieDetails,
): Promise<object | undefined>

Borra una cookie por nombre.

Parámetros

Muestra

  • Promise<object | undefined>

    Chrome 88 y versiones posteriores browser.* desde Chrome 148

set()

browser.cookies.set(
  details: object,
): Promise<Cookie | undefined>

Establece una cookie con los datos de cookie proporcionados; puede reemplazar las cookies equivalentes si existen.

Parámetros

  • detalles

    objeto

    Son los detalles sobre la cookie que se está configurando.

    • dominio

      string opcional

      Es el dominio de la cookie. Si se omite, la cookie se convierte en una cookie de solo host.

    • expirationDate

      number opcional

      La fecha de vencimiento de la cookie como la cantidad de segundos transcurridos desde el tiempo Unix. Si se omite, la cookie se convierte en una cookie de sesión.

    • httpOnly

      booleano opcional

      Indica si la cookie se debe marcar como HttpOnly. La configuración predeterminada es "false".

    • nombre

      string opcional

      Es el nombre de la cookie. Si se omite, queda vacío de forma predeterminada.

    • partitionKey

      CookiePartitionKey opcional

      Chrome 119 y versiones posteriores browser.* desde Chrome 148

      Es la clave de partición para leer o modificar cookies con el atributo Partitioned.

    • ruta de acceso

      string opcional

      Es la ruta de la cookie. Se establece de forma predeterminada en la parte de la ruta de acceso del parámetro de URL.

    • sameSite

      SameSiteStatus opcional

      Chrome 51 y versiones posteriores browser.* desde Chrome 148

      Es el estado de la cookie para seguimiento dentro de un sitio. El valor predeterminado es "unspecified", es decir, si se omite, la cookie se establece sin especificar un atributo SameSite.

    • seguro

      booleano opcional

      Indica si la cookie se debe marcar como segura. La configuración predeterminada es "false".

    • storeId

      string opcional

      Es el ID del almacén de cookies en el que se establecerá la cookie. De forma predeterminada, la cookie se establece en el almacén de cookies del contexto de ejecución actual.

    • url

      string

      Es el URI de solicitud que se asociará con la configuración de la cookie. Este valor puede afectar los valores predeterminados de dominio y ruta de acceso 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á.

    • valor

      string opcional

      Es el valor de la cookie. Si se omite, queda vacío de forma predeterminada.

Muestra

  • Promise<Cookie | undefined>

    Chrome 88 y versiones posteriores browser.* desde Chrome 148

Eventos

onChanged

browser.cookies.onChanged.addListener(
  callback: function,
)

Se activa cuando se establece o se 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: primero, se quita por completo la cookie que se actualizará, lo que genera una notificación con la "causa" de "reemplazar" . Luego, se escribe una cookie nueva con los valores actualizados, lo que genera una segunda notificación con "cause" "explicit".

Parámetros

  • callback

    función

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

    (changeInfo: object) => void

    • changeInfo

      objeto

      • Es el motivo subyacente del cambio de la cookie.

      • galleta

        Cookie

        Información sobre la cookie que se estableció o quitó.

      • quitado

        booleano

        Es verdadero si se quitó una cookie.