webNavigation

This is for extensions that need to analyze or react to the navigation process itself, which is more detailed than what the tabs.onUpdated event provides.

Examples:

• A developer tool that analyzes page load performance and tracks redirect chains.
• A security extension that checks a URL against a blocklist before the navigation commits.
• An extension that provides a "loading progress" indicator based on the navigation events.
• An extension that injects a script at the earliest possible moment (onCommitted).

{
  "name": "My Navigation Tracker",
  "version": "1.0",
  "manifest_version": 3,
  "permissions": [
    "webNavigation"
  ],
  "background": {
    "service_worker": "background.js"
  }
}

Why is it risky?

This permission allows an extension to see the web address of every page you visit, in real-time, as you are navigating to it. It gives the extension a live feed of your browsing activity.

This is a step below giving access to your full history, but it is still very sensitive. A malicious extension could use this to track your browsing habits. Legitimate extensions might use this for features that need to react instantly when you visit a new page. You should be cautious when granting this permission.

This example logs the details of every completed top-level navigation request.

// background.js

chrome.webNavigation.onCompleted.addListener((details) => {
  // We only care about navigations in the main frame, not iframes.
  if (details.frameId === 0) {
    console.log(`Main frame navigation completed for tab ${details.tabId}`);
    console.log(`  URL: ${details.url}`);
    console.log(`  Timestamp: ${new Date(details.timeStamp).toLocaleTimeString()}`);
  }
}, {
  url: [{schemes: ['http', 'https']}] // Filter for http/https URLs
});

chrome.webNavigation.onErrorOccurred.addListener((details) => {
  if (details.frameId === 0) {
    console.error(`Navigation error in tab ${details.tabId}:`);
    console.error(`  URL: ${details.url}`);
    console.error(`  Error: ${details.error}`);
  }
});