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 anoriginTypes
, 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 originhttp://chrome.angrybirds.com
, and removes it from theunprotectedWeb
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 thechrome-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
properties | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
double | (optional) since |
Remove data accumulated on or after this date, represented in milliseconds since the epoch (accessible via the |
|||||||||
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'.
|
|||||||||
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 |
DataTypeSet
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) {...};
|
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() {...};
|