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

Update compatibility data on GitHub
DesktopMobile
ChromeEdgeFirefoxOperaFirefox for Android
CookieChrome Full support YesEdge Full support 14Firefox Full support 45Opera Full support YesFirefox Android Full support 48
CookieStoreChrome Full support YesEdge Full support 14Firefox Full support 45Opera Full support YesFirefox Android Full support 48
OnChangedCauseChrome Full support YesEdge No support NoFirefox Full support 45Opera Full support YesFirefox Android Full support 48
getChrome Full support YesEdge Full support 14Firefox Full support 45
Notes
Full support 45
Notes
Notes Provides access to cookies from private browsing mode and container tabs since version 52.
Opera Full support YesFirefox Android Full support 48
getAllChrome Full support YesEdge Full support 14
Notes
Full support 14
Notes
Notes If no URL is provided, cookies are retrieved only for URLs in currently opened tabs. In Chrome, this gets all cookies on a user's machine.
Firefox Full support 45
Notes
Full support 45
Notes
Notes Before version 52, the 'tabIds' list was empty and only cookies from the default cookie store were returned. From version 52 onwards, this has been fixed and the result includes cookies from private browsing mode and container tabs.
Opera Full support YesFirefox Android Full support 48
getAllCookieStoresChrome Full support YesEdge Full support 14
Notes
Full support 14
Notes
Notes Always returns the same default cookie store with ID 0. All cookies belong to this store.
Firefox Full support 45
Notes
Full support 45
Notes
Notes Before version 52, only the default cookie store was visible. From version 52 onwards, the cookie stores for private browsing mode and container tabs are also readable.
Opera Full support YesFirefox Android Full support 48
onChangedChrome Full support YesEdge No support NoFirefox Full support 45Opera Full support YesFirefox Android Full support 48
removeChrome Full support YesEdge Full support 14Firefox Full support 45
Notes
Full support 45
Notes
Notes Before version 56, this function did not remove cookies from private browsing mode. From version 56 onwards this is fixed.
Opera Full support YesFirefox Android Full support 48
Notes
Full support 48
Notes
Notes Before version 56, this function did not remove cookies from private browsing mode. From version 56 onwards this is fixed.
setChrome Full support YesEdge Full support 14Firefox Full support 45
Notes
Full support 45
Notes
Notes Before version 56, this function did not modify cookies in private browsing mode. From version 56 onwards this is fixed.
Opera Full support YesFirefox Android Full support 48
Notes
Full support 48
Notes
Notes Before version 56, this function did not modify cookies in private browsing mode. From version 56 onwards this is fixed.

Legend

Full support  
Full support
No support  
No support
See implementation notes.
See implementation notes.

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,