chrome.cookies

Descripción

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

Permisos

cookies

Para usar la API de cookies, declara el permiso "cookies" en tu manifiesto junto con los permisos de host para todos los hosts cuyas cookies desees para 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 fotograma 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 de A pueden tener distintos valores en B y C.

De forma predeterminada, todos los métodos de la API operan en cookies no particionadas. El 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 sencillo del uso de la API de cookies en la 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

    Fecha de vencimiento de la cookie como el número de segundos transcurridos desde la época UNIX. No se proporciona para las cookies de sesión.

  • hostOnly

    boolean

    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

    boolean

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

  • 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 fecha de vencimiento.

  • storeId

    string

    Es el ID de la tienda 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 accederá.

  • 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 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

    La URL con la que está asociada la cookie de acceso. 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

    Pendiente

    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 varios 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 una tienda de cookies en el navegador. Por ejemplo, una ventana en modo incógnito utiliza 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 debido a que se reemplazó por una fecha de vencimiento que ya venció, "cause" se configurará como “expired_overwrite”. Si se quitó una cookie automáticamente debido a la recolección de elementos no utilizados, se "expulsará" la "causa". Si se quitó automáticamente una cookie debido a un “conjunto” la llamaron y la reemplazaron, "causa" "overwrite". Planifica tu respuesta en consecuencia.

Enum

SameSiteStatus

Chrome 51 y versiones posteriores

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

Métodos

get()

Promise 
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 temprana.

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 encuentra tal cookie.

Muestra

  • Promise<Cookie | indefinido>

    Chrome 88 y versiones posteriores

    Las promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para retrocompatibilidad. No puedes usar ambos en la misma llamada a función. El se resuelve con el mismo tipo que se pasa a la devolución de llamada.

getAll()

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

Recupera todas las cookies de un solo almacén de cookies que coinciden con la información proporcionada. Las cookies mostradas se ordenarán, con las que tengan la ruta de acceso más larga primero. Si varias cookies tienen la misma ruta de interacciones, aparecerán primero aquellas con la hora de creación más temprana. 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 coinciden con esta o que son subdominios de esta.

    • nombre

      string opcional

      Filtra las cookies por nombre.

    • 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 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

      string 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

      string 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

      Galleta

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

Muestra

  • Promise<Cookie[]>

    Chrome 88 y versiones posteriores

    Las promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para retrocompatibilidad. No puedes usar ambos en la misma llamada a función. El se resuelve con el mismo tipo que se pasa a la devolución de llamada.

getAllCookieStores()

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

Muestra una lista de todos los almacenes 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 son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para retrocompatibilidad. No puedes usar ambos en la misma llamada a función. El se resuelve con el mismo tipo que se pasa a la devolución de llamada.

remove()

Promise 
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 por algún motivo la eliminación falla, el 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

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

Muestra

  • Promise<object | indefinido>

    Chrome 88 y versiones posteriores

    Las promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para retrocompatibilidad. No puedes usar ambos en la misma llamada a función. El se resuelve con el mismo tipo que se pasa a la devolución de llamada.

set()

Promise 
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

      string opcional

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

    • 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 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 posteriores

      El estado del mismo sitio de la cookie. El valor predeterminado es "no especificado", es decir, si se omite, la cookie se establece sin especificar un atributo de 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

      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, 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 | indefinido>

    Chrome 88 y versiones posteriores

    Las promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para retrocompatibilidad. No puedes usar ambos en la misma llamada a función. El 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á primero se quita por completo y se genera una notificación con la palabra "cause". de "sobrescribir" de Google Cloud. Luego, se escribe una cookie nueva con los valores actualizados y se genera una segunda notificación con la palabra “cause”. "explícito".

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

        Galleta

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

      • quitado

        boolean

        Es verdadero si se quitó una cookie.