chrome.cookies

Descrição

Use a API chrome.cookies para consultar e modificar cookies e receber uma notificação quando eles mudarem.

Permissões

cookies

Para usar a API de cookies, declare a permissão "cookies" na sua junto com as permissões de host dos hosts cujos cookies você deseja para 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 vinculados à 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 site C, as versões incorporadas de um cookie particionado de A podem ter valores diferentes em B e C.

Por padrão, todos os métodos de API operam em cookies não particionados. O 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

Você pode encontrar um exemplo simples de como usar a API de cookies na examples/api/cookies. Para outros exemplos e para obter ajuda na visualização o código-fonte, consulte Amostras.

Tipos

Representa informações sobre um cookie HTTP.

Propriedades

  • domínio

    string

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

  • expirationDate

    número opcional

    A data de validade 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 for um cookie 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 não pode ser acessado pelos scripts do lado do cliente).

  • nome

    string

    O nome do cookie.

  • partitionKey

    CookiePartitionKey opcional

    Chrome 119 ou versões mais recentes

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

  • caminho

    string

    O caminho do cookie.

  • sameSite

    SameSiteStatus

    Chrome 51 ou superior

    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, seu escopo é limitado a canais seguros, normalmente HTTPS).

  • sessão

    booleano

    Verdadeiro se o cookie for de sessão, ao contrário de um cookie permanente 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 ou superior

Detalhes para identificar o cookie.

Propriedades

  • nome

    string

    O nome do cookie a ser acessado.

  • partitionKey

    CookiePartitionKey opcional

    Chrome 119 ou versões mais recentes

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

  • 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 de acesso 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 de host para esse URL não forem especificadas no arquivo de manifesto, a chamada da API vai falhar.

CookiePartitionKey

Chrome 119 ou versões mais recentes

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

Propriedades

  • hasCrossSiteAncestor

    booleano opcional

    Pendente

    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 os cookies definidos por esse site no 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. Uma janela no modo 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 do armazenamento de cookies.

  • tabIds

    número[]

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

OnChangedCause

Chrome 44 ou superior

O motivo por trás 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 ao vencimento, "causa" será "expirado". Se um cookie foi removido por ter sido substituído por uma data de validade já expirada, "causa" será definido como " expirado_overwrite". Se um cookie foi removido automaticamente devido à coleta de lixo, "causa" serão "removidos". Se um cookie tiver sido removido automaticamente devido a um "set" que a substituiu, como "causa" será "substituir". Planeje sua resposta de acordo.

Enumeração

SameSiteStatus

Chrome 51 ou superior

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

Enumeração

(link em inglês)

Métodos

get()

Promise 
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, aquele com o caminho mais longo será retornado. Para cookies com o mesmo tamanho de caminho, aquele com o horário de criação mais antigo será retornado.

Parâmetros

  • detalhes

    CookieDetails

  • callback

    função opcional

    O parâmetro callback tem esta aparência: 

    (cookie?: Cookie) => void

    • biscoito

      Cookie opcional

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

Retorna

  • Promise<Cookie | indefinido>

    Chrome 88 ou superior

    O Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para a compatibilidade com versões anteriores. Não é possível usar ambos na mesma chamada de função. O promessa é resolvida com o mesmo tipo passado ao retorno de chamada.

getAll()

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

Recupera todos os cookies de um único repositório de cookies que correspondem às informações fornecidas. Os cookies retornados serão classificados, com o 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 recupera apenas 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 aos domínios que correspondem ou são subdomínios deste.

    • nome

      string opcional

      Filtra os cookies por nome.

    • partitionKey

      CookiePartitionKey opcional

      Chrome 119 ou versões mais recentes

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

    • caminho

      string opcional

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

    • seguro

      booleano opcional

      Filtra os cookies pela propriedade "Secure".

    • sessão

      booleano opcional

      Filtra os cookies de sessão e persistentes.

    • storeId

      string opcional

      O armazenamento de cookies do qual 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 aos que corresponderiam ao URL fornecido.

  • callback

    função opcional

    O parâmetro callback tem esta aparência: 

    (cookies: Cookie[]) => void

    • cookies

      Cookie[]

      Todos os cookies atuais não expirados que correspondem às informações especificadas.

Retorna

  • Promise<Cookie[]>

    Chrome 88 ou superior

    O Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para a compatibilidade com versões anteriores. Não é possível usar ambos na mesma chamada de função. O promessa é resolvida com o mesmo tipo passado ao retorno de chamada.

getAllCookieStores()

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

Lista todos os repositórios de cookies existentes.

Parâmetros

  • callback

    função opcional

    O parâmetro callback tem esta aparência: 

    (cookieStores: CookieStore[]) => void

    • cookieStores

      CookieStore[]

      Todos os armazenamentos de cookies atuais.

Retorna

  • Promise<CookieStore[]>

    Chrome 88 ou superior

    O Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para a compatibilidade com versões anteriores. Não é possível usar ambos na mesma chamada de função. O promessa é resolvida com o mesmo tipo passado ao retorno de chamada.

remove()

Promise 
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 esta aparência: 

    (details?: object) => void

    • detalhes

      objeto opcional

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

      • nome

        string

        O nome do cookie que foi removido.

      • partitionKey

        CookiePartitionKey opcional

        Chrome 119 ou versões mais recentes

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

      • storeId

        string

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

      • url

        string

        O URL associado ao cookie que foi removido.

Retorna

  • Promise<object | indefinido>

    Chrome 88 ou superior

    O Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para a compatibilidade com versões anteriores. Não é possível usar ambos na mesma chamada de função. O promessa é resolvida com o mesmo tipo passado ao retorno de chamada.

set()

Promise 
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 somente host.

    • expirationDate

      número opcional

      A data de validade 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

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

    • nome

      string opcional

      O nome do cookie. Vai ficar vazio por padrão se for omitido.

    • partitionKey

      CookiePartitionKey opcional

      Chrome 119 ou versões mais recentes

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

    • caminho

      string opcional

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

    • sameSite

      SameSiteStatus opcional

      Chrome 51 ou superior

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

    • seguro

      booleano opcional

      Indica se o cookie deve ser marcado como seguro. 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 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 de domínio e caminho padrão do cookie criado. Se as permissões de 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. Vai ficar vazio por padrão se for omitido.

  • callback

    função opcional

    O parâmetro callback tem esta aparência: 

    (cookie?: Cookie) => void

    • biscoito

      Cookie opcional

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

Retorna

  • Promise<Cookie | indefinido>

    Chrome 88 ou superior

    O Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para a compatibilidade com versões anteriores. Não é possível usar ambos na mesma chamada de função. O promessa é resolvida com o mesmo tipo passado ao retorno de chamada.

Eventos

onChanged

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

Disparado 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 é removido totalmente primeiro, gerando uma notificação com "causa" de "substituir" , Em seguida, um novo cookie é gravado com os valores atualizados, gerando uma segunda notificação com a causa "explícito".

Parâmetros

  • callback

    função

    O parâmetro callback tem esta aparência: 

    (changeInfo: object) => void

    • changeInfo

      objeto

      • O motivo por trás da mudança do cookie.

      • biscoito

        Cookie

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

      • removido

        booleano

        Verdadeiro se um cookie tiver sido removido.