browser.browsingData

Descrição

Use a API chrome.browsingData para remover dados de navegação do perfil local de um usuário.

Permissões

browsingData

É necessário declarar a permissão "browsingData" no manifesto da extensão para usar essa API.

{
  "name": "My extension",
  ...
  "permissions": [
    "browsingData",
  ],
  ...
}

Conceitos e uso

O caso de uso mais simples para essa API é um mecanismo baseado em tempo para limpar os dados de navegação de um usuário. Seu código precisa fornecer um carimbo de data/hora que indique a data histórica após a qual os dados de navegação do usuário devem ser removidos. Esse carimbo de data/hora é formatado como o número de milissegundos desde a época Unix, que pode ser recuperado de um objeto Date do JavaScript usando o método getTime().

Por exemplo, para limpar todos os dados de navegação de um usuário da última semana, escreva um código como este:

var callback = function () {
  // Do something clever here once data has been removed.
};

var millisecondsPerWeek = 1000 * 60 * 60 * 24 * 7;
var oneWeekAgo = (new Date()).getTime() - millisecondsPerWeek;
browser.browsingData.remove({
  "since": oneWeekAgo
}, {
  "appcache": true,
  "cache": true,
  "cacheStorage": true,
  "cookies": true,
  "downloads": true,
  "fileSystems": true,
  "formData": true,
  "history": true,
  "indexedDB": true,
  "localStorage": true,
  "passwords": true,
  "serviceWorkers": true,
  "webSQL": true
}, callback);

O método browser.browsingData.remove() permite remover vários tipos de dados de navegação com uma única chamada e é muito mais rápido do que chamar vários métodos mais específicos. No entanto, se você quiser limpar apenas um tipo específico de dados de navegação (cookies, por exemplo), os métodos mais granulares oferecem uma alternativa legível a uma chamada preenchida com JSON.

var callback = function () {
  // Do something clever here once data has been removed.
};

var millisecondsPerWeek = 1000 * 60 * 60 * 24 * 7;
var oneWeekAgo = (new Date()).getTime() - millisecondsPerWeek;
browser.browsingData.removeCookies({
  "since": oneWeekAgo
}, callback);

Se o usuário estiver sincronizando os dados, o browser.browsingData.remove() poderá recriar automaticamente o cookie para a conta de sincronização depois de limpá-lo. Isso garante que a sincronização continue funcionando para que os dados possam ser excluídos do servidor. No entanto, o browser.browsingData.removeCookies() mais específico pode ser usado para limpar o cookie da conta de sincronização, e a sincronização será pausada nesse caso.

Importante: a remoção de dados de navegação envolve um trabalho pesado em segundo plano e pode levar dezenas de segundos para ser concluída, dependendo do perfil do usuário. Use a promessa retornada ou o callback para manter os usuários atualizados sobre o status da remoção.

Origens específicas

Para remover dados de uma origem específica ou excluir um conjunto de origens da exclusão, use os parâmetros RemovalOptions.origins e RemovalOptions.excludeOrigins. Elas só podem ser aplicadas a cookies, cache e armazenamento (CacheStorage, FileSystems, IndexedDB, LocalStorage, ServiceWorkers e WebSQL).

browser.browsingData.remove({
  "origins": ["https://www.example.com"]
}, {
  "cacheStorage": true,
  "cookies": true,
  "fileSystems": true,
  "indexedDB": true,
  "localStorage": true,
  "serviceWorkers": true,
  "webSQL": true
}, callback);

Importante: como os cookies têm um escopo mais amplo do que outros tipos de armazenamento, excluir os cookies de uma origem vai excluir todos os cookies do domínio registrável. Por exemplo, excluir dados de https://www.example.com também vai excluir cookies com um domínio de .example.com.

Tipos de origem

Adicionar uma propriedade originTypes ao objeto de opções das APIs permite especificar quais tipos de origens devem ser afetados. As origens são divididas em três categorias:

• unprotectedWeb abrange o caso geral de sites que os usuários acessam sem realizar nenhuma ação especial. Se você não especificar um originTypes, a API vai remover os dados de origens da Web não protegidas por padrão.
• protectedWeb abrange as origens da Web que foram instaladas como aplicativos hospedados. Por exemplo, instalar Angry Birds protege a origem https://chrome.angrybirds.com e a remove da categoria unprotectedWeb. Tenha cuidado ao acionar a exclusão de dados dessas origens: verifique se os usuários sabem o que estão recebendo, porque isso vai remover os dados do jogo de forma irreversível. Ninguém quer derrubar casinhas de porcos mais do que o necessário.
• extension abrange origens no esquema chrome-extensions:. A remoção de dados de extensão é, novamente, algo que você deve fazer com muito cuidado.

Podemos ajustar o exemplo anterior para remover apenas dados de sites protegidos da seguinte maneira:

var callback = function () {
  // Do something clever here once data has been removed.
};

var millisecondsPerWeek = 1000 * 60 * 60 * 24 * 7;
var oneWeekAgo = (new Date()).getTime() - millisecondsPerWeek;
browser.browsingData.remove({
  "since": oneWeekAgo,
  "originTypes": {
    "protectedWeb": true
  }
}, {
  "appcache": true,
  "cache": true,
  "cacheStorage": true,
  "cookies": true,
  "downloads": true,
  "fileSystems": true,
  "formData": true,
  "history": true,
  "indexedDB": true,
  "localStorage": true,
  "passwords": true,
  "serviceWorkers": true,
  "webSQL": true
}, callback);

Aviso: tenha cuidado com os tipos de origem protectedWeb e extension. Essas são operações destrutivas que podem surpreender os usuários se eles não estiverem bem informados sobre o que esperar quando a extensão remover dados em nome deles.

Exemplos

Para testar essa API, instale o exemplo da API browsingData do repositório chrome-extension-samples.

Tipos

DataTypeSet

Um conjunto de tipos de dados. Os tipos de dados ausentes são interpretados como false.

Propriedades

• appcache

  booleano opcional

  Descontinuado desde o Chrome 152

  O suporte ao appcache foi removido. Esse tipo de dado será ignorado.

  Appcaches de sites.

• cache

  booleano opcional

  O cache do navegador.

• cacheStorage

  booleano opcional

  Chrome 72+ browser.* desde o Chrome 148

  Armazenamento em cache

• cookies

  booleano opcional

  Os cookies do navegador.

• downloads

  booleano opcional

  A lista de downloads do navegador.

• fileSystems

  booleano opcional

  Sistemas de arquivos de sites.

• formData

  booleano opcional

  Os dados de formulário armazenados do navegador.

• histórico

  booleano opcional

  O histórico do navegador.

• indexedDB

  booleano opcional

  Dados do IndexedDB dos sites.

• localStorage

  booleano opcional

  Dados de armazenamento local de sites.

• senhas

  booleano opcional

  Descontinuado desde o Chrome 144

  O suporte para exclusão de senhas por extensões foi removido. Esse tipo de dado será ignorado.

  Senhas armazenadas.

• pluginData

  booleano opcional

  Descontinuado desde o Chrome 88

  O suporte ao Flash foi removido. Esse tipo de dado será ignorado.

  Dados dos plug-ins.

• serverBoundCertificates

  booleano opcional

  Descontinuado desde o Chrome 76

  O suporte a certificados vinculados ao servidor foi removido. Esse tipo de dado será ignorado.

  Certificados vinculados ao servidor.

• serviceWorkers

  booleano opcional

  Service workers.

• webSQL

  booleano opcional

  Descontinuado desde o Chrome 152

  O suporte ao WebSQL foi removido. Esse tipo de dado será ignorado.

  Dados do WebSQL dos sites.

RemovalOptions

Opções que determinam exatamente quais dados serão removidos.

Propriedades

• excludeOrigins

  string[] opcional

  Chrome 74+ browser.* desde o Chrome 148

  Quando presentes, os dados das origens nessa lista são excluídos da exclusão. Não pode ser usado com origins. Compatível apenas com cookies, armazenamento e cache. Os cookies são excluídos de todo o domínio registrável.

• originTypes

  objeto optional

  Um objeto com propriedades que especificam quais tipos de origem precisam ser limpos. Se esse objeto não for especificado, o padrão será limpar apenas as origens "desprotegidas". Confirme se você realmente quer remover os dados do aplicativo antes de adicionar "protectedWeb" ou "extensions".

  • extensão

    booleano opcional

    Extensões e aplicativos empacotados que um usuário instalou (tenha _muito_ cuidado!).

  • protectedWeb

    booleano opcional

    Sites que foram instalados como aplicativos hospedados (tenha cuidado!).

  • unprotectedWeb

    booleano opcional

    Sites normais.

• origens

  [string, ...string[]] opcional

  Chrome 74+ browser.* desde o Chrome 148

  Quando presente, apenas os dados das origens nessa lista são excluídos. Compatível apenas com cookies, armazenamento e cache. Os cookies são apagados para todo o domínio registrável.

• desde

  número optional

  Remova os dados acumulados a partir dessa data, representados em milissegundos desde o período (acessível pelo método getTime do objeto Date do JavaScript). Se ausente, o padrão é 0 (o que removeria todos os dados de navegação).

Métodos

remove()

browser.browsingData.remove(
  options: RemovalOptions,
  dataToRemove: DataTypeSet,
): Promise<void>

Limpa vários tipos de dados de navegação armazenados no perfil de um usuário.

Parâmetros

• opções

  RemovalOptions

• dataToRemove

  DataTypeSet

  O conjunto de tipos de dados a serem removidos.

Retorna

• Promessa<void>

  Chrome 96+ browser.* desde o Chrome 148

  É resolvida quando a exclusão é concluída.

removeAppcache()

Descontinuado desde o Chrome 152

browser.browsingData.removeAppcache(
  options: RemovalOptions,
): Promise<void>

O suporte ao appcache foi removido. Essa função não tem efeito.

Limpa os dados de appcache dos sites.

Parâmetros

• opções

  RemovalOptions

Retorna

• Promessa<void>

  Chrome 96+ browser.* desde o Chrome 148

  É resolvido quando os dados do cache de apps dos sites são apagados.

removeCache()

browser.browsingData.removeCache(
  options: RemovalOptions,
): Promise<void>

Limpa o cache do navegador.

Parâmetros

• opções

  RemovalOptions

Retorna

• Promessa<void>

  Chrome 96+ browser.* desde o Chrome 148

  É resolvida quando o cache do navegador é limpo.

removeCacheStorage()

Chrome 72+ browser.* desde o Chrome 148

browser.browsingData.removeCacheStorage(
  options: RemovalOptions,
): Promise<void>

Limpa os dados de armazenamento em cache dos sites.

Parâmetros

• opções

  RemovalOptions

Retorna

• Promessa<void>

  Chrome 96+ browser.* desde o Chrome 148

  É resolvido quando o armazenamento em cache dos sites é limpo.

removeCookies()

browser.browsingData.removeCookies(
  options: RemovalOptions,
): Promise<void>

Limpa os cookies do navegador e os certificados vinculados ao servidor modificados em um determinado período.

Parâmetros

• opções

  RemovalOptions

Retorna

• Promessa<void>

  Chrome 96+ browser.* desde o Chrome 148

  É resolvido quando os cookies e os certificados vinculados ao servidor do navegador são limpos.

removeDownloads()

browser.browsingData.removeDownloads(
  options: RemovalOptions,
): Promise<void>

Limpa a lista de arquivos baixados do navegador (não os arquivos em si).

Parâmetros

• opções

  RemovalOptions

Retorna

• Promessa<void>

  Chrome 96+ browser.* desde o Chrome 148

  É resolvida quando a lista de arquivos baixados do navegador é limpa.

removeFileSystems()

browser.browsingData.removeFileSystems(
  options: RemovalOptions,
): Promise<void>

Limpa os dados do sistema de arquivos dos sites.

Parâmetros

• opções

  RemovalOptions

Retorna

• Promessa<void>

  Chrome 96+ browser.* desde o Chrome 148

  É resolvida quando os sistemas de arquivos dos sites são limpos.

removeFormData()

browser.browsingData.removeFormData(
  options: RemovalOptions,
): Promise<void>

Limpa os dados de formulário armazenados do navegador (preenchimento automático).

Parâmetros

• opções

  RemovalOptions

Retorna

• Promessa<void>

  Chrome 96+ browser.* desde o Chrome 148

  É resolvida quando os dados de formulário do navegador são limpos.

removeHistory()

browser.browsingData.removeHistory(
  options: RemovalOptions,
): Promise<void>

Limpa o histórico do navegador.

Parâmetros

• opções

  RemovalOptions

Retorna

• Promessa<void>

  Chrome 96+ browser.* desde o Chrome 148

  É resolvida quando o histórico do navegador é limpo.

removeIndexedDB()

browser.browsingData.removeIndexedDB(
  options: RemovalOptions,
): Promise<void>

Limpa os dados do IndexedDB dos sites.

Parâmetros

• opções

  RemovalOptions

Retorna

• Promessa<void>

  Chrome 96+ browser.* desde o Chrome 148

  É resolvido quando os dados do IndexedDB dos sites são apagados.

removeLocalStorage()

browser.browsingData.removeLocalStorage(
  options: RemovalOptions,
): Promise<void>

Limpa os dados de armazenamento local dos sites.

Parâmetros

• opções

  RemovalOptions

Retorna

• Promessa<void>

  Chrome 96+ browser.* desde o Chrome 148

  É resolvido quando o armazenamento local dos sites é limpo.

removePasswords()

Descontinuado desde o Chrome 144

browser.browsingData.removePasswords(
  options: RemovalOptions,
): Promise<void>

O suporte para exclusão de senhas por extensões foi removido. Essa função não tem efeito.

Limpa as senhas armazenadas do navegador.

Parâmetros

• opções

  RemovalOptions

Retorna

• Promessa<void>

  Chrome 96+ browser.* desde o Chrome 148

  É resolvida quando as senhas do navegador são apagadas.

removePluginData()

Descontinuado desde o Chrome 88

browser.browsingData.removePluginData(
  options: RemovalOptions,
): Promise<void>

O suporte ao Flash foi removido. Essa função não tem efeito.

Limpa os dados dos plug-ins.

Parâmetros

• opções

  RemovalOptions

Retorna

• Promessa<void>

  Chrome 96+ browser.* desde o Chrome 148

  É resolvida quando os dados dos plug-ins são apagados.

removeServiceWorkers()

Chrome 72+ browser.* desde o Chrome 148

browser.browsingData.removeServiceWorkers(
  options: RemovalOptions,
): Promise<void>

Limpa os service workers dos sites.

Parâmetros

• opções

  RemovalOptions

Retorna

• Promessa<void>

  Chrome 96+ browser.* desde o Chrome 148

  É resolvido quando os service workers dos sites são limpos.

removeWebSQL()

Descontinuado desde o Chrome 152

browser.browsingData.removeWebSQL(
  options: RemovalOptions,
): Promise<void>

O suporte ao WebSQL foi removido. Essa função não tem efeito.

Limpa os dados do WebSQL dos sites.

Parâmetros

• opções

  RemovalOptions

Retorna

• Promessa<void>

  Chrome 96+ browser.* desde o Chrome 148

  É resolvido quando os bancos de dados WebSQL dos sites são limpos.

settings()

browser.browsingData.settings(): Promise<object>

Informa quais tipos de dados estão selecionados na interface de configurações "Limpar dados de navegação". Observação: alguns dos tipos de dados incluídos nessa API não estão disponíveis na interface de configurações, e algumas configurações da interface controlam mais de um tipo de dados listado aqui.

Retorna

• Promise<object>

  Chrome 96+ browser.* desde o Chrome 148