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

nativeMessaging

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.

Return type (Promise)

Port through which messages can be sent and received. The port’s runtime.Port onDisconnect event is fired if the extension/app does not exist.

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

  • nativeMessaging

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.

Return type (Promise)

The JavaScript ‘window’ object for the background page.

getBrowserInfo()

Returns information about the current browser.

Return type (Promise)

getContexts(filter)

Fetches information about active contexts associated with this extension

Parameters

filter

(runtime.ContextFilter)

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.

Return type (Promise)

any

The JSON response object sent by the handler of the message. If an error occurs while connecting to the extension, the callback will be called with no arguments and lastError will be set to the error message.

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

  • nativeMessaging

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

port

(Port)

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

port

(Port)

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.

sender

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.

sender

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’.

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

contextType

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.

[tab]

(Tab, optional)

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

arch

The machine’s processor architecture.

nacl_arch

(runtime.PlatformNaclArch) Unsupported.

The native client architecture. This may be different from arch on some platforms.

os

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)

onDisconnect

(Event)

onMessage

(Event)

postMessage

(function)

[sender]

(MessageSender, optional)

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