browser.cookies

Descrição

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

Permissões

cookies

Para usar a API cookies, declare a permissão "cookies" no manifesto, junto com as permissões de 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 associados à origem do frame de nível superior. Isso significa que, por exemplo, se o site A for incorporado usando um iframe no site B e no site C, as versões incorporadas de um cookie particionado de A poderão ter valores diferentes em B e C.

Por padrão, todos os métodos de API operam em cookies não particionados. A propriedade partitionKey pode ser usada para substituir esse comportamento.

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

Exemplos

Confira um exemplo simples de uso da API de cookies no diretório examples/api/cookies. Para ver 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 optional

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

  • hostOnly

    booleano

    Verdadeiro se o cookie for somente de host (ou seja, o host de uma solicitação precisa corresponder exatamente ao domínio do cookie).

  • httpOnly

    booleano

    Verdadeiro se o cookie estiver marcado como HttpOnly (ou seja, o cookie está inacessível para linguagem de cliente).

  • nome

    string

    O nome do cookie.

  • partitionKey

    CookiePartitionKey opcional

    Chrome 119+ browser.* desde o Chrome 148

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

  • caminho

    string

    O caminho do cookie.

  • sameSite

    SameSiteStatus

    Chrome 51+ browser.* desde o Chrome 148

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

  • seguro

    booleano

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

  • sessão

    booleano

    Verdadeiro se o cookie for de sessão, em vez de um cookie persistente com uma 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+ browser.* desde o Chrome 148

Detalhes para identificar o cookie.

Propriedades

  • nome

    string

    O nome do cookie a ser acessado.

  • partitionKey

    CookiePartitionKey opcional

    Chrome 119+ browser.* desde o Chrome 148

    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, o armazenamento de cookies do contexto de execução atual será usado.

  • url

    string

    O URL ao qual 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 ignorados. Se as permissões de host para esse URL não forem especificadas no arquivo de manifesto, a chamada de API vai falhar.

CookiePartitionKey

Chrome 119+ browser.* desde o Chrome 148

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

Propriedades

  • hasCrossSiteAncestor

    booleano opcional

    Chrome 130+ browser.* desde o Chrome 148

    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 do 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. Por exemplo, uma janela do modo de navegação anônima usa um armazenamento de cookies separado de uma janela que não é anônima.

Propriedades

  • ID

    string

    O identificador exclusivo do armazenamento de cookies.

  • tabIds

    number[]

    Identificadores de todas as guias do navegador que compartilham esse repositório de cookies.

FrameDetails

Chrome 132+ browser.* desde o Chrome 148

Detalhes para identificar o frame.

Propriedades

  • documentId

    string opcional

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

  • frameId

    número optional

    O identificador exclusivo do frame na guia.

  • tabId

    número optional

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

OnChangedCause

Chrome 44+ browser.* desde o Chrome 148

O motivo da mudança do cookie. Se um cookie foi inserido ou removido por uma chamada explícita para "chrome.cookies.remove", "cause" será "explicit". Se um cookie foi removido automaticamente devido à expiração, "cause" será "expired". Se um cookie foi removido porque foi substituído por uma data de validade já expirada, "cause" será definido como "expired_overwrite". Se um cookie foi removido automaticamente devido à coleta de lixo, "cause" será "evicted". Se um cookie foi removido automaticamente devido a uma chamada "set" que o substituiu, "cause" será "overwrite". Planeje sua resposta de acordo.

Enumeração

"evicted"

"expired"

"explicit"

"expired_overwrite"

"overwrite"

SameSiteStatus

Chrome 51+ browser.* desde o Chrome 148

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" a "SameSite=Lax" e "strict" a "SameSite=Strict". "unspecified" corresponde a um cookie definido sem o atributo SameSite.

Enumeração

"no_restriction"

"lax"

"strict"

"unspecified"

Métodos

get()

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

Recupera informações sobre um cookie individual. Se houver mais de um cookie com o mesmo nome para o URL fornecido, aquele com o caminho mais longo será retornado. Para cookies com o mesmo tamanho de caminho, o cookie com o horário de criação mais antigo será retornado.

Parâmetros

Retorna

  • Promise<Cookie | undefined>

    Chrome 88+ browser.* desde o Chrome 148

getAll()

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

Recupera todos os cookies de um repositório que correspondem às informações fornecidas. Os cookies retornados serão classificados, com os de caminho mais longo primeiro. Se vários cookies tiverem o mesmo tamanho de caminho, aqueles com o horário 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 àqueles cujos domínios correspondem ou são subdomínios deste.

    • nome

      string opcional

      Filtra os cookies por nome.

    • partitionKey

      CookiePartitionKey opcional

      Chrome 119+ browser.* desde o Chrome 148

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

    • caminho

      string opcional

      Restringe os cookies recuperados àqueles cujo caminho corresponde exatamente a essa string.

    • seguro

      booleano opcional

      Filtra os cookies pela propriedade Secure.

    • sessão

      booleano opcional

      Filtra cookies de sessão e persistentes.

    • storeId

      string opcional

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

    • url

      string opcional

      Restringe os cookies recuperados àqueles que correspondem ao URL fornecido.

Retorna

  • Promise<Cookie[]>

    Chrome 88+ browser.* desde o Chrome 148

getAllCookieStores()

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

Lista todos os armazenamentos de cookies atuais.

Retorna

  • Promise<CookieStore[]>

    Chrome 88+ browser.* desde o Chrome 148

getPartitionKey()

Chrome 132+ browser.* desde o Chrome 148 
browser.cookies.getPartitionKey(
  details: FrameDetails,
): Promise<object>

A chave de partição do frame indicado.

Parâmetros

Retorna

  • Promise<object>

remove()

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

Exclui um cookie pelo nome.

Parâmetros

Retorna

  • Promise<object | undefined>

    Chrome 88+ browser.* desde o Chrome 148

set()

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

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 de host.

    • expirationDate

      número optional

      A data de validade do cookie como o número de segundos desde a época 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 é "falso".

    • nome

      string opcional

      O nome do cookie. Se omitido, o padrão é vazio.

    • partitionKey

      CookiePartitionKey opcional

      Chrome 119+ browser.* desde o Chrome 148

      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+ browser.* desde o Chrome 148

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

    • seguro

      booleano opcional

      Se o cookie precisa ser marcado como seguro. O padrão é "falso".

    • storeId

      string opcional

      O ID do armazenamento de cookies em que o cookie será definido. Por padrão, o cookie é definido no armazenamento 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 padrão de domínio e caminho do cookie criado. Se as permissões de host para esse URL não forem especificadas no arquivo de manifesto, a chamada de API vai falhar.

    • valor

      string opcional

      O valor do cookie. Se omitido, o padrão é vazio.

Retorna

  • Promise<Cookie | undefined>

    Chrome 88+ browser.* desde o Chrome 148

Eventos

onChanged

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

Acionado quando um cookie é definido ou removido. Como um caso especial, observe que a atualização das propriedades de um cookie é implementada como um processo de duas etapas: o cookie a ser atualizado é primeiro removido completamente, gerando uma notificação com "cause" de "overwrite" . Depois, um novo cookie é gravado com os valores atualizados, gerando uma segunda notificação com "cause" "explicit".

Parâmetros

  • callback

    função

    O parâmetro callback é semelhante a: 

    (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.