chrome.cookies

Descripción

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

Permisos

cookies

Manifiesto

Para usar la API de cookies, debes declarar el permiso "cookies" en tu manifiesto, junto con los permisos de host para los hosts a cuyas cookies deseas 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 la clave del origen del marco de nivel superior. Esto significa que, si el sitio A se incorpora con un iframe en el sitio B y en el sitio C, una cookie particionada puede tener un valor diferente en cada uno.

chrome.cookies no admite la partición, lo que significa que todos los métodos leen y escriben cookies de todas las particiones. El método cookies.set() almacena las cookies en la partición predeterminada.

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

Ejemplos

Puedes encontrar un ejemplo sencillo del 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 Ejemplos.

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

    número opcional

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

  • hostOnly

    booleano

    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

    booleano

    Es verdadero si la cookie está marcada como HttpOnly (es decir, las secuencias de comandos del cliente no pueden acceder a ella).

  • nombre

    string

    Es el nombre de la cookie.

  • partitionKey

    CookiePartitionKey opcional

    Chrome 119 y versiones posteriores

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

  • ruta de acceso

    string

    Es la ruta de la cookie.

  • sameSite

    SameSiteStatus

    Chrome 51 y versiones posteriores

    El estado del mismo sitio de la cookie (es decir, si 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

    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

Detalles para identificar la cookie

Propiedades

  • nombre

    string

    Es el nombre de la cookie a la que se accede.

  • partitionKey

    CookiePartitionKey opcional

    Chrome 119 y versiones posteriores

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

  • storeId

    cadena opcional

    El ID del almacén de cookies en el que se debe 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 está asociada la cookie a la que se accede. Este argumento puede ser una URL completa, en cuyo caso se ignoran todos los datos que siguen 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, fallará la llamada a la API.

CookiePartitionKey

Chrome 119 y versiones posteriores

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

Propiedades

  • hasCrossSiteAncestor

    booleano opcional

    Chrome 130 y versiones posteriores

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

  • topLevelSite

    cadena 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 del modo Incógnito usa un almacén de cookies independiente de una ventana que no es de incógnito.

Propiedades

  • id

    string

    Es el identificador único de la tienda de cookies.

  • tabIds

    number[]

    Identificadores de todas las pestañas del navegador que comparten esta tienda de cookies.

FrameDetails

Pendiente

Detalles para identificar el marco

Propiedades

  • documentId

    cadena 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

    número opcional

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

  • tabId

    número opcional

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

OnChangedCause

Chrome 44 y versiones posteriores

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 se quitó automáticamente una cookie debido al vencimiento, "cause" será "expired". Si se quitó una cookie porque se reemplazó por una con una fecha de vencimiento vencida, "cause" se establecerá en "expired_overwrite". Si se quitó una cookie automáticamente debido a la recolección de elementos no utilizados, se "expulsará" la "causa". 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

El estado "SameSite" de una cookie (https://tools.ietf.org/html/draft-west-first-party-cookies). "no_restriction" corresponde a una cookie establecida 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()

Promesa 
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 determinada, se mostrará la que tenga la ruta más larga. En el caso de las cookies con la misma longitud de ruta de acceso, se mostrará la cookie con la hora de creación más antigua.

Parámetros

  • detalles

    CookieDetails

  • callback

    función opcional

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

    (cookie?: Cookie) => void

    • galleta

      Cookie opcional

      Contiene detalles sobre la cookie. Este parámetro es nulo si no se encontró esa cookie.

Muestra

  • Promise<Cookie | undefined>

    Chrome 88 y versiones posteriores

    Las promesas solo se admiten para Manifest V3 y versiones posteriores. Otras plataformas deben usar devoluciones de llamada.

getAll()

Promesa 
chrome.cookies.getAll(
  details: object,
  callback?: function,
)

Recupera todas las cookies de un solo almacén de cookies que coincidan con la información proporcionada. Las cookies que se devuelvan 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

    Es la información para filtrar las cookies que se recuperan.

    • dominio

      cadena opcional

      Restringe las cookies recuperadas a aquellas cuyos dominios coinciden o son subdominios de este.

    • nombre

      cadena opcional

      Filtra las cookies por nombre.

    • partitionKey

      CookiePartitionKey opcional

      Chrome 119 y versiones posteriores

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

    • 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 las cookies de sesión y las persistentes.

    • storeId

      cadena opcional

      Es el almacén de cookies desde el que se recuperarán 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 callback se ve de la siguiente manera: 

    (cookies: Cookie[]) => void

    • cookies

      Cookie[]

      Todas las cookies existentes sin vencer que coincidan con la información de la cookie determinada

Muestra

  • Promise<Cookie[]>

    Chrome 88 y versiones posteriores

    Las promesas solo se admiten para Manifest V3 y versiones posteriores. Otras plataformas deben usar devoluciones de llamada.

getAllCookieStores()

Promesa 
chrome.cookies.getAllCookieStores(
  callback?: function,
)

Enumera todas las tiendas de cookies existentes.

Parámetros

  • callback

    función opcional

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

    (cookieStores: CookieStore[]) => void

    • cookieStores

      CookieStore[]

      Todas las tiendas de cookies existentes

Muestra

  • Promise<CookieStore[]>

    Chrome 88 y versiones posteriores

    Las promesas solo se admiten para Manifest V3 y versiones posteriores. Otras plataformas deben usar devoluciones de llamada.

getPartitionKey()

Promise Pending
chrome.cookies.getPartitionKey(
  details: FrameDetails,
  callback?: function,
)

Es la clave de partición del fotograma indicado.

Parámetros

  • detalles

    FrameDetails

  • callback

    función opcional

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

    (details: object) => void

    • detalles

      objeto

      Contiene detalles sobre la clave de partición que se recuperó.

      • partitionKey

        CookiePartitionKey

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

Muestra

  • Promise<object>

    Las promesas solo se admiten para Manifest V3 y versiones posteriores. Otras plataformas deben usar devoluciones de llamada.

remove()

Promesa 
chrome.cookies.remove(
  details: CookieDetails,
  callback?: function,
)

Borra una cookie por nombre.

Parámetros

  • detalles

    CookieDetails

  • callback

    función opcional

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

    (details?: object) => void

    • detalles

      objeto opcional

      Contiene detalles sobre la cookie que se quitó. Si la eliminación falló por algún motivo, este valor será “nulo” y se establecerá runtime.lastError.

      • nombre

        string

        Es el nombre de la cookie que se quitó.

      • partitionKey

        CookiePartitionKey opcional

        Chrome 119 y versiones posteriores

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

      • storeId

        string

        Es el ID del almacén de cookies del que se quitó la cookie.

      • url

        string

        Es la URL asociada con la cookie que se quitó.

Muestra

  • Promesa<objeto | undefined>

    Chrome 88 y versiones posteriores

    Las promesas solo se admiten para Manifest V3 y versiones posteriores. Otras plataformas deben usar devoluciones de llamada.

set()

Promesa 
chrome.cookies.set(
  details: object,
  callback?: function,
)

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

Parámetros

  • detalles

    objeto

    Detalles sobre la cookie que se establece.

    • dominio

      cadena opcional

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

    • expirationDate

      número opcional

      La fecha de vencimiento de la cookie como la cantidad de segundos desde el epoch 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

      cadena opcional

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

    • partitionKey

      CookiePartitionKey opcional

      Chrome 119 y versiones posteriores

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

    • ruta de acceso

      cadena opcional

      Es la ruta de la cookie. De forma predeterminada, se establece en la parte de ruta del parámetro de URL.

    • sameSite

      SameSiteStatus opcional

      Chrome 51 y versiones posteriores

      El estado de la cookie del mismo 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

      cadena 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 la cookie creada. Si no se especifican los permisos de host para esta URL en el archivo de manifiesto, fallará la llamada a la API.

    • valor

      cadena opcional

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

  • callback

    función opcional

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

    (cookie?: Cookie) => void

    • galleta

      Cookie opcional

      Contiene detalles sobre la cookie que se configuró. Si el parámetro de configuración falló por algún motivo, este será “nulo” y se establecerá runtime.lastError.

Muestra

  • Promise<Cookie | undefined>

    Chrome 88 y versiones posteriores

    Las promesas solo se admiten para Manifest V3 y versiones posteriores. Otras plataformas deben usar devoluciones de llamada.

Eventos

onChanged

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

Se activa cuando se establece 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: primero, se quita por completo la cookie que se actualizará, lo que genera una notificación con la "causa" de "reemplazo" . 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 configuró o quitó

      • quitado

        booleano

        Es verdadero si se quitó una cookie.