chrome.webNavigation

Description: Use the chrome.webNavigation API to receive notifications about the status of navigation requests in-flight.
Availability: Since Chrome 35.
Permissions: "webNavigation"

Manifest

All chrome.webNavigation methods and events require you to declare the "webNavigation" permission in the extension manifest. For example: 

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

Examples

You can find simple examples of using the tabs module in the examples/api/webNavigation directory. For other examples and for help in viewing the source code, see Samples.

Event order

For a navigation that is successfully completed, events are fired in the following order: 

      onBeforeNavigate -> onCommitted -> onDOMContentLoaded -> onCompleted

Any error that occurs during the process results in an onErrorOccurred event. For a specific navigation, there are no further events fired after onErrorOccurred.

If a navigating frame contains subframes, its onCommitted is fired before any of its children's onBeforeNavigate; while onCompleted is fired after all of its children's onCompleted.

If the reference fragment of a frame is changed, a onReferenceFragmentUpdated event is fired. This event can fire any time after onDOMContentLoaded, even after onCompleted.

If the history API is used to modify the state of a frame (e.g. using history.pushState(), a onHistoryStateUpdated event is fired. This event can fire any time after onDOMContentLoaded.

If a navigation was triggered via Chrome Instant or Instant Pages, a completely loaded page is swapped into the current tab. In that case, an onTabReplaced event is fired.

Relation to webRequest events

There is no defined ordering between events of the webRequest API and the events of the webNavigation API. It is possible that webRequest events are still received for frames that already started a new navigation, or that a navigation only proceeds after the network resources are already fully loaded.

In general, the webNavigation events are closely related to the navigation state that is displayed in the UI, while the webRequest events correspond to the state of the network stack which is generally opaque to the user.

A note about tab IDs

Not all navigating tabs correspond to actual tabs in Chrome's UI, e.g., a tab that is being pre-rendered. Such tabs are not accessible via the tabs API nor can you request information about them via webNavigation.getFrame or webNavigation.getAllFrames. Once such a tab is swapped in, an onTabReplaced event is fired and they become accessible via these APIs.

A note about timestamps

It's important to note that some technical oddities in the OS's handling of distinct Chrome processes can cause the clock to be skewed between the browser itself and extension processes. That means that WebNavigation's events' timeStamp property is only guaranteed to be internally consistent. Comparing one event to another event will give you the correct offset between them, but comparing them to the current time inside the extension (via (new Date()).getTime(), for instance) might give unexpected results.

A note about frame IDs

Frames within a tab can be identified by a frame ID. The frame ID of the main frame is always 0, the ID of child frames is a positive number. Once a document is constructed in a frame, its frame ID remains constant during the lifetime of the document. As of Chrome 49, this ID is also constant for the lifetime of the frame (across multiple navigations).

Due to the multi-process nature of Chrome, a tab might use different processes to render the source and destination of a web page. Therefore, if a navigation takes place in a new process, you might receive events both from the new and the old page until the new navigation is committed (i.e. the onCommitted event is send for the new main frame). In other words, it is possible to have more than one pending sequence of webNavigation events with the same frameId. The sequences can be distinguished by the processId key.

Also note that during a provisional load the process might be switched several times. This happens when the load is redirected to a different site. In this case, you will receive repeated onBeforeNavigate and onErrorOccurred events, until you receive the final onCommitted event.

Transition types and qualifiers

The webNavigation API's onCommitted event has a transitionType and a transitionQualifiers property. The transition type is the same as used in the history API describing how the browser navigated to this particular URL. In addition, several transition qualifiers can be returned that further define the navigation.

The following transition qualifiers exist:

Transition qualifier Description
"client_redirect" One or more redirects caused by JavaScript or meta refresh tags on the page happened during the navigation.
"server_redirect" One or more redirects caused by HTTP headers sent from the server happened during the navigation.
"forward_back" The user used the Forward or Back button to initiate the navigation.
"from_address_bar" The user initiated the navigation from the address bar (aka Omnibox).

Summary

Types
TransitionType
TransitionQualifier
Methods
getFrame − chrome.webNavigation.getFrame(object details, function callback)
getAllFrames − chrome.webNavigation.getAllFrames(object details, function callback)
Events
onBeforeNavigate
onCommitted
onDOMContentLoaded
onCompleted
onErrorOccurred
onCreatedNavigationTarget
onReferenceFragmentUpdated
onTabReplaced
onHistoryStateUpdated

Types

TransitionType

Cause of the navigation. The same transition types as defined in the history API are used. These are the same transition types as defined in the history API except with "start_page" in place of "auto_toplevel" (for backwards compatibility).
Enum
"link", "typed", "auto_bookmark", "auto_subframe", "manual_subframe", "generated", "start_page", "form_submit", "reload", "keyword", or "keyword_generated"

TransitionQualifier

Enum
"client_redirect", "server_redirect", "forward_back", or "from_address_bar"

Methods

getFrame

chrome.webNavigation.getFrame(object details, function callback)

Retrieves information about the given frame. A frame refers to an <iframe> or a <frame> of a web page and is identified by a tab ID and a frame ID.

Parameters
object details

Information about the frame to retrieve information about.

integer tabId

The ID of the tab in which the frame is.

integer (optional) processId

Deprecated since Chrome 49. Frames are now uniquely identified by their tab ID and frame ID; the process ID is no longer needed and therefore ignored.

The ID of the process that runs the renderer for this tab.

integer frameId

The ID of the frame in the given tab.

function callback

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

function(object details) {...};
object (optional) details

Information about the requested frame, null if the specified frame ID and/or tab ID are invalid.

boolean errorOccurred

True if the last navigation in this frame was interrupted by an error, i.e. the onErrorOccurred event fired.

string url

The URL currently associated with this frame, if the frame identified by the frameId existed at one point in the given tab. The fact that an URL is associated with a given frameId does not imply that the corresponding frame still exists.

integer parentFrameId

The ID of the parent frame, or -1 if this is the main frame.

getAllFrames

chrome.webNavigation.getAllFrames(object details, function callback)

Retrieves information about all frames of a given tab.

Parameters
object details

Information about the tab to retrieve all frames from.

integer tabId

The ID of the tab.

function callback

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

function(array of object details) {...};
array of object (optional) details

A list of frames in the given tab, null if the specified tab ID is invalid.

Properties of each object

boolean errorOccurred

True if the last navigation in this frame was interrupted by an error, i.e. the onErrorOccurred event fired.

integer processId

The ID of the process that runs the renderer for this frame.

integer frameId

The ID of the frame. 0 indicates that this is the main frame; a positive value indicates the ID of a subframe.

integer parentFrameId

The ID of the parent frame, or -1 if this is the main frame.

string url

The URL currently associated with this frame.

Events

onBeforeNavigate

Fired when a navigation is about to occur.

Filters

array of object url

Conditions that the URL being navigated to must satisfy. The 'schemes' and 'ports' fields of UrlFilter are ignored for this event.

Properties of each object

Filters URLs for various criteria. See event filtering. All criteria are case sensitive.
string (optional) hostContains

Matches if the host name of the URL contains a specified string. To test whether a host name component has a prefix 'foo', use hostContains: '.foo'. This matches 'www.foobar.com' and 'foo.com', because an implicit dot is added at the beginning of the host name. Similarly, hostContains can be used to match against component suffix ('foo.') and to exactly match against components ('.foo.'). Suffix- and exact-matching for the last components need to be done separately using hostSuffix, because no implicit dot is added at the end of the host name.

string (optional) hostEquals

Matches if the host name of the URL is equal to a specified string.

string (optional) hostPrefix

Matches if the host name of the URL starts with a specified string.

string (optional) hostSuffix

Matches if the host name of the URL ends with a specified string.

string (optional) pathContains

Matches if the path segment of the URL contains a specified string.

string (optional) pathEquals

Matches if the path segment of the URL is equal to a specified string.

string (optional) pathPrefix

Matches if the path segment of the URL starts with a specified string.

string (optional) pathSuffix

Matches if the path segment of the URL ends with a specified string.

string (optional) queryContains

Matches if the query segment of the URL contains a specified string.

string (optional) queryEquals

Matches if the query segment of the URL is equal to a specified string.

string (optional) queryPrefix

Matches if the query segment of the URL starts with a specified string.

string (optional) querySuffix

Matches if the query segment of the URL ends with a specified string.

string (optional) urlContains

Matches if the URL (without fragment identifier) contains a specified string. Port numbers are stripped from the URL if they match the default port number.

string (optional) urlEquals

Matches if the URL (without fragment identifier) is equal to a specified string. Port numbers are stripped from the URL if they match the default port number.

string (optional) urlMatches

Matches if the URL (without fragment identifier) matches a specified regular expression. Port numbers are stripped from the URL if they match the default port number. The regular expressions use the RE2 syntax.

string (optional) originAndPathMatches

Matches if the URL without query segment and fragment identifier matches a specified regular expression. Port numbers are stripped from the URL if they match the default port number. The regular expressions use the RE2 syntax.

string (optional) urlPrefix

Matches if the URL (without fragment identifier) starts with a specified string. Port numbers are stripped from the URL if they match the default port number.

string (optional) urlSuffix

Matches if the URL (without fragment identifier) ends with a specified string. Port numbers are stripped from the URL if they match the default port number.

array of string (optional) schemes

Matches if the scheme of the URL is equal to any of the schemes specified in the array.

array of integer or array of integer (optional) ports

Matches if the port of the URL is contained in any of the specified port lists. For example [80, 443, [1000, 1200]] matches all requests on port 80, 443 and in the range 1000-1200.

addListener

chrome.webNavigation.onBeforeNavigate.addListener(function callback)
Parameters
function callback

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

function(object details) {...};
object details
integer tabId

The ID of the tab in which the navigation is about to occur.

string url
integer processId

Deprecated since Chrome 50. The processId is no longer set for this event, since the process which will render the resulting document is not known until onCommit.

The value of -1.

integer frameId

0 indicates the navigation happens in the tab content window; a positive value indicates navigation in a subframe. Frame IDs are unique for a given tab and process.

integer parentFrameId

The ID of the parent frame, or -1 if this is the main frame.

double timeStamp

The time when the browser was about to start the navigation, in milliseconds since the epoch.

onCommitted

Fired when a navigation is committed. The document (and the resources it refers to, such as images and subframes) might still be downloading, but at least part of the document has been received from the server and the browser has decided to switch to the new document.

Filters

array of object url

Conditions that the URL being navigated to must satisfy. The 'schemes' and 'ports' fields of UrlFilter are ignored for this event.

Properties of each object

Filters URLs for various criteria. See event filtering. All criteria are case sensitive.
string (optional) hostContains

Matches if the host name of the URL contains a specified string. To test whether a host name component has a prefix 'foo', use hostContains: '.foo'. This matches 'www.foobar.com' and 'foo.com', because an implicit dot is added at the beginning of the host name. Similarly, hostContains can be used to match against component suffix ('foo.') and to exactly match against components ('.foo.'). Suffix- and exact-matching for the last components need to be done separately using hostSuffix, because no implicit dot is added at the end of the host name.

string (optional) hostEquals

Matches if the host name of the URL is equal to a specified string.

string (optional) hostPrefix

Matches if the host name of the URL starts with a specified string.

string (optional) hostSuffix

Matches if the host name of the URL ends with a specified string.

string (optional) pathContains

Matches if the path segment of the URL contains a specified string.

string (optional) pathEquals

Matches if the path segment of the URL is equal to a specified string.

string (optional) pathPrefix

Matches if the path segment of the URL starts with a specified string.

string (optional) pathSuffix

Matches if the path segment of the URL ends with a specified string.

string (optional) queryContains

Matches if the query segment of the URL contains a specified string.

string (optional) queryEquals

Matches if the query segment of the URL is equal to a specified string.

string (optional) queryPrefix

Matches if the query segment of the URL starts with a specified string.

string (optional) querySuffix

Matches if the query segment of the URL ends with a specified string.

string (optional) urlContains

Matches if the URL (without fragment identifier) contains a specified string. Port numbers are stripped from the URL if they match the default port number.

string (optional) urlEquals

Matches if the URL (without fragment identifier) is equal to a specified string. Port numbers are stripped from the URL if they match the default port number.

string (optional) urlMatches

Matches if the URL (without fragment identifier) matches a specified regular expression. Port numbers are stripped from the URL if they match the default port number. The regular expressions use the RE2 syntax.

string (optional) originAndPathMatches

Matches if the URL without query segment and fragment identifier matches a specified regular expression. Port numbers are stripped from the URL if they match the default port number. The regular expressions use the RE2 syntax.

string (optional) urlPrefix

Matches if the URL (without fragment identifier) starts with a specified string. Port numbers are stripped from the URL if they match the default port number.

string (optional) urlSuffix

Matches if the URL (without fragment identifier) ends with a specified string. Port numbers are stripped from the URL if they match the default port number.

array of string (optional) schemes

Matches if the scheme of the URL is equal to any of the schemes specified in the array.

array of integer or array of integer (optional) ports

Matches if the port of the URL is contained in any of the specified port lists. For example [80, 443, [1000, 1200]] matches all requests on port 80, 443 and in the range 1000-1200.

addListener

chrome.webNavigation.onCommitted.addListener(function callback)
Parameters
function callback

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

function(object details) {...};
object details
integer tabId

The ID of the tab in which the navigation occurs.

string url
integer processId

The ID of the process that runs the renderer for this frame.

integer frameId

0 indicates the navigation happens in the tab content window; a positive value indicates navigation in a subframe. Frame IDs are unique within a tab.

integer parentFrameId

Since Chrome 74.

The ID of the parent frame, or -1 if this is the main frame.

TransitionType transitionType

Cause of the navigation.

array of TransitionQualifier transitionQualifiers

A list of transition qualifiers.

double timeStamp

The time when the navigation was committed, in milliseconds since the epoch.

onDOMContentLoaded

Fired when the page's DOM is fully constructed, but the referenced resources may not finish loading.

Filters

array of object url

Conditions that the URL being navigated to must satisfy. The 'schemes' and 'ports' fields of UrlFilter are ignored for this event.

Properties of each object

Filters URLs for various criteria. See event filtering. All criteria are case sensitive.
string (optional) hostContains

Matches if the host name of the URL contains a specified string. To test whether a host name component has a prefix 'foo', use hostContains: '.foo'. This matches 'www.foobar.com' and 'foo.com', because an implicit dot is added at the beginning of the host name. Similarly, hostContains can be used to match against component suffix ('foo.') and to exactly match against components ('.foo.'). Suffix- and exact-matching for the last components need to be done separately using hostSuffix, because no implicit dot is added at the end of the host name.

string (optional) hostEquals

Matches if the host name of the URL is equal to a specified string.

string (optional) hostPrefix

Matches if the host name of the URL starts with a specified string.

string (optional) hostSuffix

Matches if the host name of the URL ends with a specified string.

string (optional) pathContains

Matches if the path segment of the URL contains a specified string.

string (optional) pathEquals

Matches if the path segment of the URL is equal to a specified string.

string (optional) pathPrefix

Matches if the path segment of the URL starts with a specified string.

string (optional) pathSuffix

Matches if the path segment of the URL ends with a specified string.

string (optional) queryContains

Matches if the query segment of the URL contains a specified string.

string (optional) queryEquals

Matches if the query segment of the URL is equal to a specified string.

string (optional) queryPrefix

Matches if the query segment of the URL starts with a specified string.

string (optional) querySuffix

Matches if the query segment of the URL ends with a specified string.

string (optional) urlContains

Matches if the URL (without fragment identifier) contains a specified string. Port numbers are stripped from the URL if they match the default port number.

string (optional) urlEquals

Matches if the URL (without fragment identifier) is equal to a specified string. Port numbers are stripped from the URL if they match the default port number.

string (optional) urlMatches

Matches if the URL (without fragment identifier) matches a specified regular expression. Port numbers are stripped from the URL if they match the default port number. The regular expressions use the RE2 syntax.

string (optional) originAndPathMatches

Matches if the URL without query segment and fragment identifier matches a specified regular expression. Port numbers are stripped from the URL if they match the default port number. The regular expressions use the RE2 syntax.

string (optional) urlPrefix

Matches if the URL (without fragment identifier) starts with a specified string. Port numbers are stripped from the URL if they match the default port number.

string (optional) urlSuffix

Matches if the URL (without fragment identifier) ends with a specified string. Port numbers are stripped from the URL if they match the default port number.

array of string (optional) schemes

Matches if the scheme of the URL is equal to any of the schemes specified in the array.

array of integer or array of integer (optional) ports

Matches if the port of the URL is contained in any of the specified port lists. For example [80, 443, [1000, 1200]] matches all requests on port 80, 443 and in the range 1000-1200.

addListener

chrome.webNavigation.onDOMContentLoaded.addListener(function callback)
Parameters
function callback

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

function(object details) {...};
object details
integer tabId

The ID of the tab in which the navigation occurs.

string url
integer processId

The ID of the process that runs the renderer for this frame.

integer frameId

0 indicates the navigation happens in the tab content window; a positive value indicates navigation in a subframe. Frame IDs are unique within a tab.

integer parentFrameId

Since Chrome 74.

The ID of the parent frame, or -1 if this is the main frame.

double timeStamp

The time when the page's DOM was fully constructed, in milliseconds since the epoch.

onCompleted

Fired when a document, including the resources it refers to, is completely loaded and initialized.

Filters

array of object url

Conditions that the URL being navigated to must satisfy. The 'schemes' and 'ports' fields of UrlFilter are ignored for this event.

Properties of each object

Filters URLs for various criteria. See event filtering. All criteria are case sensitive.
string (optional) hostContains

Matches if the host name of the URL contains a specified string. To test whether a host name component has a prefix 'foo', use hostContains: '.foo'. This matches 'www.foobar.com' and 'foo.com', because an implicit dot is added at the beginning of the host name. Similarly, hostContains can be used to match against component suffix ('foo.') and to exactly match against components ('.foo.'). Suffix- and exact-matching for the last components need to be done separately using hostSuffix, because no implicit dot is added at the end of the host name.

string (optional) hostEquals

Matches if the host name of the URL is equal to a specified string.

string (optional) hostPrefix

Matches if the host name of the URL starts with a specified string.

string (optional) hostSuffix

Matches if the host name of the URL ends with a specified string.

string (optional) pathContains

Matches if the path segment of the URL contains a specified string.

string (optional) pathEquals

Matches if the path segment of the URL is equal to a specified string.

string (optional) pathPrefix

Matches if the path segment of the URL starts with a specified string.

string (optional) pathSuffix

Matches if the path segment of the URL ends with a specified string.

string (optional) queryContains

Matches if the query segment of the URL contains a specified string.

string (optional) queryEquals

Matches if the query segment of the URL is equal to a specified string.

string (optional) queryPrefix

Matches if the query segment of the URL starts with a specified string.

string (optional) querySuffix

Matches if the query segment of the URL ends with a specified string.

string (optional) urlContains

Matches if the URL (without fragment identifier) contains a specified string. Port numbers are stripped from the URL if they match the default port number.

string (optional) urlEquals

Matches if the URL (without fragment identifier) is equal to a specified string. Port numbers are stripped from the URL if they match the default port number.

string (optional) urlMatches

Matches if the URL (without fragment identifier) matches a specified regular expression. Port numbers are stripped from the URL if they match the default port number. The regular expressions use the RE2 syntax.

string (optional) originAndPathMatches

Matches if the URL without query segment and fragment identifier matches a specified regular expression. Port numbers are stripped from the URL if they match the default port number. The regular expressions use the RE2 syntax.

string (optional) urlPrefix

Matches if the URL (without fragment identifier) starts with a specified string. Port numbers are stripped from the URL if they match the default port number.

string (optional) urlSuffix

Matches if the URL (without fragment identifier) ends with a specified string. Port numbers are stripped from the URL if they match the default port number.

array of string (optional) schemes

Matches if the scheme of the URL is equal to any of the schemes specified in the array.

array of integer or array of integer (optional) ports

Matches if the port of the URL is contained in any of the specified port lists. For example [80, 443, [1000, 1200]] matches all requests on port 80, 443 and in the range 1000-1200.

addListener

chrome.webNavigation.onCompleted.addListener(function callback)
Parameters
function callback

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

function(object details) {...};
object details
integer tabId

The ID of the tab in which the navigation occurs.

string url
integer processId

The ID of the process that runs the renderer for this frame.

integer frameId

0 indicates the navigation happens in the tab content window; a positive value indicates navigation in a subframe. Frame IDs are unique within a tab.

integer parentFrameId

Since Chrome 74.

The ID of the parent frame, or -1 if this is the main frame.

double timeStamp

The time when the document finished loading, in milliseconds since the epoch.

onErrorOccurred

Fired when an error occurs and the navigation is aborted. This can happen if either a network error occurred, or the user aborted the navigation.

Filters

array of object url

Conditions that the URL being navigated to must satisfy. The 'schemes' and 'ports' fields of UrlFilter are ignored for this event.

Properties of each object

Filters URLs for various criteria. See event filtering. All criteria are case sensitive.
string (optional) hostContains

Matches if the host name of the URL contains a specified string. To test whether a host name component has a prefix 'foo', use hostContains: '.foo'. This matches 'www.foobar.com' and 'foo.com', because an implicit dot is added at the beginning of the host name. Similarly, hostContains can be used to match against component suffix ('foo.') and to exactly match against components ('.foo.'). Suffix- and exact-matching for the last components need to be done separately using hostSuffix, because no implicit dot is added at the end of the host name.

string (optional) hostEquals

Matches if the host name of the URL is equal to a specified string.

string (optional) hostPrefix

Matches if the host name of the URL starts with a specified string.

string (optional) hostSuffix

Matches if the host name of the URL ends with a specified string.

string (optional) pathContains

Matches if the path segment of the URL contains a specified string.

string (optional) pathEquals

Matches if the path segment of the URL is equal to a specified string.

string (optional) pathPrefix

Matches if the path segment of the URL starts with a specified string.

string (optional) pathSuffix

Matches if the path segment of the URL ends with a specified string.

string (optional) queryContains

Matches if the query segment of the URL contains a specified string.

string (optional) queryEquals

Matches if the query segment of the URL is equal to a specified string.

string (optional) queryPrefix

Matches if the query segment of the URL starts with a specified string.

string (optional) querySuffix

Matches if the query segment of the URL ends with a specified string.

string (optional) urlContains

Matches if the URL (without fragment identifier) contains a specified string. Port numbers are stripped from the URL if they match the default port number.

string (optional) urlEquals

Matches if the URL (without fragment identifier) is equal to a specified string. Port numbers are stripped from the URL if they match the default port number.

string (optional) urlMatches

Matches if the URL (without fragment identifier) matches a specified regular expression. Port numbers are stripped from the URL if they match the default port number. The regular expressions use the RE2 syntax.

string (optional) originAndPathMatches

Matches if the URL without query segment and fragment identifier matches a specified regular expression. Port numbers are stripped from the URL if they match the default port number. The regular expressions use the RE2 syntax.

string (optional) urlPrefix

Matches if the URL (without fragment identifier) starts with a specified string. Port numbers are stripped from the URL if they match the default port number.

string (optional) urlSuffix

Matches if the URL (without fragment identifier) ends with a specified string. Port numbers are stripped from the URL if they match the default port number.

array of string (optional) schemes

Matches if the scheme of the URL is equal to any of the schemes specified in the array.

array of integer or array of integer (optional) ports

Matches if the port of the URL is contained in any of the specified port lists. For example [80, 443, [1000, 1200]] matches all requests on port 80, 443 and in the range 1000-1200.

addListener

chrome.webNavigation.onErrorOccurred.addListener(function callback)
Parameters
function callback

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

function(object details) {...};
object details
integer tabId

The ID of the tab in which the navigation occurs.

string url
integer processId

Deprecated since Chrome 50. The processId is no longer set for this event.

The value of -1.

integer frameId

0 indicates the navigation happens in the tab content window; a positive value indicates navigation in a subframe. Frame IDs are unique within a tab.

integer parentFrameId

Since Chrome 74.

The ID of the parent frame, or -1 if this is the main frame.

string error

The error description.

double timeStamp

The time when the error occurred, in milliseconds since the epoch.

onCreatedNavigationTarget

Fired when a new window, or a new tab in an existing window, is created to host a navigation.

Filters

array of object url

Conditions that the URL being navigated to must satisfy. The 'schemes' and 'ports' fields of UrlFilter are ignored for this event.

Properties of each object

Filters URLs for various criteria. See event filtering. All criteria are case sensitive.
string (optional) hostContains

Matches if the host name of the URL contains a specified string. To test whether a host name component has a prefix 'foo', use hostContains: '.foo'. This matches 'www.foobar.com' and 'foo.com', because an implicit dot is added at the beginning of the host name. Similarly, hostContains can be used to match against component suffix ('foo.') and to exactly match against components ('.foo.'). Suffix- and exact-matching for the last components need to be done separately using hostSuffix, because no implicit dot is added at the end of the host name.

string (optional) hostEquals

Matches if the host name of the URL is equal to a specified string.

string (optional) hostPrefix

Matches if the host name of the URL starts with a specified string.

string (optional) hostSuffix

Matches if the host name of the URL ends with a specified string.

string (optional) pathContains

Matches if the path segment of the URL contains a specified string.

string (optional) pathEquals

Matches if the path segment of the URL is equal to a specified string.

string (optional) pathPrefix

Matches if the path segment of the URL starts with a specified string.

string (optional) pathSuffix

Matches if the path segment of the URL ends with a specified string.

string (optional) queryContains

Matches if the query segment of the URL contains a specified string.

string (optional) queryEquals

Matches if the query segment of the URL is equal to a specified string.

string (optional) queryPrefix

Matches if the query segment of the URL starts with a specified string.

string (optional) querySuffix

Matches if the query segment of the URL ends with a specified string.

string (optional) urlContains

Matches if the URL (without fragment identifier) contains a specified string. Port numbers are stripped from the URL if they match the default port number.

string (optional) urlEquals

Matches if the URL (without fragment identifier) is equal to a specified string. Port numbers are stripped from the URL if they match the default port number.

string (optional) urlMatches

Matches if the URL (without fragment identifier) matches a specified regular expression. Port numbers are stripped from the URL if they match the default port number. The regular expressions use the RE2 syntax.

string (optional) originAndPathMatches

Matches if the URL without query segment and fragment identifier matches a specified regular expression. Port numbers are stripped from the URL if they match the default port number. The regular expressions use the RE2 syntax.

string (optional) urlPrefix

Matches if the URL (without fragment identifier) starts with a specified string. Port numbers are stripped from the URL if they match the default port number.

string (optional) urlSuffix

Matches if the URL (without fragment identifier) ends with a specified string. Port numbers are stripped from the URL if they match the default port number.

array of string (optional) schemes

Matches if the scheme of the URL is equal to any of the schemes specified in the array.

array of integer or array of integer (optional) ports

Matches if the port of the URL is contained in any of the specified port lists. For example [80, 443, [1000, 1200]] matches all requests on port 80, 443 and in the range 1000-1200.

addListener

chrome.webNavigation.onCreatedNavigationTarget.addListener(function callback)
Parameters
function callback

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

function(object details) {...};
object details
integer sourceTabId

The ID of the tab in which the navigation is triggered.

integer sourceProcessId

The ID of the process that runs the renderer for the source frame.

integer sourceFrameId

The ID of the frame with sourceTabId in which the navigation is triggered. 0 indicates the main frame.

string url

The URL to be opened in the new window.

integer tabId

The ID of the tab in which the url is opened

double timeStamp

The time when the browser was about to create a new view, in milliseconds since the epoch.

onReferenceFragmentUpdated

Fired when the reference fragment of a frame was updated. All future events for that frame will use the updated URL.

Filters

array of object url

Conditions that the URL being navigated to must satisfy. The 'schemes' and 'ports' fields of UrlFilter are ignored for this event.

Properties of each object

Filters URLs for various criteria. See event filtering. All criteria are case sensitive.
string (optional) hostContains

Matches if the host name of the URL contains a specified string. To test whether a host name component has a prefix 'foo', use hostContains: '.foo'. This matches 'www.foobar.com' and 'foo.com', because an implicit dot is added at the beginning of the host name. Similarly, hostContains can be used to match against component suffix ('foo.') and to exactly match against components ('.foo.'). Suffix- and exact-matching for the last components need to be done separately using hostSuffix, because no implicit dot is added at the end of the host name.

string (optional) hostEquals

Matches if the host name of the URL is equal to a specified string.

string (optional) hostPrefix

Matches if the host name of the URL starts with a specified string.

string (optional) hostSuffix

Matches if the host name of the URL ends with a specified string.

string (optional) pathContains

Matches if the path segment of the URL contains a specified string.

string (optional) pathEquals

Matches if the path segment of the URL is equal to a specified string.

string (optional) pathPrefix

Matches if the path segment of the URL starts with a specified string.

string (optional) pathSuffix

Matches if the path segment of the URL ends with a specified string.

string (optional) queryContains

Matches if the query segment of the URL contains a specified string.

string (optional) queryEquals

Matches if the query segment of the URL is equal to a specified string.

string (optional) queryPrefix

Matches if the query segment of the URL starts with a specified string.

string (optional) querySuffix

Matches if the query segment of the URL ends with a specified string.

string (optional) urlContains

Matches if the URL (without fragment identifier) contains a specified string. Port numbers are stripped from the URL if they match the default port number.

string (optional) urlEquals

Matches if the URL (without fragment identifier) is equal to a specified string. Port numbers are stripped from the URL if they match the default port number.

string (optional) urlMatches

Matches if the URL (without fragment identifier) matches a specified regular expression. Port numbers are stripped from the URL if they match the default port number. The regular expressions use the RE2 syntax.

string (optional) originAndPathMatches

Matches if the URL without query segment and fragment identifier matches a specified regular expression. Port numbers are stripped from the URL if they match the default port number. The regular expressions use the RE2 syntax.

string (optional) urlPrefix

Matches if the URL (without fragment identifier) starts with a specified string. Port numbers are stripped from the URL if they match the default port number.

string (optional) urlSuffix

Matches if the URL (without fragment identifier) ends with a specified string. Port numbers are stripped from the URL if they match the default port number.

array of string (optional) schemes

Matches if the scheme of the URL is equal to any of the schemes specified in the array.

array of integer or array of integer (optional) ports

Matches if the port of the URL is contained in any of the specified port lists. For example [80, 443, [1000, 1200]] matches all requests on port 80, 443 and in the range 1000-1200.

addListener

chrome.webNavigation.onReferenceFragmentUpdated.addListener(function callback)
Parameters
function callback

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

function(object details) {...};
object details
integer tabId

The ID of the tab in which the navigation occurs.

string url
integer processId

The ID of the process that runs the renderer for this frame.

integer frameId

0 indicates the navigation happens in the tab content window; a positive value indicates navigation in a subframe. Frame IDs are unique within a tab.

integer parentFrameId

Since Chrome 74.

The ID of the parent frame, or -1 if this is the main frame.

TransitionType transitionType

Cause of the navigation.

array of TransitionQualifier transitionQualifiers

A list of transition qualifiers.

double timeStamp

The time when the navigation was committed, in milliseconds since the epoch.

onTabReplaced

Fired when the contents of the tab is replaced by a different (usually previously pre-rendered) tab.

addListener

chrome.webNavigation.onTabReplaced.addListener(function callback)
Parameters
function callback

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

function(object details) {...};
object details
integer replacedTabId

The ID of the tab that was replaced.

integer tabId

The ID of the tab that replaced the old tab.

double timeStamp

The time when the replacement happened, in milliseconds since the epoch.

onHistoryStateUpdated

Fired when the frame's history was updated to a new URL. All future events for that frame will use the updated URL.

Filters

array of object url

Conditions that the URL being navigated to must satisfy. The 'schemes' and 'ports' fields of UrlFilter are ignored for this event.

Properties of each object

Filters URLs for various criteria. See event filtering. All criteria are case sensitive.
string (optional) hostContains

Matches if the host name of the URL contains a specified string. To test whether a host name component has a prefix 'foo', use hostContains: '.foo'. This matches 'www.foobar.com' and 'foo.com', because an implicit dot is added at the beginning of the host name. Similarly, hostContains can be used to match against component suffix ('foo.') and to exactly match against components ('.foo.'). Suffix- and exact-matching for the last components need to be done separately using hostSuffix, because no implicit dot is added at the end of the host name.

string (optional) hostEquals

Matches if the host name of the URL is equal to a specified string.

string (optional) hostPrefix

Matches if the host name of the URL starts with a specified string.

string (optional) hostSuffix

Matches if the host name of the URL ends with a specified string.

string (optional) pathContains

Matches if the path segment of the URL contains a specified string.

string (optional) pathEquals

Matches if the path segment of the URL is equal to a specified string.

string (optional) pathPrefix

Matches if the path segment of the URL starts with a specified string.

string (optional) pathSuffix

Matches if the path segment of the URL ends with a specified string.

string (optional) queryContains

Matches if the query segment of the URL contains a specified string.

string (optional) queryEquals

Matches if the query segment of the URL is equal to a specified string.

string (optional) queryPrefix

Matches if the query segment of the URL starts with a specified string.

string (optional) querySuffix

Matches if the query segment of the URL ends with a specified string.

string (optional) urlContains

Matches if the URL (without fragment identifier) contains a specified string. Port numbers are stripped from the URL if they match the default port number.

string (optional) urlEquals

Matches if the URL (without fragment identifier) is equal to a specified string. Port numbers are stripped from the URL if they match the default port number.

string (optional) urlMatches

Matches if the URL (without fragment identifier) matches a specified regular expression. Port numbers are stripped from the URL if they match the default port number. The regular expressions use the RE2 syntax.

string (optional) originAndPathMatches

Matches if the URL without query segment and fragment identifier matches a specified regular expression. Port numbers are stripped from the URL if they match the default port number. The regular expressions use the RE2 syntax.

string (optional) urlPrefix

Matches if the URL (without fragment identifier) starts with a specified string. Port numbers are stripped from the URL if they match the default port number.

string (optional) urlSuffix

Matches if the URL (without fragment identifier) ends with a specified string. Port numbers are stripped from the URL if they match the default port number.

array of string (optional) schemes

Matches if the scheme of the URL is equal to any of the schemes specified in the array.

array of integer or array of integer (optional) ports

Matches if the port of the URL is contained in any of the specified port lists. For example [80, 443, [1000, 1200]] matches all requests on port 80, 443 and in the range 1000-1200.

addListener

chrome.webNavigation.onHistoryStateUpdated.addListener(function callback)
Parameters
function callback

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

function(object details) {...};
object details
integer tabId

The ID of the tab in which the navigation occurs.

string url
integer processId

The ID of the process that runs the renderer for this frame.

integer frameId

0 indicates the navigation happens in the tab content window; a positive value indicates navigation in a subframe. Frame IDs are unique within a tab.

integer parentFrameId

Since Chrome 74.

The ID of the parent frame, or -1 if this is the main frame.

TransitionType transitionType

Cause of the navigation.

array of TransitionQualifier transitionQualifiers

A list of transition qualifiers.

double timeStamp

The time when the navigation was committed, in milliseconds since the epoch.