chrome.cookies

Descripción

Usa la API de chrome.cookies para consultar y modificar cookies, y recibir notificaciones cuando estas 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 vincularse con el 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 cookies en la partición predeterminada.

Para obtener detalles sobre el impacto general de la partición de 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 visualizar 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

    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

    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 ella).

  • nombre

    string

    Es el nombre de la cookie.

  • partitionKey

    CookiePartitionKey opcional

    Chrome 119 y versiones posteriores

    La clave de partición para leer o modificar cookies con el atributo de partición.

  • ruta de acceso

    string

    Es la ruta de la cookie.

  • sameSite

    SameSiteStatus

    Chrome 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

    Verdadero si la cookie está marcada como segura (es decir, su alcance está limitado a canales seguros, normalmente HTTPS).

  • sesión

    boolean

    Es verdadero si la cookie es de sesión, en lugar 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

Son los 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

    Es el ID de la tienda de cookies en la 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 está asociada la cookie a la que se accede. Este argumento puede ser una URL completa, en cuyo caso cualquier dato que siga a la ruta de URL (p.ej., la cadena de consulta) simplemente se ignora. 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

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

Propiedades

  • hasCrossSiteAncestor

    booleano opcional

    Chrome 130 y versiones posteriores

    Indica si la cookie se configuró en un contexto que abarca varios sitios. 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

    número

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

OnChangedCause

Chrome 44 y versiones posteriores

Es 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án "explícitos". Si una cookie se quitó automáticamente debido a su vencimiento, "cause" caducará. 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 en consecuencia.

Enum

"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

"strict"

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 dada, se mostrará la que tenga la ruta de acceso 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

  • Promesa<Cookie | indefinido>

    Chrome 88 y versiones posteriores

    Las promesas solo son compatibles con 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 devueltas se ordenarán, donde aparecerán primero las que tengan la ruta de acceso más larga. 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

      string 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 frente a las persistentes.

    • storeId

      cadena opcional

      El almacén de cookies desde el que se recuperan las cookies. Si se omite, se usará la tienda de cookies del contexto de ejecución actual.

    • url

      cadena opcional

      Restringe las cookies recuperadas a aquellas que coinciden con la URL dada.

  • callback

    función opcional

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

    (cookies: Cookie[]) => void

    • cookies

      Cookie[]

      Todas las cookies existentes y no vencidas que coinciden con la información de cookie especificada.

Muestra

  • Promesa<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&lt;CookieStore[]&gt;

    Chrome 88 y versiones posteriores

    Las promesas solo son compatibles con 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

        El nombre de la cookie que se quitó.

      • partitionKey

        CookiePartitionKey opcional

        Chrome 119 y versiones posteriores

        La clave de partición para leer o modificar cookies con el atributo de partición.

      • storeId

        string

        Es el ID de la tienda de cookies de la que se quitó la cookie.

      • url

        string

        La URL asociada con la cookie que se quitó

Muestra

  • Promise<object | undefined>

    Chrome 88 y versiones posteriores

    Las promesas solo son compatibles con Manifest V3 y versiones posteriores; otras plataformas deben usar devoluciones de llamada.

set()

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

Configura una cookie con los datos de cookies proporcionados. puede reemplazar cookies equivalentes, si existen.

Parámetros

  • detalles

    objeto

    Detalles acerca de la configuración de la cookie.

    • dominio

      string opcional

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

    • expirationDate

      número opcional

      Fecha de vencimiento de la cookie como el número de segundos transcurridos desde la época 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, estará 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

      string 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 del mismo sitio de la cookie. 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 de la tienda de cookies en la 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

      cadena opcional

      Es el valor de la cookie. Si se omite, estará 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 por algún motivo, se produce un error en la configuración, el valor 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 se quitó.

      • quitado

        boolean

        Es verdadero si se quitó una cookie.