chrome.browsingData

Description: Use the chrome.browsingData API to remove browsing data from a user's local profile.
Availability: Since Chrome 35.
Permissions: "browsingData"

Manifest

You must declare the "browsingData" permission in the extension manifest to use this API.

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

Usage

The simplest use-case for this API is a a time-based mechanism for clearing a user's browsing data. Your code should provide a timestamp which indicates the historical date after which the user's browsing data should be removed. This timestamp is formatted as the number of milliseconds since the Unix epoch (which can be retrieved from a JavaScript Date object via the getTime method).

For example, to clear all of a user's browsing data from the last week, you might write code as follows:

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;
      chrome.browsingData.remove({
        "since": oneWeekAgo
      }, {
        "appcache": true,
        "cache": true,
        "cacheStorage": true,
        "cookies": true,
        "downloads": true,
        "fileSystems": true,
        "formData": true,
        "history": true,
        "indexedDB": true,
        "localStorage": true,
        "pluginData": true,
        "passwords": true,
        "serviceWorkers": true,
        "webSQL": true
      }, callback);

The chrome.browsingData.remove method allows you to remove various types of browsing data with a single call, and will be much faster than calling multiple more specific methods. If, however, you only want to clear one specific type of browsing data (cookies, for example), the more granular methods offer a readable alternative to a call filled with 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;
      chrome.browsingData.removeCookies({
        "since": oneWeekAgo
      }, callback);

If the user is syncing their data, chrome.browsingData.remove may automatically rebuild the cookie for the Sync account after clearing it. This is to ensure that Sync can continue working, so that the data can be eventually deleted on the server. However the more specific chrome.browsingData.removeCookies can be used to clear the cookie for the Sync account, and Sync will be paused in this case.

Important: Removing browsing data involves a good deal of heavy lifting in the background, and can take tens of seconds to complete, depending on a user's profile. You should use the callback mechanism to keep your users up to date on the removal's status.

Specific Origins

To remove data for a specific origin or to exclude a set of origins from deletion, you can use the RemovalOptions.origins and RemovalOptions.excludeOrigins parameters. They can only be applied to cookies, cache, and storage (CacheStorage, FileSystems, IndexedDB, LocalStorage, PluginData, ServiceWorkers, and WebSQL).

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

Important: As cookies are scoped more broadly than other types of storage, deleting cookies for an origin will delete all cookies of the registrable domain. For example, deleting data for https://www.example.com will delete cookies with a domain of .example.com as well.

Origin Types

Adding an originTypes property to the API's options object allows you to specify which types of origins ought to be effected. Currently, origins are divided into three categories:

  • unprotectedWeb covers the general case of websites that users visit without taking any special action. If you don't specify an originTypes, the API defaults to removing data from unprotected web origins.
  • protectedWeb covers those web origins that have been installed as hosted applications. Installing Angry Birds, for example, protects the origin http://chrome.angrybirds.com, and removes it from the unprotectedWeb category. Please do be careful when triggering deletion of data for these origins: make sure your users know what they're getting, as this will irrevocably remove their game data. No one wants to knock tiny pig houses over more often than necessary.
  • extension covers origins under the chrome-extensions: scheme. Removing extension data is, again, something you should be very careful about.

We could adjust the previous example to remove only data from protected websites as follows:

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;
      chrome.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,
        "serverBoundCertificates": true,
        "pluginData": true,
        "passwords": true,
        "serviceWorkers": true,
        "webSQL": true
      }, callback);

Seriously: Be careful with protectedWeb and extension. These are destructive operations that your users will write angry email about if they're not well-informed about what to expect when your extension removes data on their behalf.

Examples

Samples for the browsingData API are available on the samples page.

Summary

Types
RemovalOptions
DataTypeSet
Methods
settings chrome.browsingData.settings(function callback)
remove chrome.browsingData.remove( RemovalOptions options, DataTypeSet dataToRemove, function callback)
removeAppcache chrome.browsingData.removeAppcache( RemovalOptions options, function callback)
removeCache chrome.browsingData.removeCache( RemovalOptions options, function callback)
removeCacheStorage chrome.browsingData.removeCacheStorage( RemovalOptions options, function callback)
removeCookies chrome.browsingData.removeCookies( RemovalOptions options, function callback)
removeDownloads chrome.browsingData.removeDownloads( RemovalOptions options, function callback)
removeFileSystems chrome.browsingData.removeFileSystems( RemovalOptions options, function callback)
removeFormData chrome.browsingData.removeFormData( RemovalOptions options, function callback)
removeHistory chrome.browsingData.removeHistory( RemovalOptions options, function callback)
removeIndexedDB chrome.browsingData.removeIndexedDB( RemovalOptions options, function callback)
removeLocalStorage chrome.browsingData.removeLocalStorage( RemovalOptions options, function callback)
removePluginData chrome.browsingData.removePluginData( RemovalOptions options, function callback)
removePasswords chrome.browsingData.removePasswords( RemovalOptions options, function callback)
removeServiceWorkers chrome.browsingData.removeServiceWorkers( RemovalOptions options, function callback)
removeWebSQL chrome.browsingData.removeWebSQL( RemovalOptions options, function callback)

Types

RemovalOptions

Options that determine exactly what data will be removed.
properties
double (optional) since

Remove data accumulated on or after this date, represented in milliseconds since the epoch (accessible via the getTime method of the JavaScript Date object). If absent, defaults to 0 (which would remove all browsing data).

object (optional) originTypes

An object whose properties specify which origin types ought to be cleared. If this object isn't specified, it defaults to clearing only "unprotected" origins. Please ensure that you really want to remove application data before adding 'protectedWeb' or 'extensions'.

boolean (optional) unprotectedWeb

Normal websites.

boolean (optional) protectedWeb

Websites that have been installed as hosted applications (be careful!).

boolean (optional) extension

Extensions and packaged applications a user has installed (be _really_ careful!).

array of string (optional) origins

Since Chrome 74.

When present, only data for origins in this list is deleted. Only supported for cookies, storage and cache. Cookies are cleared for the whole registrable domain.

array of string (optional) excludeOrigins

Since Chrome 74.

When present, data for origins in this list is excluded from deletion. Can't be used together with origins. Only supported for cookies, storage and cache. Cookies are excluded for the whole registrable domain.

DataTypeSet

A set of data types. Missing data types are interpreted as false.
properties
boolean (optional) appcache

Websites' appcaches.

boolean (optional) cache

The browser's cache.

boolean (optional) cacheStorage

Since Chrome 72.

Cache storage

boolean (optional) cookies

The browser's cookies.

boolean (optional) downloads

The browser's download list.

boolean (optional) fileSystems

Websites' file systems.

boolean (optional) formData

The browser's stored form data.

boolean (optional) history

The browser's history.

boolean (optional) indexedDB

Websites' IndexedDB data.

boolean (optional) localStorage

Websites' local storage data.

boolean (optional) serverBoundCertificates

Deprecated since Chrome 76. Support for server-bound certificates has been removed. This data type will be ignored.

Server-bound certificates.

boolean (optional) passwords

Stored passwords.

boolean (optional) pluginData

Plugins' data.

boolean (optional) serviceWorkers

Since Chrome 39.

Service Workers.

boolean (optional) webSQL

Websites' WebSQL data.

Methods

settings

chrome.browsingData.settings(function callback)

Reports which types of data are currently selected in the 'Clear browsing data' settings UI. Note: some of the data types included in this API are not available in the settings UI, and some UI settings control more than one data type listed here.

Parameters
function callback

The callback parameter should be a function that looks like this:

function(object result) {...};
object result
RemovalOptions options
DataTypeSet dataToRemove

All of the types will be present in the result, with values of true if they are both selected to be removed and permitted to be removed, otherwise false.

DataTypeSet dataRemovalPermitted

All of the types will be present in the result, with values of true if they are permitted to be removed (e.g., by enterprise policy) and false if not.

remove

chrome.browsingData.remove( RemovalOptions options, DataTypeSet dataToRemove, function callback)

Clears various types of browsing data stored in a user's profile.

Parameters
RemovalOptions options
DataTypeSet dataToRemove

The set of data types to remove.

function (optional) callback

Called when deletion has completed.

If you specify the callback parameter, it should be a function that looks like this:

function() {...};

removeAppcache

chrome.browsingData.removeAppcache( RemovalOptions options, function callback)

Clears websites' appcache data.

Parameters
RemovalOptions options
function (optional) callback

Called when websites' appcache data has been cleared.

If you specify the callback parameter, it should be a function that looks like this:

function() {...};

removeCache

chrome.browsingData.removeCache( RemovalOptions options, function callback)

Clears the browser's cache.

Parameters
RemovalOptions options
function (optional) callback

Called when the browser's cache has been cleared.

If you specify the callback parameter, it should be a function that looks like this:

function() {...};

removeCacheStorage

chrome.browsingData.removeCacheStorage( RemovalOptions options, function callback)

Since Chrome 72.

Clears websites' cache storage data.

Parameters
RemovalOptions options
function (optional) callback

Called when websites' cache storage has been cleared.

If you specify the callback parameter, it should be a function that looks like this:

function() {...};

removeCookies

chrome.browsingData.removeCookies( RemovalOptions options, function callback)

Clears the browser's cookies and server-bound certificates modified within a particular timeframe.

Parameters
RemovalOptions options
function (optional) callback

Called when the browser's cookies and server-bound certificates have been cleared.

If you specify the callback parameter, it should be a function that looks like this:

function() {...};

removeDownloads

chrome.browsingData.removeDownloads( RemovalOptions options, function callback)

Clears the browser's list of downloaded files (not the downloaded files themselves).

Parameters
RemovalOptions options
function (optional) callback

Called when the browser's list of downloaded files has been cleared.

If you specify the callback parameter, it should be a function that looks like this:

function() {...};

removeFileSystems

chrome.browsingData.removeFileSystems( RemovalOptions options, function callback)

Clears websites' file system data.

Parameters
RemovalOptions options
function (optional) callback

Called when websites' file systems have been cleared.

If you specify the callback parameter, it should be a function that looks like this:

function() {...};

removeFormData

chrome.browsingData.removeFormData( RemovalOptions options, function callback)

Clears the browser's stored form data (autofill).

Parameters
RemovalOptions options
function (optional) callback

Called when the browser's form data has been cleared.

If you specify the callback parameter, it should be a function that looks like this:

function() {...};

removeHistory

chrome.browsingData.removeHistory( RemovalOptions options, function callback)

Clears the browser's history.

Parameters
RemovalOptions options
function (optional) callback

Called when the browser's history has cleared.

If you specify the callback parameter, it should be a function that looks like this:

function() {...};

removeIndexedDB

chrome.browsingData.removeIndexedDB( RemovalOptions options, function callback)

Clears websites' IndexedDB data.

Parameters
RemovalOptions options
function (optional) callback

Called when websites' IndexedDB data has been cleared.

If you specify the callback parameter, it should be a function that looks like this:

function() {...};

removeLocalStorage

chrome.browsingData.removeLocalStorage( RemovalOptions options, function callback)

Clears websites' local storage data.

Parameters
RemovalOptions options
function (optional) callback

Called when websites' local storage has been cleared.

If you specify the callback parameter, it should be a function that looks like this:

function() {...};

removePluginData

chrome.browsingData.removePluginData( RemovalOptions options, function callback)

Clears plugins' data.

Parameters
RemovalOptions options
function (optional) callback

Called when plugins' data has been cleared.

If you specify the callback parameter, it should be a function that looks like this:

function() {...};

removePasswords

chrome.browsingData.removePasswords( RemovalOptions options, function callback)

Clears the browser's stored passwords.

Parameters
RemovalOptions options
function (optional) callback

Called when the browser's passwords have been cleared.

If you specify the callback parameter, it should be a function that looks like this:

function() {...};

removeServiceWorkers

chrome.browsingData.removeServiceWorkers( RemovalOptions options, function callback)

Since Chrome 72.

Clears websites' service workers.

Parameters
RemovalOptions options
function (optional) callback

Called when websites' service workers have been cleared.

If you specify the callback parameter, it should be a function that looks like this:

function() {...};

removeWebSQL

chrome.browsingData.removeWebSQL( RemovalOptions options, function callback)

Clears websites' WebSQL data.

Parameters
RemovalOptions options
function (optional) callback

Called when websites' WebSQL databases have been cleared.

If you specify the callback parameter, it should be a function that looks like this:

function() {...};