chrome.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 de cookies, declare a permissão "cookies" no seu manifesto com as permissões de host para todos os hosts com cookies que 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 na 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 da API operam em cookies não particionados. A propriedade partitionKey pode ser usada para substituir esse comportamento.

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

Exemplos

Um exemplo simples de uso da API de cookies está no diretório examples/api/cookies. Para ver outros exemplos e receber ajuda na visualização do 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", "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

    boolean

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

  • httpOnly

    boolean

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

  • name

    string

    O nome do cookie.

  • partitionKey

    CookiePartitionKey opcional

    Chrome 119 ou mais recente

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

  • caminho

    string

    Caminho do cookie.

  • sameSite

    SameSiteStatus

    Chrome 51 ou mais recente

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

  • seguro

    boolean

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

  • seção

    boolean

    Verdadeiro se o cookie for um cookie de sessão, ao contrário de um cookie persistente com uma data de validade.

  • storeId

    string

    O ID do repositório de cookies que contém o cookie, conforme fornecido em getAllCookieStores().

  • valor

    string

    Valor do cookie.

CookieDetails

Chrome 88 ou mais recente

Detalhes para identificar o cookie.

Propriedades

  • name

    string

    Nome do cookie a ser acessado.

  • partitionKey

    CookiePartitionKey opcional

    Chrome 119 ou mais recente

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

  • storeId

    string opcional

    O ID do repositório de cookies em que o cookie será procurado. Por padrão, será usado o armazenamento de cookies do contexto de execução atual.

  • url

    string

    O URL ao qual o cookie de acesso está associado. Esse argumento pode ser um URL completo. Nesse caso, todos os dados após o caminho do URL (por exemplo, a string de consulta) serão simplesmente 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 ou mais recente

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

Propriedades

  • topLevelSite

    string opcional

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

CookieStore

Representa um repositório de cookies no navegador. Por exemplo, uma janela no modo de navegação anônima usa um armazenamento de cookies separado de uma janela não anônima.

Propriedades

  • id

    string

    O identificador exclusivo do repositório de cookies.

  • tabIds

    Número[]

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

OnChangedCause

Chrome 44 ou mais recente

O motivo por trás da alteração do cookie. Se um cookie tiver sido inserido ou removido por meio de uma chamada explícita para "chrome.cookies.remove", "causa" será "explícito". Se um cookie tiver sido removido automaticamente devido à data de validade, a "causa" será "expirado". Se um cookie tiver sido removido por ter sido substituído por uma data de validade já expirada, "Cause" será definido como "expiry_overwrite". Se um cookie tiver sido removido automaticamente devido à coleta de lixo, a "causa" será "removida". Se um cookie tiver sido removido automaticamente devido a uma chamada "set" que o substituiu, "Cause" será "overwrite". Planeje sua resposta adequadamente.

Tipo enumerado

SameSiteStatus

Chrome 51 ou mais recente

Estado "SameSite" de um cookie (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". "unspecified" corresponde a um cookie definido sem o atributo SameSite.

Tipo enumerado

"no_restriction"

"lax"

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 um determinado URL, aquele com o caminho mais longo será retornado. No caso de cookies com o mesmo tamanho de caminho, será retornado o cookie com o horário de criação mais antigo.

Parâmetros

  • detalhes

    CookieDetails

  • callback

    função optional

    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

  • Prometer<Cookie|undefined>

    Chrome 88 ou mais recente

    Promessas são compatíveis com o Manifest V3 e versões mais recentes, mas callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo que é passado para o callback.

getAll()

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

Recupera todos os cookies de um único repositório que correspondem às informações fornecidas. Os cookies retornados serão classificados, com aqueles que tiverem o caminho mais longo primeiro. Se vários cookies tiverem o mesmo tamanho de caminho, aqueles com a hora de criação mais antiga serão os primeiros. Esse método só recupera cookies de domínios em que 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 correspondam ou sejam subdomínios deste.

    • name

      string opcional

      Filtra os cookies por nome.

    • partitionKey

      CookiePartitionKey opcional

      Chrome 119 ou mais recente

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

    • caminho

      string opcional

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

    • seguro

      booleano opcional

      Filtra os cookies pela propriedade "Secure".

    • seção

      booleano opcional

      Filtra sessões em comparação com cookies persistentes.

    • storeId

      string opcional

      O repositório 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 correspondem ao URL informado.

  • callback

    função optional

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

Retorna

  • Promise<Cookie[]>

    Chrome 88 ou mais recente

    Promessas são compatíveis com o Manifest V3 e versões mais recentes, mas callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo que é passado para o callback.

getAllCookieStores()

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

Lista todos os armazenamentos de cookies existentes.

Parâmetros

  • callback

    função optional

    O parâmetro callback tem esta aparência: 

    (cookieStores: CookieStore[])=>void

    • cookieStores

      CookieStore[]

      Todos os cookies existentes são armazenados.

Retorna

  • Promise<CookieStore[]>

    Chrome 88 ou mais recente

    Promessas são compatíveis com o Manifest V3 e versões mais recentes, mas callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo que é passado para o callback.

remove()

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

Exclui um cookie por nome.

Parâmetros

  • detalhes

    CookieDetails

  • callback

    função optional

    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.

      • name

        string

        Nome do cookie que foi removido.

      • partitionKey

        CookiePartitionKey opcional

        Chrome 119 ou mais recente

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

      • storeId

        string

        O ID do repositório de cookies do qual o cookie foi removido.

      • url

        string

        O URL associado ao cookie que foi removido.

Retorna

  • Promise<object|undefined>

    Chrome 88 ou mais recente

    Promessas são compatíveis com o Manifest V3 e versões mais recentes, mas callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo que é passado para o callback.

set()

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

Define um cookie com os dados de cookie fornecidos. Pode substituir cookies equivalentes, se eles existirem.

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

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

    • name

      string opcional

      O nome do cookie. Vai ser vazio por padrão, se omitido.

    • partitionKey

      CookiePartitionKey opcional

      Chrome 119 ou mais recente

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

    • caminho

      string opcional

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

    • sameSite

      SameSiteStatus opcional

      Chrome 51 ou mais recente

      O status do mesmo site do cookie. O padrão é "não especificado", 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 repositório de cookies em que o cookie será definido. Por padrão, o cookie é definido no repositório de cookies do contexto de execução atual.

    • url

      string

      O URI da 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 de API vai falhar.

    • valor

      string opcional

      Valor do cookie. Vai ser vazio por padrão, se omitido.

  • callback

    função optional

    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

  • Prometer<Cookie|undefined>

    Chrome 88 ou mais recente

    Promessas são compatíveis com o Manifest V3 e versões mais recentes, mas callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo que é passado para o callback.

Eventos

onChanged

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

Disparado 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: primeiro, o cookie a ser atualizado é removido por completo, gerando uma notificação com a "causa" de "substituição" . Depois, 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 esta aparência: 

    (changeInfo: object)=>void

    • changeInfo

      objeto

      • O motivo por trás da alteração do cookie.

      • biscoito

        Cookie

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

      • removido

        boolean

        Verdadeiro se um cookie tiver sido removido.