chrome.cookies

Descrição

Use a API chrome.cookies para consultar e modificar cookies e receber notificações quando eles mudarem.

Permissões

cookies

Manifesto

Para usar a API cookies, declare a permissão "cookies" no manifesto, junto com as permissões do host para todos os hosts cujos cookies você quer acessar. Exemplo:

{
  "name": "My extension",
  ...
  "host_permissions": [
    "*://*.google.com/"
  ],
  "permissions": [
    "cookies"
  ],
  ...
}

Particionamento

Os cookies particionados permitem que um site marque que determinados cookies precisam ser codificados com base na origem do frame de nível superior. Isso significa que, se o site A for incorporado usando um iframe no site B e no site C, um cookie particionado poderá ter um valor diferente em cada um.

O chrome.cookies não oferece suporte ao particionamento, o que significa que todos os métodos lêem e gravam cookies de todas as partições. O método cookies.set() armazena cookies na partição padrão.

Para saber mais sobre o impacto geral do particionamento para extensões, consulte Armazenamento e cookies.

Exemplos

Confira um exemplo simples de uso da API Cookies no diretório examples/api/cookies. Para conferir outros exemplos e receber ajuda para visualizar o código-fonte, consulte Exemplos.

Tipos

Representa informações sobre um cookie HTTP.

Propriedades

  • domínio

    string

    O domínio do cookie (por exemplo, "www.google.com", "example.com").

  • expirationDate

    número opcional

    A data de expiração do cookie como o número de segundos desde a época do UNIX. Não fornecido para cookies de sessão.

  • hostOnly

    booleano

    Verdadeiro se o cookie for exclusivo para host, ou seja, se o host de uma solicitação precisar corresponder exatamente ao domínio do cookie.

  • httpOnly

    booleano

    Verdadeiro se o cookie estiver marcado como HttpOnly (ou seja, se o cookie for inacessível para scripts do lado do cliente).

  • nome

    string

    O nome do cookie.

  • partitionKey

    CookiePartitionKey opcional

    Chrome 119 e versões mais recentes

    A chave de partição para ler ou modificar cookies com o atributo "Partitioned".

  • caminho

    string

    O caminho do cookie.

  • sameSite

    SameSiteStatus

    Chrome 51 e versões mais recentes

    O status do cookie no mesmo site (ou seja, se ele é enviado com solicitações entre sites).

  • seguro

    booleano

    Verdadeiro se o cookie estiver marcado como seguro (ou seja, se o escopo dele for limitado a canais seguros, normalmente HTTPS).

  • sessão

    booleano

    Verdadeiro se o cookie for de sessão, em vez de um cookie persistente com data de validade.

  • storeId

    string

    O ID do armazenamento de cookies que contém esse cookie, conforme fornecido em getAllCookieStores().

  • valor

    string

    O valor do cookie.

CookieDetails

Chrome 88 e versões mais recentes

Detalhes para identificar o cookie.

Propriedades

  • nome

    string

    O nome do cookie a ser acessado.

  • partitionKey

    CookiePartitionKey opcional

    Chrome 119 e versões mais recentes

    A chave de partição para ler ou modificar cookies com o atributo "Partitioned".

  • storeId

    string opcional

    O ID do armazenamento de cookies em que o cookie será procurado. Por padrão, a loja de cookies do contexto de execução atual será usada.

  • url

    string

    O URL com que o cookie a ser acessado está associado. Esse argumento pode ser um URL completo. Nesse caso, todos os dados que seguem o caminho do URL (por exemplo, a string de consulta) são simplesmente ignorados. Se as permissões do host para esse URL não forem especificadas no arquivo de manifesto, a chamada da API vai falhar.

CookiePartitionKey

Chrome 119 e versões mais recentes

Representa a chave de partição de um cookie particionado.

Propriedades

  • hasCrossSiteAncestor

    booleano opcional

    Chrome 130 e versões mais recentes

    Indica se o cookie foi definido em um contexto entre sites. Isso impede que um site de nível superior incorporado em um contexto entre sites acesse cookies definidos pelo site de nível superior em um contexto no mesmo site.

  • topLevelSite

    string opcional

    O site de nível superior em que o cookie particionado está disponível.

CookieStore

Representa um armazenamento de cookies no navegador. Uma janela de navegação anônima, por exemplo, usa um armazenamento de cookies separado de uma janela não anônima.

Propriedades

  • id

    string

    O identificador exclusivo da loja de cookies.

  • tabIds

    number[]

    Identificadores de todas as guias do navegador que compartilham esse armazenamento de cookies.

FrameDetails

Pendente

Detalhes para identificar o frame.

Propriedades

  • documentId

    string opcional

    O identificador exclusivo do documento. Se o frameId e/ou tabId forem fornecidos, eles serão validados para corresponder ao documento encontrado pelo ID do documento fornecido.

  • frameId

    número opcional

    O identificador exclusivo do frame na guia.

  • tabId

    número opcional

    O identificador exclusivo da guia que contém o frame.

OnChangedCause

Chrome 44 e versões mais recentes

O motivo da mudança do cookie. Se um cookie foi inserido ou removido por uma chamada explícita para "chrome.cookies.remove", a "causa" será "explícita". Se um cookie foi removido automaticamente devido à expiração, a "causa" será "expirada". Se um cookie foi removido por ter sido substituído com uma data de validade vencida, a "causa" será definida como "expired_overwrite". Se um cookie for removido automaticamente devido à coleta de lixo, a "causa" será "expulsa". Se um cookie foi removido automaticamente devido a uma chamada "set" que o substituiu, a causa será "overwrite". Planeje sua resposta de acordo.

Enumeração

"evicted"

"expired"

"explicit"

"expired_overwrite"

"overwrite"

SameSiteStatus

Chrome 51 e versões mais recentes

O estado "SameSite" de um cookie (https://tools.ietf.org/html/draft-west-first-party-cookies). "no_restriction" corresponde a um cookie definido com "SameSite=None", "lax" para "SameSite=Lax" e "strict" para "SameSite=Strict". "unspecified" corresponde a um cookie definido sem o atributo SameSite.

Enumeração

"no_restriction"

"lax"

"strict"

"unspecified"

Métodos

get()

Promessa 
chrome.cookies.get(
  details: CookieDetails,
  callback?: function,
)

Recupera informações sobre um único cookie. Se houver mais de um cookie com o mesmo nome para o URL fornecido, o cookie com o caminho mais longo será retornado. Para cookies com o mesmo comprimento de caminho, o cookie com o tempo de criação mais curto será retornado.

Parâmetros

  • detalhes

    CookieDetails

  • callback

    função opcional

    O parâmetro callback tem este formato: 

    (cookie?: Cookie) => void

    • biscoito

      Cookie opcional

      Contém detalhes sobre o cookie. Esse parâmetro é nulo se nenhum cookie desse tipo for encontrado.

Retorna

  • Promise<Cookie | undefined>

    Chrome 88 e versões mais recentes

    As promessas têm suporte apenas para o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

getAll()

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

Recupera todos os cookies de um único armazenamento de cookies que correspondem às informações fornecidas. Os cookies retornados serão classificados, com aqueles com o caminho mais longo em primeiro lugar. Se vários cookies tiverem o mesmo comprimento de caminho, os que tiverem o tempo de criação mais antigo serão os primeiros. Esse método só recupera cookies de domínios para os quais a extensão tem permissões de host.

Parâmetros

  • detalhes

    objeto

    Informações para filtrar os cookies que estão sendo recuperados.

    • domínio

      string opcional

      Restringe os cookies recuperados a aqueles cujos domínios correspondem ou são subdomínios deste.

    • nome

      string opcional

      Filtra os cookies por nome.

    • partitionKey

      CookiePartitionKey opcional

      Chrome 119 e versões mais recentes

      A chave de partição para ler ou modificar cookies com o atributo "Partitioned".

    • caminho

      string opcional

      Restringe os cookies recuperados aos que têm um caminho que corresponde exatamente a essa string.

    • seguro

      booleano opcional

      Filtra os cookies pela propriedade "Secure".

    • sessão

      booleano opcional

      Filtra cookies de sessão e cookies persistentes.

    • storeId

      string opcional

      O armazenamento de cookies de onde os cookies serão recuperados. Se omitido, a loja de cookies do contexto de execução atual será usada.

    • url

      string opcional

      Restringe os cookies recuperados aos que correspondem ao URL fornecido.

  • callback

    função opcional

    O parâmetro callback tem este formato: 

    (cookies: Cookie[]) => void

    • cookies

      Cookie[]

      Todos os cookies existentes e não expirados que correspondem às informações do cookie.

Retorna

  • Promise<Cookie[]>

    Chrome 88 e versões mais recentes

    As promessas têm suporte apenas para o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

getAllCookieStores()

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

Lista todas as lojas de cookies.

Parâmetros

  • callback

    função opcional

    O parâmetro callback tem este formato: 

    (cookieStores: CookieStore[]) => void

    • cookieStores

      CookieStore[]

      Todas as lojas de cookies existentes.

Retorna

  • Promise<CookieStore[]>

    Chrome 88 e versões mais recentes

    As promessas têm suporte apenas para o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

getPartitionKey()

Promessa Pendente
chrome.cookies.getPartitionKey(
  details: FrameDetails,
  callback?: function,
)

A chave de partição do frame indicado.

Parâmetros

  • detalhes

    FrameDetails

  • callback

    função opcional

    O parâmetro callback tem este formato: 

    (details: object) => void

    • detalhes

      objeto

      Contém detalhes sobre a chave de partição que foi recuperada.

      • partitionKey

        CookiePartitionKey

        A chave de partição para ler ou modificar cookies com o atributo "Partitioned".

Retorna

  • Promise<object>

    As promessas têm suporte apenas para o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

remove()

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

Exclui um cookie por nome.

Parâmetros

  • detalhes

    CookieDetails

  • callback

    função opcional

    O parâmetro callback tem este formato: 

    (details?: object) => void

    • detalhes

      objeto opcional

      Contém detalhes sobre o cookie removido. Se a remoção falhar por algum motivo, o valor será "null", e runtime.lastError será definido.

      • nome

        string

        O nome do cookie que foi removido.

      • partitionKey

        CookiePartitionKey opcional

        Chrome 119 e versões mais recentes

        A chave de partição para ler ou modificar cookies com o atributo "Partitioned".

      • storeId

        string

        O ID do armazenamento de cookies de onde o cookie foi removido.

      • url

        string

        O URL associado ao cookie que foi removido.

Retorna

  • Promise<object | undefined>

    Chrome 88 e versões mais recentes

    As promessas têm suporte apenas para o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

set()

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

Define um cookie com os dados fornecidos. Pode substituir cookies equivalentes, se houver.

Parâmetros

  • detalhes

    objeto

    Detalhes sobre o cookie que está sendo definido.

    • domínio

      string opcional

      O domínio do cookie. Se omitido, o cookie se torna um cookie somente do host.

    • expirationDate

      número opcional

      A data de expiração do cookie como o número de segundos desde a época do UNIX. Se omitido, o cookie se torna um cookie de sessão.

    • httpOnly

      booleano opcional

      Se o cookie precisa ser marcado como HttpOnly. O padrão é "false".

    • nome

      string opcional

      O nome do cookie. Vazio por padrão se omitido.

    • partitionKey

      CookiePartitionKey opcional

      Chrome 119 e versões mais recentes

      A chave de partição para ler ou modificar cookies com o atributo "Partitioned".

    • caminho

      string opcional

      O caminho do cookie. O padrão é a parte do caminho do parâmetro de URL.

    • sameSite

      SameSiteStatus opcional

      Chrome 51 e versões mais recentes

      O status do cookie no mesmo site. O padrão é "unspecified", ou seja, se o atributo SameSite for omitido, o cookie será definido sem especificar um atributo SameSite.

    • seguro

      booleano opcional

      Se o cookie precisa ser marcado como "Secure". O padrão é "false".

    • storeId

      string opcional

      O ID do armazenamento de cookies em que o cookie será definido. Por padrão, o cookie é definido na loja de cookies do contexto de execução atual.

    • url

      string

      O URI de solicitação a ser associado à configuração do cookie. Esse valor pode afetar os valores de domínio e caminho padrão do cookie criado. Se as permissões do host para esse URL não forem especificadas no arquivo de manifesto, a chamada da API vai falhar.

    • valor

      string opcional

      O valor do cookie. Vazio por padrão se omitido.

  • callback

    função opcional

    O parâmetro callback tem este formato: 

    (cookie?: Cookie) => void

    • biscoito

      Cookie opcional

      Contém detalhes sobre o cookie que foi definido. Se a configuração falhar por algum motivo, ela será "null" e runtime.lastError será definido.

Retorna

  • Promise<Cookie | undefined>

    Chrome 88 e versões mais recentes

    As promessas têm suporte apenas para o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

Eventos

onChanged

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

Acionado quando um cookie é definido ou removido. Como um caso especial, a atualização das propriedades de um cookie é implementada como um processo de duas etapas: o cookie a ser atualizado é removido totalmente primeiro, gerando uma notificação com a "causa" de "substituir" . Em seguida, um novo cookie é gravado com os valores atualizados, gerando uma segunda notificação com a "causa" "explicita".

Parâmetros

  • callback

    função

    O parâmetro callback tem este formato: 

    (changeInfo: object) => void

    • changeInfo

      objeto

      • O motivo da mudança do cookie.

      • biscoito

        Cookie

        Informações sobre o cookie que foi definido ou removido.

      • removido

        booleano

        Verdadeiro se um cookie foi removido.