Habilita extensões a obter e atribuir cookies, e ser notificado quando eles mudam.

Para usar esta API, você precisa incluir a API permission "cookies" em seu arquivo manifest.json, bem como a host permissions para os sites cujos cookies você precisa acessar. Veja cookie Permissions.

Permissões

Para usar esta API, uma extensão especificar a "cookies" API permission em seu arquivo manifest, junto com a host permissions para qualquer site que deseja acessar os cookies. O add-on pode ler ou escrever qualquer cookie no qual poderia ser lido ou escrito pela URL correspondente nas permissões de host, por exemplo:

http://*.example.com/

Uma extensão com esta permissão de host pode:

  • Ler um cookie inseguro para www.example.com, com qualquer caminho.
  • Escrever um cookie seguro ou inseguro para www.example.com, com qualquer caminho.

não pode:

  • Ler um cookie seguro de www.example.com.
http://www.example.com/

Uma extensão com esta permissão de host pode:

  • Ler um cookie não seguro para www.example.com, com qualquer caminho.
  • Ler um cookie não seguro para .example.com, com qualquer caminho.
  • Escrever um cookie seguro ou não seguro para www.example.com com qualquer caminho.
  • Escrever um cookie seguro ou não seguro para .example.com com qualquer caminho.

não pode:

  • Ler ou escrever um cookie para foo.example.com.
  • Ler ou escrever um cookie para foo.www.example.com.
*://*.example.com/

Uma extensão com esta permissão de host pode:

  • Ler ou escrever um cookie seguro ou inseguro para www.example.com com qualquer caminho.

Isolamento de primera parte

Cookies de terceiros são aquleles enviados por sites em que você está num dado momento, por exemplo:

  1. Você acessa bbc.com. Ele contém uma publicidade do tracker.com que atribui um cookie associado com o domínio "tracker.com".
  2. Você acessa cnn.com. Ele também contém uma publicidade do tracker.com que atribui um cookie associado ao domínio "tracker.com".
  3. Eventualmente ambos os cookies podem ser enviados para tracker.com. Quem então pode descobrir que o mesmo usuário visitou ambos os sites.

Quando um isolamento de primeira parte está ativo, cookies são ainda qualificados pelo domínio da página original visitada pelo usuário (essencialmente, o domínio exibe o usuário na barra da URL, também conhecido como "domínio de primeira parte). Isto significa que não é possivel para um rastreador correlacionar o cookie da bbc.com com o cookie da cnn.com, então o rastreador não pode monitorar um simples usuários através de ambos os sites.

Isolamento de primera parte pode ser habilitado diretamente pelo usuário ajustando a configuração do navegador , e pode ser atribuia do extensões usando a configuração firstPartyIsolate atribuida a API privacy. Observe que este isolamento de primeira parte está habilitado por padrão no navegador Tor.

Na API cookies, o domínio de primeira parte é representado usando o atributo firstPartyDomain. Todos os cookies atribuidos enquanto o isolamento de primeira parte está habilitado terá este atributo atribuito para o domínio da página original. No exemplo acima, deveria ser "bbc.com" para um cookie e "cnn.com" para outro. Todos os cookies atribuidos pelos websites enquanto o isolamento de primeira parte estiver desabilitado terão sua propriedade atribuida a uma string vazia.

As APIs cookies.get(), cookies.getAll(), cookies.set() and cookies.remove() aceitam a opção firstPartyDomain.

Quando o isolamento de primeira parte está habilitado, você deve informar esta opção ou a chamada da API irá falhar e retornar uma promise rejeitada. For get(), set(), and remove() you must pass a string value. Para um getAll(), você pode passar null, e irá obter todos os cookies que possuem ou não um valor não vazio para o firstPartyDomain.

Quando o isolamento de primeira parte está desabilitado, o parâmetro firstPartyDomain é opcional por padrão é uma string vazia.  Uma string não vazia pode ser utilizada para recuperar ou podificar cookies de isolamento de primeira parte.  Da mesma forma, passando null como firstPartyDomain para o getAll() retornará todos os cookies.

Tipos

cookies.Cookie
Representa a informação sobre um cookie HTTP.
cookies.CookieStore
Representa um cookie armazenado no navegador.
cookies.OnChangedCause
Representa o motivo da mudança de um cookie.

Métodos

cookies.get()
Recupera informações sobre um único cookie.
cookies.getAll()
Recupera todos os cookies com o padrão de um conjunto de filtros fornecido.
cookies.set()
Atribui um cookie com um dado fornecido; pode sobrescrever cookies equivalentes caso existam.
cookies.remove()
Remove um cookie pelo nome.
cookies.getAllCookieStores()
Lista todos os cookies armazenados.

Manipulador de eventos

cookies.onChanged
Disparado quando um cookie é criado ou removido.

Compatibilidade de navegadores

ChromeEdgeFirefoxFirefox for AndroidOpera
Cookie Yes144548 Yes
CookieStore Yes144548 Yes
OnChangedCause Yes No4548 Yes
get Yes1445 *48 Yes
getAll Yes14 *45 *48 Yes
getAllCookieStores Yes14 *45 *48 Yes
onChanged Yes No4548 Yes
remove Yes1445 *48 * Yes
set Yes1445 *48 * Yes

Example extensions

Agradecimentos

Esta API é baseada na API chrome.cookies do Chromium. Esta documentação é derivada do cookies.json no código do Chromium.

Etiquetas do documento e colaboradores

Colaboradores desta página: thiagopelizoni
Última atualização por: thiagopelizoni,