chrome.runtime

Description:	Use the `chrome.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.
Availability:	Stable since Chrome 22.
Learn More:	Manage App Lifecycle Event Pages

Summary

Types
Port
MessageSender
Properties
lastError
id
Methods
getBackgroundPage − `chrome.runtime.getBackgroundPage(function callback)`
getManifest − `object chrome.runtime.getManifest()`
getURL − `string chrome.runtime.getURL(string path)`
setUninstallURL − `chrome.runtime.setUninstallURL(string url)`
reload − `chrome.runtime.reload()`
requestUpdateCheck − `chrome.runtime.requestUpdateCheck(function callback)`
restart − `chrome.runtime.restart()`
connect − `Port chrome.runtime.connect(string extensionId, object connectInfo)`
connectNative − `Port chrome.runtime.connectNative(string application)`
sendMessage − `chrome.runtime.sendMessage(string extensionId, any message, object options, function responseCallback)`
sendNativeMessage − `chrome.runtime.sendNativeMessage(string application, object message, function responseCallback)`
getPlatformInfo − `chrome.runtime.getPlatformInfo(function callback)`
getPackageDirectoryEntry − `chrome.runtime.getPackageDirectoryEntry(function callback)`
Events
onStartup
onInstalled
onSuspend
onSuspendCanceled
onUpdateAvailable
onBrowserUpdateAvailable
onConnect
onConnectExternal
onMessage
onMessageExternal
onRestartRequired

Types

Port

An object which allows two way communication with other pages.

properties
string	name
function	disconnect
events.Event	onDisconnect
events.Event	onMessage
function	postMessage
MessageSender	(optional) sender	This property will only be present on ports passed to onConnect/onConnectExternal listeners.

MessageSender

An object containing information about the script context that sent a message or request.

properties
tabs.Tab	(optional) tab	The tabs.Tab which opened the connection, if any. This property will only be present when the connection was opened from a tab (including content scripts), and only if the receiver is an extension, not an app.
string	(optional) id	The ID of the extension or app that opened the connection, if any.
string	(optional) url	The URL of the page or frame that opened the connection, if any. This property will only be present when the connection was opened from a tab or content script.
string	(optional) tlsChannelId	The TLS channel ID of the web page that opened the connection, if requested by the extension or app, and if available.

Properties

object

chrome.runtime.lastError

This will be defined during an API method callback if there was an error

Properties
string	(optional) message	Details about the error which occurred.

string chrome.runtime.id The ID of the extension/app.

Methods

getBackgroundPage


              chrome.runtime.getBackgroundPage(function callback)

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.

Parameters

function

callback

The callback parameter should be a function that looks like this:

function(Window backgroundPage) {...};

Window

(optional) backgroundPage

The JavaScript 'window' object for the background page.

getManifest


              object
              chrome.runtime.getManifest()

Returns details about the app or extension from the manifest. The object returned is a serialization of the full manifest file.

Returns

The manifest details.

getURL


              string
              chrome.runtime.getURL(string path)

Converts a relative path within an app/extension install directory to a fully-qualified URL.

Parameters
string	path	A path to a resource within an app/extension expressed relative to its install directory.

setUninstallURL


              chrome.runtime.setUninstallURL(string url)

Sets the URL to be visited upon uninstallation. This may be used to clean up server-side data, do analytics, and implement surveys. Maximum 255 characters.

Parameters
string	url

reload


              chrome.runtime.reload()

Reloads the app or extension.

requestUpdateCheck


              chrome.runtime.requestUpdateCheck(function callback)

Requests an update check for this app/extension.

Parameters

function

callback

The callback parameter should be a function that looks like this:

function(enum of "throttled", "no_update", or "update_available" status, object details) {...};

enum of "throttled", "no_update", or "update_available" status Result of the update check.

object

(optional) details

If an update is available, this contains more information about the available update.

string

version

The version of the available update.

restart


              chrome.runtime.restart()

Restart the ChromeOS device when the app runs in kiosk mode. Otherwise, it's no-op.

connect


                  Port
              chrome.runtime.connect(string extensionId, object 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 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 tabs.connect.

Parameters

string

(optional) extensionId

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 web messaging.

object

(optional) connectInfo

string	(optional) name	Will be passed into onConnect for processes that are listening for the connection event.
boolean	(optional) includeTlsChannelId	Whether the TLS channel ID will be passed into onConnectExternal for processes that are listening for the connection event.

connectNative


                  Port
              chrome.runtime.connectNative(string application)

Connects to a native application in the host machine.

Parameters
string	application	The name of the registered application to connect to.

sendMessage


              chrome.runtime.sendMessage(string extensionId, any message, object options, function responseCallback)

Sends a single message to event listeners within your extension/app or a different extension/app. Similar to runtime.connect but only sends a single message, with an optional response. If sending to your extension, the runtime.onMessage event will be fired in each page, or runtime.onMessageExternal, if a different extension. Note that extensions cannot send messages to content scripts using this method. To send messages to content scripts, use tabs.sendMessage.

Parameters

string (optional) extensionId 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 web messaging.

any message

object

(optional) options

boolean

(optional) includeTlsChannelId

Whether the TLS channel ID will be passed into onMessageExternal for processes that are listening for the connection event.

function

(optional) responseCallback

If you specify the responseCallback parameter, it should be a function that looks like this:

function(any response) {...};

any

response

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 runtime.lastError will be set to the error message.

sendNativeMessage


              chrome.runtime.sendNativeMessage(string application, object message, function responseCallback)

Send a single message to a native application.

Parameters

string application The name of the native messaging host.

object message The message that will be passed to the native messaging host.

function

(optional) responseCallback

If you specify the responseCallback parameter, it should be a function that looks like this:

function(any response) {...};

any

response

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 runtime.lastError will be set to the error message.

getPlatformInfo


              chrome.runtime.getPlatformInfo(function callback)

Returns information about the current platform.

Parameters

function

callback

Called with results

The callback parameter should be a function that looks like this:

function(object platformInfo) {...};

object

platformInfo

enum of `"mac"`, `"win"`, `"android"`, `"cros"`, `"linux"`, or `"openbsd"`	os	The operating system chrome is running on.
enum of `"arm"`, `"x86-32"`, or `"x86-64"`	arch	The machine's processor architecture.
enum of `"arm"`, `"x86-32"`, or `"x86-64"`	nacl_arch	The native client architecture. This may be different from arch on some platforms.

getPackageDirectoryEntry


              chrome.runtime.getPackageDirectoryEntry(function callback)

Returns a DirectoryEntry for the package directory.

Parameters

function

callback

The callback parameter should be a function that looks like this:

function(DirectoryEntry directoryEntry) {...};

DirectoryEntry

directoryEntry

Events

onStartup

Fired when a profile that has this extension installed first starts up. This event is not fired when an incognito profile is started, even if this extension is operating in 'split' incognito mode.

addListener


                    chrome.runtime.onStartup.addListener(function callback)

Parameters
function	callback	The callback parameter should be a function that looks like this: `function() {...};`

onInstalled

Fired when the extension is first installed, when the extension is updated to a new version, and when Chrome is updated to a new version.

addListener


                    chrome.runtime.onInstalled.addListener(function callback)

Parameters

function

callback

The callback parameter should be a function that looks like this:

function(object details) {...};

object

details

enum of `"install"`, `"update"`, or `"chrome_update"`	reason	The reason that this event is being dispatched.
string	(optional) previousVersion	Indicates the previous version of the extension, which has just been updated. This is present only if 'reason' is 'update'.

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.

addListener


                    chrome.runtime.onSuspend.addListener(function callback)

Parameters
function	callback	The callback parameter should be a function that looks like this: `function() {...};`

onSuspendCanceled

Sent after onSuspend to indicate that the app won't be unloaded after all.

addListener


                    chrome.runtime.onSuspendCanceled.addListener(function callback)

Parameters
function	callback	The callback parameter should be a function that looks like this: `function() {...};`

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 chrome.runtime.reload().

addListener


                    chrome.runtime.onUpdateAvailable.addListener(function callback)

Parameters

function

callback

The callback parameter should be a function that looks like this:

function(object details) {...};

object

details

The manifest details of the available update.

string

version

The version number of the available update.

onBrowserUpdateAvailable

onBrowserUpdateAvailable is deprecated. Please use runtime.onRestartRequired.

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

addListener


                    chrome.runtime.onBrowserUpdateAvailable.addListener(function callback)

Parameters
function	callback	The callback parameter should be a function that looks like this: `function() {...};`

onConnect

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

addListener


                    chrome.runtime.onConnect.addListener(function callback)

Parameters

function

callback

The callback parameter should be a function that looks like this:

function( Port port) {...};

Port

port

onConnectExternal

Fired when a connection is made from another extension.

addListener


                    chrome.runtime.onConnectExternal.addListener(function callback)

Parameters

function

callback

The callback parameter should be a function that looks like this:

function( Port port) {...};

Port

port

onMessage

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

addListener


                    chrome.runtime.onMessage.addListener(function callback)

Parameters

function

callback

The callback parameter should be a function that looks like this:

function(any message, MessageSender sender, function sendResponse) {...};

any	(optional) message	The message sent by the calling script.
MessageSender	sender
function	sendResponse	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).

onMessageExternal

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

addListener


                    chrome.runtime.onMessageExternal.addListener(function callback)

Parameters

function

callback

The callback parameter should be a function that looks like this:

function(any message, MessageSender sender, function sendResponse) {...};

any	(optional) message	The message sent by the calling script.
MessageSender	sender
function	sendResponse	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).

onRestartRequired

Fired when an app or the device that it runs on needs to be restarted. The app should close all its windows at its earliest convenient time to let the restart to happen. If the app does nothing, a restart will be enforced after a 24-hour grace period has passed. Currently, this event is only fired for Chrome OS kiosk apps.

addListener


                    chrome.runtime.onRestartRequired.addListener(function callback)

Parameters

function

callback

The callback parameter should be a function that looks like this:

function(enum of "app_update", "os_update", or "periodic" reason) {...};

enum of "app_update", "os_update", or "periodic" reason 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.