runtime API
Use the browser.runtime API to retrieve the background page, return details about the manifest, and listen for and respond to events in the app or extension lifecycle. You can also use this API to convert the relative path of URLs to fully-qualified URLs.
Permissions
Exchange messages with programs other than { -brand-short-name }
Functions
connect([extensionId], [connectInfo])
Attempts to connect to connect listeners within an extension/app (such as the background page), or other extensions/apps. This is useful for content scripts connecting to their extension processes, inter-app/extension communication, and $(topic:manifest/externally_connectable)[web messaging]. Note that this does not connect to any listeners in a content script. Extensions may connect to content scripts embedded in tabs via connect(tabId, [connectInfo]).
Parameters
[extensionId]
(string, optional)
The ID of the extension or app to connect to. If omitted, a connection will be attempted with your own extension. Required if sending messages from a web page for $(topic:manifest/externally_connectable)[web messaging].
[connectInfo]
(object, optional)
[includeTlsChannelId]
(boolean, optional)
Whether the TLS channel ID will be passed into onConnectExternal for processes that are listening for the connection event.
[name]
(string, optional)
Will be passed into onConnect for processes that are listening for the connection event.
connectNative(application)
Connects to a native application in the host machine.
Parameters
application
(string)
The name of the registered application to connect to.
Return type (Promise)
Port through which messages can be sent and received with the application
Required permissions
getBackgroundPage()
Retrieves the JavaScript ‘window’ object for the background page running inside the current extension/app. If the background page is an event page, the system will ensure it is loaded before calling the callback. If there is no background page, an error is set.
getBrowserInfo()
Returns information about the current browser.
Return type (Promise)
getContexts(filter)
Fetches information about active contexts associated with this extension
Parameters
A filter to find matching context.
Return type (Promise)
array of ExtensionContext
The matching contexts, if any.
getFrameId(target)
Get the frameId of any window global or frame element.
Parameters
target
(any)
A WindowProxy or a Browsing Context container element (IFrame, Frame, Embed, Object) for the target frame.
Return type (Promise)
number
The frameId of the target frame, or -1 if it doesn’t exist.
getManifest()
Returns details about the app or extension from the manifest. The object returned is a serialization of the full $(topic:manifest)[manifest file].
Return type (Promise)
object
The manifest details.
getPlatformInfo()
Returns information about the current platform.
Return type (Promise)
getURL(path)
Converts a relative path within an app/extension install directory to a fully-qualified URL.
Parameters
path
(string)
A path to a resource within an app/extension expressed relative to its install directory.
Return type (Promise)
string
The fully-qualified URL to the resource.
openOptionsPage()
<p>Open your Extension’s options page, if possible.</p><p>The precise behavior may depend on your manifest’s $(topic:optionsV2)[options_ui] or $(topic:options)[options_page] key, or what the browser happens to support at the time.</p><p>If your Extension does not declare an options page, or the browser failed to create one for some other reason, the callback will set lastError.</p>
reload()
Reloads the app or extension.
restart()
Restart the device when the app runs in kiosk mode. Otherwise, it’s no-op.
sendMessage([extensionId], message, [options])
Sends a single message to event listeners within your extension/app or a different extension/app. Similar to connect([extensionId], [connectInfo]) but only sends a single message, with an optional response. If sending to your extension, the onMessage event will be fired in each page, or onMessageExternal, if a different extension. Note that extensions cannot send messages to content scripts using this method. To send messages to content scripts, use sendMessage(tabId, message, [options]).
Parameters
[extensionId]
(string, optional)
The ID of the extension/app to send the message to. If omitted, the message will be sent to your own extension/app. Required if sending messages from a web page for $(topic:manifest/externally_connectable)[web messaging].
message
(any)
[options]
(object, optional)
[includeTlsChannelId]
(boolean, optional) Unsupported.
Whether the TLS channel ID will be passed into onMessageExternal for processes that are listening for the connection event.
sendNativeMessage(application, message)
Send a single message to a native application.
Parameters
application
(string)
The name of the native messaging host.
message
(any)
The message that will be passed to the native messaging host.
Return type (Promise)
any
The response message sent by the native messaging host. If an error occurs while connecting to the native messaging host, the callback will be called with no arguments and lastError will be set to the error message.
Required permissions
Events
onConnect
Fired when a connection is made from either an extension process or a content script.
Parameters for onConnect.addListener(listener)
listener(port)
A function that will be called when this event occurs.
Parameters passed to the listener function
onConnectExternal
Fired when a connection is made from another extension.
Parameters for onConnectExternal.addListener(listener)
listener(port)
A function that will be called when this event occurs.
Parameters passed to the listener function
onInstalled
Fired when the extension is first installed, when the extension is updated to a new version, and when the browser is updated to a new version.
Parameters for onInstalled.addListener(listener)
listener(details)
A function that will be called when this event occurs.
Parameters passed to the listener function
details
(object)
The reason that this event is being dispatched.
temporary
(boolean)
Indicates whether the addon is installed as a temporary extension.
[id]
(string, optional) Unsupported.
Indicates the ID of the imported shared module extension which updated. This is present only if ‘reason’ is ‘shared_module_update’.
[previousVersion]
(string, optional)
Indicates the previous version of the extension, which has just been updated. This is present only if ‘reason’ is ‘update’.
onMessage
Fired when a message is sent from either an extension process or a content script.
Parameters for onMessage.addListener(listener)
listener(message, sender, sendResponse)
A function that will be called when this event occurs.
Parameters passed to the listener function
[message]
(any, optional)
The message sent by the calling script.
sendResponse
(function)
Function to call (at most once) when you have a response. The argument should be any JSON-ifiable object. If you have more than one onMessage listener in the same document, then only one may send a response. This function becomes invalid when the event listener returns, unless you return true from the event listener to indicate you wish to send a response asynchronously (this will keep the message channel open to the other end until sendResponse is called).
Expected return value of the listener function
boolean
Return true from the event listener if you wish to call sendResponse after the event listener returns.
onMessageExternal
Fired when a message is sent from another extension/app. Cannot be used in a content script.
Parameters for onMessageExternal.addListener(listener)
listener(message, sender, sendResponse)
A function that will be called when this event occurs.
Parameters passed to the listener function
[message]
(any, optional)
The message sent by the calling script.
sendResponse
(function)
Function to call (at most once) when you have a response. The argument should be any JSON-ifiable object. If you have more than one onMessage listener in the same document, then only one may send a response. This function becomes invalid when the event listener returns, unless you return true from the event listener to indicate you wish to send a response asynchronously (this will keep the message channel open to the other end until sendResponse is called).
Expected return value of the listener function
boolean
Return true from the event listener if you wish to call sendResponse after the event listener returns.
onPerformanceWarning
Fired when a runtime performance issue is detected with the extension. Observe this event to be proactively notified of runtime performance problems with the extension.
Parameters for onPerformanceWarning.addListener(listener)
listener(details)
A function that will be called when this event occurs.
Parameters passed to the listener function
details
(object)
The performance warning event category, e.g. ‘content_script’.
description
(string)
An explanation of what the warning means, and hopefully how to address it.
The performance warning event severity, e.g. ‘high’.
[tabId]
(integer, optional)
The Tab that the performance warning relates to, if any.
onStartup
Fired when a profile that has this extension installed first starts up. This event is not fired for incognito profiles.
Parameters for onStartup.addListener(listener)
listener()
A function that will be called when this event occurs.
onSuspend
Sent to the event page just before it is unloaded. This gives the extension opportunity to do some clean up. Note that since the page is unloading, any asynchronous operations started while handling this event are not guaranteed to complete. If more activity for the event page occurs before it gets unloaded the onSuspendCanceled event will be sent and the page won’t be unloaded.
Parameters for onSuspend.addListener(listener)
listener()
A function that will be called when this event occurs.
onSuspendCanceled
Sent after onSuspend to indicate that the app won’t be unloaded after all.
Parameters for onSuspendCanceled.addListener(listener)
listener()
A function that will be called when this event occurs.
onUpdateAvailable
Fired when an update is available, but isn’t installed immediately because the app is currently running. If you do nothing, the update will be installed the next time the background page gets unloaded, if you want it to be installed sooner you can explicitly call reload(). If your extension is using a persistent background page, the background page of course never gets unloaded, so unless you call reload() manually in response to this event the update will not get installed until the next time the browser itself restarts. If no handlers are listening for this event, and your extension has a persistent background page, it behaves as if reload() is called in response to this event.
Parameters for onUpdateAvailable.addListener(listener)
listener(details)
A function that will be called when this event occurs.
Parameters passed to the listener function
details
(object)
The manifest details of the available update.
version
(string)
The version number of the available update.
Types
BrowserInfo
An object containing information about the current browser.
object
buildID
(string)
The browser’s build ID/date, for example ‘20160101’.
name
(string)
The name of the browser, for example ‘Firefox’.
vendor
(string)
The name of the browser vendor, for example ‘Mozilla’.
version
(string)
The browser’s version, for example ‘42.0.0’ or ‘0.8.1pre’.
ContextFilter
A filter to match against existing extension context. Matching contexts must match all specified filters.
object
[contextIds]
(array of string, optional)
[documentIds]
(array of string, optional)
[documentOrigins]
(array of string, optional)
[documentUrls]
(array of string, optional)
[frameIds]
(array of integer, optional)
[incognito]
(boolean, optional)
[tabIds]
(array of integer, optional)
[windowIds]
(array of integer, optional)
ContextType
The type of extension view.
string
Supported values:
BACKGROUND
POPUP
SIDE_PANEL
TAB
ExtensionContext
A context hosting extension content
object
contextId
(string)
An unique identifier associated to this context
The type of the context
frameId
(integer)
The frame ID for this context, or -1 if it is not hosted in a frame.
incognito
(boolean)
Whether the context is associated with an private browsing context.
tabId
(integer)
The tab ID for this context, or -1 if it is not hosted in a tab.
windowId
(integer)
The window ID for this context, or -1 if it is not hosted in a window.
[documentId]
(string, optional) Unsupported.
An UUID for the document associated with this context, or undefined if it is not hosted in a document
[documentOrigin]
(string, optional)
The origin of the document associated with this context, or undefined if it is not hosted in a document
[documentUrl]
(string, optional)
The URL of the document associated with this context, or undefined if it is not hosted in a document
MessageSender
An object containing information about the script context that sent a message or request.
object
[frameId]
(integer, optional)
The $(topic:frame_ids)[frame] that opened the connection. 0 for top-level frames, positive for child frames. This will only be set when tab is set.
[id]
(string, optional)
The ID of the extension or app that opened the connection, if any.
The Tab which opened the connection, if any. This property will <strong>only</strong> be present when the connection was opened from a tab (including content scripts), and <strong>only</strong> if the receiver is an extension, not an app.
[tlsChannelId]
(string, optional) Unsupported.
The TLS channel ID of the page or frame that opened the connection, if requested by the extension or app, and if available.
[url]
(string, optional)
The URL of the page or frame that opened the connection. If the sender is in an iframe, it will be iframe’s URL not the URL of the page which hosts it.
OnInstalledReason
The reason that this event is being dispatched.
string
Supported values:
install
update
browser_update
OnPerformanceWarningCategory
The performance warning event category, e.g. ‘content_script’.
string
Supported values:
content_script
OnPerformanceWarningSeverity
The performance warning event severity. Will be ‘high’ for serious and user-visible issues.
string
Supported values:
low
medium
high
OnRestartRequiredReason
The reason that the event is being dispatched. ‘app_update’ is used when the restart is needed because the application is updated to a newer version. ‘os_update’ is used when the restart is needed because the browser/OS is updated to a newer version. ‘periodic’ is used when the system runs for more than the permitted uptime set in the enterprise policy.
string
Supported values:
app_update
os_update
periodic
PlatformArch
The machine’s processor architecture.
string
Supported values:
aarch64
arm
ppc64
s390x
sparc64
x86-32
x86-64
noarch
PlatformInfo
An object containing information about the current platform.
object
The machine’s processor architecture.
nacl_arch
(runtime.PlatformNaclArch) Unsupported.
The native client architecture. This may be different from arch on some platforms.
The operating system the browser is running on.
PlatformOs
The operating system the browser is running on.
string
Supported values:
mac
win
android
cros
linux
openbsd
Port
An object which allows two way communication with other pages.
object
disconnect
(function)
name
(string)
postMessage
(function)
This property will only be present on ports passed to onConnect/onConnectExternal listeners.
RequestUpdateCheckStatus
Result of the update check.
string
Supported values:
throttled
no_update
update_available
Properties
id
The ID of the extension/app.
lastError
This will be defined during an API method callback if there was an error