chrome.history
Use the chrome.history module to interact with the
browser's record of visited pages. You can add, remove, and query
for URLs in the browser's history.
To override the history page with your own version, see
Override Pages.
Manifest
You must declare the "history" permission
in the extension manifest
to use the history API.
For example:
{
"name": "My extension",
...
"permissions": [
"history"
],
...
}
Transition types
The history API uses a transition type to describe
how the browser navigated to a particular URL
on a particular visit.
For example, if a user visits a page
by clicking a link on another page,
the transition type is "link".
The following table describes each transition type.
| Transition type | Description |
| "link" |
The user got to this page by clicking a link on another page.
|
| "typed" |
The user got this page by typing the URL in the address bar.
Also used for other explicit navigation actions.
See also generated,
which is used for cases where the user selected a choice
that didn't look at all like a URL.
|
| "auto_bookmark" |
The user got to this page through a suggestion in the UI —
for example, through a menu item.
|
| "auto_subframe" |
Subframe navigation.
This is any content that is automatically
loaded in a non-top-level frame.
For example, if a page consists of
several frames containing ads,
those ad URLs have this transition type.
The user may not even realize the content in these pages
is a separate frame, and so may not care about the URL
(see also manual_subframe).
|
| "manual_subframe" |
For subframe navigations that are explicitly requested by the user
and generate new navigation entries in the back/forward list.
An explicitly requested frame is probably more important than
an automatically loaded frame
because the user probably cares about the fact that
the requested frame was loaded.
|
| "generated" |
The user got to this page by typing in the address bar
and selecting an entry that did not look like a URL.
For example, a match might have the URL of a Google search result page,
but it might appear to the user as "Search Google for ...".
These are not quite the same as typed navigations
because the user didn't type or see the destination URL.
See also keyword.
|
| "start_page" |
The page was specified in the command line or is the start page.
|
| "form_submit" |
The user filled out values in a form and submitted it.
Note that in some situations —
such as when a form uses script to submit contents —
submitting a form does not result in this transition type.
|
| "reload" |
The user reloaded the page,
either by clicking the reload button
or by pressing Enter in the address bar.
Session restore and Reopen closed tab use this transition type, too.
|
| "keyword" |
The URL was generated from a replaceable keyword
other than the default search provider.
See also
keyword_generated.
|
| "keyword_generated" |
Corresponds to a visit generated for a keyword.
See also keyword.
|
Examples
For examples of using this API, see the
history sample directory and the
history API test directory.
For other examples and for help in viewing the source code, see
Samples.
API Reference: chrome.history
Types
HistoryItem
( object )
An object encapsulating one result of a history query.
-
id
(
string
)
-
The unique identifier for the item.
-
url
(
optional
string
)
-
The URL navigated to by a user.
-
title
(
optional
string
)
-
The title of the page when it was last loaded.
-
lastVisitTime
(
optional
double
)
-
When this page was last loaded, represented in milliseconds since the epoch.
-
visitCount
(
optional
integer
)
-
The number of times the user has navigated to this page.
-
typedCount
(
optional
integer
)
-
The number of times the user has navigated to this page by typing in the address.
VisitItem
( object )
An object encapsulating one visit to a URL.
-
id
(
string
)
-
The unique identifier for the item.
-
visitId
(
string
)
-
The unique identifier for this visit.
-
visitTime
(
optional
double
)
-
When this visit occurred, represented in milliseconds since the epoch.
-
referringVisitId
(
string
)
-
The visit ID of the referrer.
-
transition
(
enumerated string ["link", "typed", "auto_bookmark", "auto_subframe", "manual_subframe", "generated", "auto_toplevel", "form_submit", "reload", "keyword", "keyword_generated"]
)
-
The transition type for this visit from its referrer.
Methods
search
chrome.history.search(object query, function callback)
Searches the history for the last visit time of each page matching the query.
Parameters
- query ( object )
-
- text ( string )
- A free-text query to the history service. Leave empty to retrieve all pages.
- startTime ( optional double )
- Limit results to those visited after this date, represented in milliseconds since the epoch.
- endTime ( optional double )
- Limit results to those visited before this date, represented in milliseconds since the epoch.
- maxResults ( optional integer )
- The maximum number of results to retrieve. Defaults to 100.
Callback function
The callback parameter should specify a function that looks like this:
function(array of HistoryItem results) {...};
getVisits
chrome.history.getVisits(object details, function callback)
Retrieves information about visits to a URL.
Parameters
- details ( object )
-
- url ( string )
- The URL for which to retrieve visit information. It must be in the format as returned from a call to history.search.
Callback function
The callback parameter should specify a function that looks like this:
function(array of VisitItem results) {...};
addUrl
chrome.history.addUrl(object details, function callback)
Adds a URL to the history at the current time with a transition type of "link".
Parameters
- details ( object )
-
- url ( string )
- The URL to add.
- callback ( optional function )
Callback function
If you specify the callback parameter, it should specify a function that looks like this:
function() {...};
deleteUrl
chrome.history.deleteUrl(object details, function callback)
Removes all occurrences of the given URL from the history.
Parameters
- details ( object )
-
- url ( string )
- The URL to remove.
- callback ( optional function )
Callback function
If you specify the callback parameter, it should specify a function that looks like this:
function() {...};
deleteRange
chrome.history.deleteRange(object range, function callback)
Removes all items within the specified date range from the history. Pages will not be removed from the history unless all visits fall within the range.
Parameters
- range ( object )
-
- startTime ( double )
- Items added to history after this date, represented in milliseconds since the epoch.
- endTime ( double )
- Items added to history before this date, represented in milliseconds since the epoch.
Callback function
The callback parameter should specify a function that looks like this:
function() {...};
deleteAll
chrome.history.deleteAll(function callback)
Deletes all items from the history.
Parameters
Callback function
The callback parameter should specify a function that looks like this:
function() {...};
Events
onVisited
chrome.history.onVisited
.addListener(function(
HistoryItem result)
{...});
Fired when a URL is visited, providing the HistoryItem data for that URL. This event fires before the page has loaded.
Listener Parameters
onVisitRemoved
chrome.history.onVisitRemoved.addListener(function(object removed) {...});
Fired when one or more URLs are removed from the history service. When all visits have been removed the URL is purged from history.
Listener Parameters
- removed ( object )
-
- allHistory ( boolean )
- True if all history was removed. If true, then urls will be empty.
- urls ( optional array of string )
Sample Extensions that use chrome.history
Typed URL History –
Reads your history, and shows the top ten pages you go to by typing the URL.
