Description
Use the chrome.browsingData
API to remove browsing data from a user's local profile.
Permissions
browsingData
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 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 originhttps://chrome.angrybirds.com
, and removes it from theunprotectedWeb
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 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,
"passwords": true,
"serviceWorkers": true,
"webSQL": true
}, callback);
Examples
To try this API, install the browsingData API example from the chrome-extension-samples repository.
Types
DataTypeSet
A set of data types. Missing data types are interpreted as false
.
Properties
-
appcache
boolean optional
Websites' appcaches.
-
cache
boolean optional
The browser's cache.
-
cacheStorage
boolean optional
Chrome 72+Cache storage
-
cookies
boolean optional
The browser's cookies.
-
downloads
boolean optional
The browser's download list.
-
fileSystems
boolean optional
Websites' file systems.
-
formData
boolean optional
The browser's stored form data.
-
history
boolean optional
The browser's history.
-
indexedDB
boolean optional
Websites' IndexedDB data.
-
localStorage
boolean optional
Websites' local storage data.
-
passwords
boolean optional
Stored passwords.
-
pluginData
boolean optional
Deprecated since Chrome 88Support for Flash has been removed. This data type will be ignored.
Plugins' data.
-
serverBoundCertificates
boolean optional
Deprecated since Chrome 76Support for server-bound certificates has been removed. This data type will be ignored.
Server-bound certificates.
-
serviceWorkers
boolean optional
Service Workers.
-
webSQL
boolean optional
Websites' WebSQL data.
RemovalOptions
Options that determine exactly what data will be removed.
Properties
-
excludeOrigins
string[] optional
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. -
originTypes
object optional
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'.
-
extension
boolean optional
Extensions and packaged applications a user has installed (be _really_ careful!).
-
protectedWeb
boolean optional
Websites that have been installed as hosted applications (be careful!).
-
unprotectedWeb
boolean optional
Normal websites.
-
-
origins
[string, ...string[]] optional
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.
-
since
number optional
Remove data accumulated on or after this date, represented in milliseconds since the epoch (accessible via the
getTime
method of the JavaScriptDate
object). If absent, defaults to 0 (which would remove all browsing data).
Methods
remove()
chrome.browsingData.remove(
options: RemovalOptions,
dataToRemove: DataTypeSet,
callback?: function,
)
Clears various types of browsing data stored in a user's profile.
Parameters
-
options
-
dataToRemove
The set of data types to remove.
-
callback
function optional
The
callback
parameter looks like:() => void
Returns
-
Promise<void>
Chrome 96+Promises are supported in Manifest V3 and later, but callbacks are provided for backward compatibility. You cannot use both on the same function call. The promise resolves with the same type that is passed to the callback.
removeAppcache()
chrome.browsingData.removeAppcache(
options: RemovalOptions,
callback?: function,
)
Clears websites' appcache data.
Parameters
-
options
-
callback
function optional
The
callback
parameter looks like:() => void
Returns
-
Promise<void>
Chrome 96+Promises are supported in Manifest V3 and later, but callbacks are provided for backward compatibility. You cannot use both on the same function call. The promise resolves with the same type that is passed to the callback.
removeCache()
chrome.browsingData.removeCache(
options: RemovalOptions,
callback?: function,
)
Clears the browser's cache.
Parameters
-
options
-
callback
function optional
The
callback
parameter looks like:() => void
Returns
-
Promise<void>
Chrome 96+Promises are supported in Manifest V3 and later, but callbacks are provided for backward compatibility. You cannot use both on the same function call. The promise resolves with the same type that is passed to the callback.
removeCacheStorage()
chrome.browsingData.removeCacheStorage(
options: RemovalOptions,
callback?: function,
)
Clears websites' cache storage data.
Parameters
-
options
-
callback
function optional
The
callback
parameter looks like:() => void
Returns
-
Promise<void>
Chrome 96+Promises are supported in Manifest V3 and later, but callbacks are provided for backward compatibility. You cannot use both on the same function call. The promise resolves with the same type that is passed to the callback.
removeCookies()
chrome.browsingData.removeCookies(
options: RemovalOptions,
callback?: function,
)
Clears the browser's cookies and server-bound certificates modified within a particular timeframe.
Parameters
-
options
-
callback
function optional
The
callback
parameter looks like:() => void
Returns
-
Promise<void>
Chrome 96+Promises are supported in Manifest V3 and later, but callbacks are provided for backward compatibility. You cannot use both on the same function call. The promise resolves with the same type that is passed to the callback.
removeDownloads()
chrome.browsingData.removeDownloads(
options: RemovalOptions,
callback?: function,
)
Clears the browser's list of downloaded files (not the downloaded files themselves).
Parameters
-
options
-
callback
function optional
The
callback
parameter looks like:() => void
Returns
-
Promise<void>
Chrome 96+Promises are supported in Manifest V3 and later, but callbacks are provided for backward compatibility. You cannot use both on the same function call. The promise resolves with the same type that is passed to the callback.
removeFileSystems()
chrome.browsingData.removeFileSystems(
options: RemovalOptions,
callback?: function,
)
Clears websites' file system data.
Parameters
-
options
-
callback
function optional
The
callback
parameter looks like:() => void
Returns
-
Promise<void>
Chrome 96+Promises are supported in Manifest V3 and later, but callbacks are provided for backward compatibility. You cannot use both on the same function call. The promise resolves with the same type that is passed to the callback.
removeFormData()
chrome.browsingData.removeFormData(
options: RemovalOptions,
callback?: function,
)
Clears the browser's stored form data (autofill).
Parameters
-
options
-
callback
function optional
The
callback
parameter looks like:() => void
Returns
-
Promise<void>
Chrome 96+Promises are supported in Manifest V3 and later, but callbacks are provided for backward compatibility. You cannot use both on the same function call. The promise resolves with the same type that is passed to the callback.
removeHistory()
chrome.browsingData.removeHistory(
options: RemovalOptions,
callback?: function,
)
Clears the browser's history.
Parameters
-
options
-
callback
function optional
The
callback
parameter looks like:() => void
Returns
-
Promise<void>
Chrome 96+Promises are supported in Manifest V3 and later, but callbacks are provided for backward compatibility. You cannot use both on the same function call. The promise resolves with the same type that is passed to the callback.
removeIndexedDB()
chrome.browsingData.removeIndexedDB(
options: RemovalOptions,
callback?: function,
)
Clears websites' IndexedDB data.
Parameters
-
options
-
callback
function optional
The
callback
parameter looks like:() => void
Returns
-
Promise<void>
Chrome 96+Promises are supported in Manifest V3 and later, but callbacks are provided for backward compatibility. You cannot use both on the same function call. The promise resolves with the same type that is passed to the callback.
removeLocalStorage()
chrome.browsingData.removeLocalStorage(
options: RemovalOptions,
callback?: function,
)
Clears websites' local storage data.
Parameters
-
options
-
callback
function optional
The
callback
parameter looks like:() => void
Returns
-
Promise<void>
Chrome 96+Promises are supported in Manifest V3 and later, but callbacks are provided for backward compatibility. You cannot use both on the same function call. The promise resolves with the same type that is passed to the callback.
removePasswords()
chrome.browsingData.removePasswords(
options: RemovalOptions,
callback?: function,
)
Clears the browser's stored passwords.
Parameters
-
options
-
callback
function optional
The
callback
parameter looks like:() => void
Returns
-
Promise<void>
Chrome 96+Promises are supported in Manifest V3 and later, but callbacks are provided for backward compatibility. You cannot use both on the same function call. The promise resolves with the same type that is passed to the callback.
removePluginData()
chrome.browsingData.removePluginData(
options: RemovalOptions,
callback?: function,
)
Support for Flash has been removed. This function has no effect.
Clears plugins' data.
Parameters
-
options
-
callback
function optional
The
callback
parameter looks like:() => void
Returns
-
Promise<void>
Chrome 96+Promises are supported in Manifest V3 and later, but callbacks are provided for backward compatibility. You cannot use both on the same function call. The promise resolves with the same type that is passed to the callback.
removeServiceWorkers()
chrome.browsingData.removeServiceWorkers(
options: RemovalOptions,
callback?: function,
)
Clears websites' service workers.
Parameters
-
options
-
callback
function optional
The
callback
parameter looks like:() => void
Returns
-
Promise<void>
Chrome 96+Promises are supported in Manifest V3 and later, but callbacks are provided for backward compatibility. You cannot use both on the same function call. The promise resolves with the same type that is passed to the callback.
removeWebSQL()
chrome.browsingData.removeWebSQL(
options: RemovalOptions,
callback?: function,
)
Clears websites' WebSQL data.
Parameters
-
options
-
callback
function optional
The
callback
parameter looks like:() => void
Returns
-
Promise<void>
Chrome 96+Promises are supported in Manifest V3 and later, but callbacks are provided for backward compatibility. You cannot use both on the same function call. The promise resolves with the same type that is passed to the callback.
settings()
chrome.browsingData.settings(
callback?: function,
)
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
-
callback
function optional
The
callback
parameter looks like:(result: object) => void
-
result
object
-
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) andfalse
if not. -
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, otherwisefalse
. -
options
-
-
Returns
-
Promise<object>
Chrome 96+Promises are supported in Manifest V3 and later, but callbacks are provided for backward compatibility. You cannot use both on the same function call. The promise resolves with the same type that is passed to the callback.