chrome.browsingData

Description

Permissions

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

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

Concepts and 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 using 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,
  "passwords": true,
  "serviceWorkers": true,
  "webSQL": true
}, callback);

The chrome.browsingData.remove() method lets you 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.

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, ServiceWorkers, and WebSQL).

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

Origin types

Adding an originTypes property to the APIs options object lets you specify which types of origins ought to be effected. 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 https://chrome.angrybirds.com, and removes it from the unprotectedWeb category. 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,
  "passwords": true,
  "serviceWorkers": true,
  "webSQL": true
}, callback);

Examples

To try this API, install the browsingData API example from the chrome-extension-samples repository.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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