chrome.offscreen
- Description
Use the
offscreenAPI to create and manage offscreen documents. - Permissions
offscreen - AvailabilityChrome 109+ MV3+
Manifest
You must declare the "offscreen" permission in the [extension manifest][1] to use the Offscreen API. For example:
{
"name": "My extension",
...
"permissions": [
"offscreen"
],
...
}Pages loaded as offscreen documents are handled differently from other types of extension pages. The extension's permissions carry over to offscreen documents, but extension API access is heavily limited. Currently, an offscreen document can only use the chrome.runtime APIs to send and receive messages; all other extension APIs are not exposed. Other notable differences between offscreen documents and normal pages are as follows:
- An offscreen document's URL must be a static HTML file bundled with the extension.
- Offscreen documents cannot be focused.
- Offscreen documents cannot have their
openerproperty set using thechrome.windowsAPI methodwindows.setSelfAsOpener(). - An extension can only have one offscreen document open at a time. If the extension is running in split mode with an active incognito profile, both the normal and incognito profiles can each have one offscreen document.
Reasons
Reasons, listed below, are set upon document creation to determine the document's lifespan. Currently, the AUDIO_PLAYBACK reason has specialized lifetime enforcement (CreateAudioLifetimeEnforcer). All others use generic idle detection (CreateEmptyEnforcer).
Examples
The following methods create and close an offscreen document. Only a single Document can be open at a time.
chrome.offscreen.createDocument({
url: chrome.runtime.getURL('off_screen.html'),
reasons: ['CLIPBOARD'],
justification: 'reason for needing the document',
});
chrome.offscreen.closeDocument()Summary
- Types
- Methods
Types
CreateParameters
Properties
- justification
string
A developer-provided string that explains, in more detail, the need for the background context. The user agent _may_ use this in display to the user.
- reasons
Reason[]
The reason(s) the extension is creating the offscreen document.
- url
string
The (relative) URL to load in the document.
Reason
Type
"TESTING"
,"AUDIO_PLAYBACK"
,"IFRAME_SCRIPTING"
,"DOM_SCRAPING"
,"BLOBS"
,"DOM_PARSER"
,"USER_MEDIA"
,"DISPLAY_MEDIA"
,"WEB_RTC"
, or"CLIPBOARD"
Methods
closeDocument
chrome.offscreen.closeDocument(
callback?:
function,
)
Closes the currently-open offscreen document for the extension.
Parameters
- callback
function optional
The
callbackparameter looks like:() => void
Returns
Promise<void>
In Manifest V3 and later, return a
Promiseby omitting thecallbackargument. The type inside thePromiseis the same as the 1st argument tocallback.
createDocument
chrome.offscreen.createDocument(
parameters:
CreateParameters,
callback?:
function,
)
Creates a new offscreen document for the extension.
Parameters
- parameters
The parameters describing the offscreen document to create.
- callback
function optional
The
callbackparameter looks like:() => void
Returns
Promise<void>
In Manifest V3 and later, return a
Promiseby omitting thecallbackargument. The type inside thePromiseis the same as the 1st argument tocallback.