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 de cookies, é necessário declarar a permissão "cookies" no manifesto, além das 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 codificados 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 deles.
chrome.cookies
não oferece suporte ao particionamento, o que significa que todos os métodos leem e gravam cookies de todas as partições. O método cookies.set()
armazena cookies na partição padrão.
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
Cookie
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).
-
nome
string
O nome do cookie.
-
partitionKey
CookiePartitionKey opcional
Chrome 119 ou mais recenteA chave de partição para ler ou modificar cookies com o atributo "Particionado".
-
caminho
string
Caminho do cookie.
-
sameSiteChrome 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
Detalhes para identificar o cookie.
Propriedades
-
nome
string
Nome do cookie a ser acessado.
-
partitionKey
CookiePartitionKey opcional
Chrome 119 ou mais recenteA 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
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
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
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()
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
Retorna
-
Promise<Cookie | undefined>
Chrome 88 ou mais recentePromessas são compatíveis apenas com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.
getAll()
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.
-
nome
string opcional
Filtra os cookies por nome.
-
partitionKey
CookiePartitionKey opcional
Chrome 119 ou mais recenteA 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 recentePromessas são compatíveis apenas com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.
getAllCookieStores()
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
Todos os cookies existentes são armazenados.
-
Retorna
-
Promise<CookieStore[]>
Chrome 88 ou mais recentePromessas são compatíveis apenas com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.
remove()
chrome.cookies.remove(
details: CookieDetails,
callback?: function,
)
Exclui um cookie por nome.
Parâmetros
-
detalhes
-
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.-
nome
string
Nome do cookie que foi removido.
-
partitionKey
CookiePartitionKey opcional
Chrome 119 ou mais recenteA 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 recentePromessas são compatíveis apenas com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.
set()
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".
-
nome
string opcional
O nome do cookie. Vai ser vazio por padrão, se omitido.
-
partitionKey
CookiePartitionKey opcional
Chrome 119 ou mais recenteA 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 recenteO 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
-
Promise<Cookie | undefined>
Chrome 88 ou mais recentePromessas são compatíveis apenas com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.
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
-
cause
O motivo por trás da alteração do cookie.
-
biscoito
Informações sobre o cookie que foi definido ou removido.
-
removida
boolean
Verdadeiro se um cookie tiver sido removido.
-
-