runtime
=======

This module provides information about your extension and the environment it's running in.

It also provides messaging APIs enabling you to:

* Communicate between different parts of your extension. For advice on choosing between the messaging options, see Choosing between one-off messages and connection-based messaging.
* Communicate with other extensions.
* Communicate with native applications.
Types
-----

`runtime.Port`

Represents one end of a connection between two specific contexts, which can be used to exchange messages.

`runtime.MessageSender`

Contains information about the sender of a message or connection request.

`runtime.PlatformOs`

Identifies the browser's operating system.

`runtime.PlatformArch`

Identifies the browser's processor architecture.

`runtime.PlatformInfo`

Contains information about the platform the browser is running on.

`runtime.RequestUpdateCheckStatus`

Result of a call to `runtime.requestUpdateCheck()`.

`runtime.OnInstalledReason`

The reason that the `runtime.onInstalled` event is being dispatched.

`runtime.OnRestartRequiredReason`

The reason that the `runtime.onRestartRequired` event is being dispatched.

Properties
----------

`runtime.lastError`

This value is set when an asynchronous function has an error condition that it needs to report to its caller.

`runtime.id`

The ID of the extension.

Functions
---------

`runtime.getBackgroundPage()`

Retrieves the Window object for the background page running inside the current extension.

`runtime.openOptionsPage()`

Opens your extension's options page.

`runtime.getFrameId()`

Gets the frame ID of any window global or frame element.

`runtime.getManifest()`

Gets the complete manifest.json file, serialized as an object.

`runtime.getURL()`

Given a relative path from the manifest.json to a resource packaged with the extension, returns a fully-qualified URL.

`runtime.setUninstallURL()`

Sets a URL to be visited when the extension is uninstalled.

`runtime.reload()`

Reloads the extension.

`runtime.requestUpdateCheck()`

Checks for updates to this extension.

`runtime.connect()`

Establishes a connection from a content script to the main extension process, or from one extension to a different extension.

`runtime.connectNative()`

Connects the extension to a native application on the user's computer.

`runtime.sendMessage()`

Sends a single message to event listeners within your extension or a different extension. Similar to `runtime.connect` but only sends a single message, with an optional response.

`runtime.sendNativeMessage()`

Sends a single message from an extension to a native application.

`runtime.getPlatformInfo()`

Returns information about the current platform.

`runtime.getBrowserInfo()`

Returns information about the browser in which this extension is installed.

`runtime.getPackageDirectoryEntry()`

Returns a DirectoryEntry for the package directory.

Events
------

`runtime.onStartup`

Fired when a profile that has this extension installed first starts up. This event is not fired when an incognito profile is started.

`runtime.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.

`runtime.onSuspend`

Sent to the event page just before the extension is unloaded. This gives the extension an opportunity to do some cleanup.

`runtime.onSuspendCanceled`

Sent after `runtime.onSuspend` to indicate that the extension won't be unloaded after all.

`runtime.onUpdateAvailable`

Fired when an update is available, but isn't installed immediately because the extension is currently running.

`runtime.onBrowserUpdateAvailable` 
Deprecated

Fired when an update for the browser is available, but isn't installed immediately because a browser restart is required.

`runtime.onConnect`

Fired when a connection is made with either an extension process or a content script.

`runtime.onConnectExternal`

Fired when a connection is made with another extension.

`runtime.onMessage`

Fired when a message is sent from either an extension process or a content script.

`runtime.onMessageExternal`

Fired when a message is sent from another extension. Cannot be used in a content script.

`runtime.onRestartRequired`

Fired when the device needs to be restarted.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Example extensions
------------------

* beastify
* content-script-register
* cookie-bg-picker
* devtools-panels
* export-helpers
* favourite-colour
* find-across-tabs
* imagify
* menu-demo
* mocha-client-tests
* native-messaging
* notify-link-clicks-i18n
* permissions
* runtime-examples
* store-collected-images
* user-script-register
* webpack-modules

**Note:** This API is based on Chromium's `chrome.runtime` API. This documentation is derived from `runtime.json` in the Chromium code.