Work with documentId
A documentId is a UUID string that identifies a unique document loaded in a tab or frame. This guide explains what documentId is, why it is useful, and how to use it in the WebExtension APIs.
A documentId is a UUID string that identifies a unique document loaded in a tab or frame. This guide explains what documentId is, why it is useful, and how to use it in the WebExtension APIs.
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:
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
tabIdand optionalframeIdsin their scripting.InjectionTarget to specify where to inject into. - User script injection: userScripts.execute() takes
tabIdandframeIdsin itstarget. - Messaging: tabs.sendMessage() and tabs.connect() accept a
tabIdand optionalframeIdto direct a message to its recipient. - Frame information: webNavigation.getFrame() and webNavigation.getAllFrames() use
tabIdandframeIdto 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
tabIdandframeIdto 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
documentIdeven though theframeIdis 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
documentIdis 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
windowor frame element from within a content script. - Read the
documentIdorparentDocumentIdproperty in the results of webNavigation.getFrame() or webNavigation.getAllFrames(). - Read the
documentIdorparentDocumentIdfrom event details in webNavigation events (for events where the document of the navigation target is known when the event fires). - Read the
documentIdfrom webRequest event details. - Read the
documentIdfrom runtime.MessageSender when receiving messages using runtime.onMessage, runtime.onConnect, and related listeners. - Read the
documentIdfrom 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
documentIdsin scripting.InjectionTarget with scripting.executeScript(), scripting.insertCSS(), and scripting.removeCSS() to inject into specific documents. - User script injection: Set
documentIdsin thetargetparameter of userScripts.execute(). - Messaging: Pass
documentIdin theoptionsparameter of tabs.connect() or tabs.sendMessage() to send to a document in a tab. - Frame lookup: Pass
documentIdto webNavigation.getFrame() as an alternative totabIdandframeId. If you also providetabIdandframeId, 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
documentIdfor each extension context and supports adocumentIdsfilter property. - runtime.MessageSender includes
documentId, available in runtime.onConnect, runtime.onMessage, runtime.onMessageExternal, runtime.onConnectExternal, runtime.onUserScriptMessage, and runtime.onUserScriptConnect listeners. - scripting.executeScript() returns
documentIdin eachInjectionResult. - userScripts.execute() results include
documentId. - webNavigation.getAllFrames() returns
documentIdandparentDocumentIdfor each frame. - webNavigation.getFrame() returns
documentIdandparentDocumentId. - webNavigation.onCommitted, webNavigation.onDOMContentLoaded, webNavigation.onCompleted, webNavigation.onErrorOccurred, webNavigation.onReferenceFragmentUpdated, and webNavigation.onHistoryStateUpdated include
documentIdandparentDocumentIdin event details. webNavigation.onBeforeNavigate may have aparentDocumentIdwhen a frame navigates, but doesn't havedocumentIdbecause the event fires before a document is loaded. - All
webRequestevents — webRequest.onBeforeRequest, webRequest.onBeforeSendHeaders, webRequest.onSendHeaders, webRequest.onHeadersReceived, webRequest.onAuthRequired, webRequest.onBeforeRedirect, webRequest.onResponseStarted, webRequest.onCompleted, and webRequest.onErrorOccurred — includedocumentIdandparentDocumentIdwhen applicable. - proxy.RequestDetails includes
documentIdandparentDocumentIdwhen applicable. - declarativeNetRequest.onRuleMatchedDebug includes
documentIdwhen applicable.
documentId for targeting
- scripting.InjectionTarget supports
documentIdsto target specific documents in scripting.executeScript(), scripting.insertCSS(), and scripting.removeCSS(). - userScripts.execute()
targetsupportsdocumentIds. - tabs.connect()
optionssupportsdocumentIdto target a specific document. - tabs.sendMessage()
optionssupportsdocumentIdto target a specific document. - webNavigation.getFrame() accepts
documentIdas an alternative totabIdandframeId.
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.