Work with documentId

Tabs, frames, and documents

A browser tab, identified by a tabId, is the top-level container for web content. Within a tab, content can be structured into multiple frames: the main (outermost) frame, which has a frameId of 0, and any nested <iframe> elements, each with a frameId. As the top frameId is 0, frameId cannot be used to uniquely identify all frames across all tabs.

Each frame holds a document, the HTML page loaded at a URL. The relationship between these three concepts is:

• A tab contains one or more frames.
• A frame contains a document.
• Navigating a frame to a new URL replaces its document but keeps the same frame and, therefore, the same frameId.

This means that the combination of tabId and frameId identifies a frame (a stable browsing context), but not the document loaded in that frame.

Documents and frames are also present in non-tab contexts, including but not limited to:

• Sidebars
• Popups attached to extension buttons
• Devtools panels
• Background pages

Operations using tab and frame IDs

Many WebExtension APIs use tabId and frameId to identify where to perform an operation:

• Script and CSS injection: scripting.executeScript(), scripting.insertCSS(), and scripting.removeCSS() accept a tabId and optional frameIds in their scripting.InjectionTarget to specify where to inject into.
• User script injection: userScripts.execute() takes tabId and frameIds in its target.
• Messaging: tabs.sendMessage() and tabs.connect() accept a tabId and optional frameId to direct a message to its recipient.
• Frame information: webNavigation.getFrame() and webNavigation.getAllFrames() use tabId and frameId to look up or enumerate frame details.
• Events: Navigation events (webNavigation.onCommitted, webNavigation.onCompleted, and others), request events (webRequest.onBeforeRequest and others), and proxy.onRequest all include tabId and frameId to identify where an event occurred.

Because frameId identifies the frame rather than its content, there is a potential race condition. After your extension has obtained the tabId and frameId, the loaded document may change, so the extension's subsequent operation no longer targets the intended document. documentId was introduced to address this problem.

What is a documentId?

A documentId is assigned to each document when it loads and remains constant throughout the document's lifetime. When a frame navigates to a new URL, it retains its frameId but receives a new documentId. This distinguishes documentId from frameId: a frameId identifies the browsing context (the frame element itself), whereas a documentId identifies the document loaded within it.

The documentId also correctly handles edge cases that frameId cannot distinguish:

• Navigations: Each new document load, including cross-origin navigations, receives a new documentId even though the frameId is unchanged.
• Reloads: A page reload creates a new documentId, indicating a fresh document.
• history.pushState() and fragment updates: These don't create a new document, so the documentId is unchanged.

As it changes with each document load, the ID your extension obtained for a document remains valid only for that document. If the frame has navigated away, the documentId no longer matches. So, if your extension injects a script or sends a message using the documented ID after the navigation, the operation fails rather than silently targeting the wrong document.

When a document is restored from the back/forward cache (bfcache), its original documentId is also restored.

Get a documentId

There are several ways to obtain a documentId:

• Call runtime.getDocumentId() with a window or frame element from within a content script.
• Read the documentId or parentDocumentId property in the results of webNavigation.getFrame() or webNavigation.getAllFrames().
• Read the documentId or parentDocumentId from event details in webNavigation events (for events where the document of the navigation target is known when the event fires).
• Read the documentId from webRequest event details.
• Read the documentId from runtime.MessageSender when receiving messages using runtime.onMessage, runtime.onConnect, and related listeners.
• Read the documentId from the results of runtime.getContexts().

Using documentId to target documents

When you have a documentId, you can use it to target that document:

• Script and CSS injection: Use documentIds in scripting.InjectionTarget with scripting.executeScript(), scripting.insertCSS(), and scripting.removeCSS() to inject into specific documents.
• User script injection: Set documentIds in the target parameter of userScripts.execute().
• Messaging: Pass documentId in the options parameter of tabs.connect() or tabs.sendMessage() to send to a document in a tab.
• Frame lookup: Pass documentId to webNavigation.getFrame() as an alternative to tabId and frameId. If you also provide tabId and frameId, the frame is only returned when all three match.

APIs supporting documentId

These APIs include documentId support.

Obtain a documentId

• runtime.getDocumentId() returns the document UUID of a target window or frame element.

documentId in return values and event details

• runtime.getContexts() returns a documentId for each extension context and supports a documentIds filter property.
• runtime.MessageSender includes documentId, available in runtime.onConnect, runtime.onMessage, runtime.onMessageExternal, runtime.onConnectExternal, runtime.onUserScriptMessage, and runtime.onUserScriptConnect listeners.
• scripting.executeScript() returns documentId in each InjectionResult.
• userScripts.execute() results include documentId.
• webNavigation.getAllFrames() returns documentId and parentDocumentId for each frame.
• webNavigation.getFrame() returns documentId and parentDocumentId.
• webNavigation.onCommitted, webNavigation.onDOMContentLoaded, webNavigation.onCompleted, webNavigation.onErrorOccurred, webNavigation.onReferenceFragmentUpdated, and webNavigation.onHistoryStateUpdated include documentId and parentDocumentId in event details. webNavigation.onBeforeNavigate may have a parentDocumentId when a frame navigates, but doesn't have documentId because the event fires before a document is loaded.
• All webRequest events — webRequest.onBeforeRequest, webRequest.onBeforeSendHeaders, webRequest.onSendHeaders, webRequest.onHeadersReceived, webRequest.onAuthRequired, webRequest.onBeforeRedirect, webRequest.onResponseStarted, webRequest.onCompleted, and webRequest.onErrorOccurred — include documentId and parentDocumentId when applicable.
• proxy.RequestDetails includes documentId and parentDocumentId when applicable.
• declarativeNetRequest.onRuleMatchedDebug includes documentId when applicable.

documentId for targeting

• scripting.InjectionTarget supports documentIds to target specific documents in scripting.executeScript(), scripting.insertCSS(), and scripting.removeCSS().
• userScripts.execute() target supports documentIds.
• tabs.connect() options supports documentId to target a specific document.
• tabs.sendMessage() options supports documentId to target a specific document.
• webNavigation.getFrame() accepts documentId as an alternative to tabId and frameId.

Future developments

The WebExtensions Community Group (WECG) is discussing relaxing the requirement to provide tabId alongside documentId when targeting documents. See WECG issue #91 for the discussion.