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.

The runtime API provides methods to support a number of areas of functionality that your extensions can use:

Message passing: These methods support message passing so that you can communicate with different parts of your extension (such as an extension popup and background scripts), other extensions, or native applications on the user's device. See Message Passing for an overview of the subject. Methods in this category include connect, connectNative, sendMessage, and sendNativeMessage.
Accessing extension and platform metadata: These methods let you retrieve several specific pieces of metadata about the extension and the platform. Methods in this category include getBackgroundPage, getManifest, getPackageDirectoryEntry, and getPlatformInfo.
Managing extension lifecycle and options: These methods let you perform some meta-operations on the extension, and display the options page to the extension user. Methods in this category include reload, requestUpdateCheck, setUninstallURL, and openOptionsPage.
Device restart support: These methods are available only on Chrome OS, and exist mainly to support kiosk implementations. Methods in this category include restart and restartAfterDelay.
Helper utilities: These methods provide utility such as the conversion of internal resource representations to external formats. Methods in this category include getURL.

Manifest

Most methods on the runtime API do not require any permission to use. However, sendNativeMessage and connectNative require the nativeMessaging permission to be declared in your manifest.

Examples

Use `getURL` to add an extension image to a page

In order for a web page to access an asset hosted on another domain, it must specify the resource's full URL (e.g. <img src="https://example.com/logo.png">). The same is true for when a web page wants to include assets included in an extension. The two main differences here are that the extension's assets must be exposed as web accessible resources and that typically content scripts are responsible for injecting extension assets.

This example shows how a content script can add an image in the extension's package to the page that the content script has been injected into.

//// content.js ////

{ // Block used to avoid setting global variables
  const img = document.createElement('img');
  img.src = chrome.runtime.getURL('logo.png');
  document.body.append(img);
}

Getting background data into a content script

Its common for an extension's content scripts to need data managed by another part of the extension, like the extension's background script. Much like two browser windows opened to the same web page, these two contexts cannot directly access each other's values. Instead, the extension can use message passing to coordinate across these different contexts.

In this example, the content script needs some data from the extension's background script in order to initialize its UI. To get this data, it passes a get-user-data message to the background, and the background responds with a copy of the user's information.

//// content.js ////

// 1. Send the background a message requesting the user's data
chrome.runtime.sendMessage('get-user-data', (response) => {
  // 3. Got an asynchronous response with the data from the background
  console.log('received user data', response);
  initializeUI(response);
});

//// background.js ////

// Example of a simple user data object
const user = {
  username: 'demo-user'
};

chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
  // 2. A page requested user data, respond with a copy of `user`
  if (message === 'get-user-data') {
    sendResponse(user);
  }
});

Gathering feedback on uninstall

Many extensions use post-uninstall surveys to understand how the extension could better serve its users and improve retention. The below example shows how one can add this functionality to their extension.

chrome.runtime.onInstalled.addListener(details => {
  if (details.reason === chrome.runtime.OnInstalledReason.INSTALL) {
    chrome.runtime.setUninstallURL('https://example.com/extension-survey');
  }
});

Summary

Types
MessageSender
OnInstalledReason
OnRestartRequiredReason
PlatformArch
PlatformInfo
PlatformNaclArch
PlatformOs
Port
RequestUpdateCheckStatus
Properties
id
lastError
Methods
connect
connectNative
getBackgroundPage
getManifest
getPackageDirectoryEntry
getPlatformInfo
getURL
openOptionsPage
reload
requestUpdateCheck
restart
restartAfterDelay
sendMessage
sendNativeMessage
setUninstallURL
Events
onBrowserUpdateAvailable
onConnect
onConnectExternal
onConnectNative
onInstalled
onMessage
onMessageExternal
onRestartRequired
onStartup
onSuspend
onSuspendCanceled
onUpdateAvailable

Types

MessageSender

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

Properties

frameId
number optional
The 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.
nativeApplication
string optional
Chrome 74+
The name of the native application that opened the connection, if any.
origin
string optional
Chrome 80+
The origin of the page or frame that opened the connection. It can vary from the url property (e.g., about:blank) or can be opaque (e.g., sandboxed iframes). This is useful for identifying if the origin can be trusted if we can't immediately tell from the URL.
tab
Tab optional
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.
tlsChannelId
string optional
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

Chrome 44+

The reason that this event is being dispatched.

Type

"install", "update", "chrome_update", or "shared_module_update"

OnRestartRequiredReason

Chrome 44+

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.

Type

"app_update", "os_update", or "periodic"

PlatformArch

Chrome 44+

The machine's processor architecture.

Type

"arm", "arm64", "x86-32", "x86-64", "mips", or "mips64"

PlatformInfo

An object containing information about the current platform.

Properties

arch
PlatformArch
The machine's processor architecture.
nacl_arch
PlatformNaclArch
The native client architecture. This may be different from arch on some platforms.
os
PlatformOs
The operating system Chrome is running on.

PlatformNaclArch

Chrome 44+

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

Type

"arm", "x86-32", "x86-64", "mips", or "mips64"

PlatformOs

Chrome 44+

The operating system Chrome is running on.

Type

"mac", "win", "android", "cros", "linux", or "openbsd"

Port

An object which allows two way communication with other pages. See Long-lived connections for more information.

Properties

name
string
The name of the port, as specified in the call to runtime.connect.
onDisconnect
event
Fired when the port is disconnected from the other end(s). runtime.lastError may be set if the port was disconnected by an error. If the port is closed via disconnect, then this event is only fired on the other end. This event is fired at most once (see also Port lifetime).
The onDisconnect.addListener function looks like: (callback: function) => {...}
- callback
  function
  The callback parameter looks like: (port: Port) => void
  - port
    Port
onMessage
event
This event is fired when postMessage is called by the other end of the port.
The onMessage.addListener function looks like: (callback: function) => {...}
- callback
  function
  The callback parameter looks like: (message: any, port: Port) => void
  - message
    any
  - port
    Port
sender
MessageSender optional
This property will only be present on ports passed to onConnect / onConnectExternal / onConnectNative listeners.
disconnect
function
Immediately disconnect the port. Calling disconnect() on an already-disconnected port has no effect. When a port is disconnected, no new events will be dispatched to this port.
The disconnect function looks like: () => {...}
postMessage
function
Send a message to the other end of the port. If the port is disconnected, an error is thrown.
The postMessage function looks like: (message: any) => {...}
- message
  any
  Chrome 52+
  The message to send. This object should be JSON-ifiable.

RequestUpdateCheckStatus

Chrome 44+

Result of the update check.

Type

"throttled", "no_update", or "update_available"

Properties

id

The ID of the extension/app.

Type

string

lastError

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

Type

object

Properties

message
string optional
Details about the error which occurred.

Methods

connect

chrome.runtime.connect(
  extensionId?: string,
  connectInfo?: object,
)

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

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

Returns

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

connectNative

chrome.runtime.connectNative(
  application: string,
)

Connects to a native application in the host machine. See Native Messaging for more information.

Parameters

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

Returns

Port
Port through which messages can be sent and received with the application

getBackgroundPage

chrome.runtime.getBackgroundPage(
  callback: function,
)

Foreground only

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

callback
function
The callback parameter looks like: (backgroundPage?: Window) => void
- backgroundPage
  Window optional
  The JavaScript 'window' object for the background page.

getManifest

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

object
The manifest details.

getPackageDirectoryEntry

chrome.runtime.getPackageDirectoryEntry(
  callback: function,
)

Foreground only

Returns a DirectoryEntry for the package directory.

Parameters

callback
function
The callback parameter looks like: (directoryEntry: DirectoryEntry) => void
- directoryEntry
  DirectoryEntry

getPlatformInfo

chrome.runtime.getPlatformInfo(
  callback: function,
)

Returns information about the current platform.

Parameters

callback
function
The callback parameter looks like: (platformInfo: PlatformInfo) => void
- platformInfo
  PlatformInfo

getURL

chrome.runtime.getURL(
  path: string,
)

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.

Returns

string
The fully-qualified URL to the resource.

openOptionsPage

chrome.runtime.openOptionsPage(
  callback?: function,
)

Open your Extension's options page, if possible.

The precise behavior may depend on your manifest's [options_ui](https://developer.chrome.com/docs/extensions/optionsV2) or [options_page](https://developer.chrome.com/docs/extensions/options) key, or what Chrome happens to support at the time. For example, the page may be opened in a new tab, within chrome://extensions, within an App, or it may just focus an open options page. It will never cause the caller page to reload.

If your Extension does not declare an options page, or Chrome failed to create one for some other reason, the callback will set lastError.

Parameters

callback
function optional
The callback parameter looks like: () => void

reload

chrome.runtime.reload()

Reloads the app or extension. This method is not supported in kiosk mode. For kiosk mode, use chrome.runtime.restart() method.

requestUpdateCheck

chrome.runtime.requestUpdateCheck(
  callback: function,
)

Requests an immediate update check be done for this app/extension.

Important: Most extensions/apps should not use this method, since Chrome already does automatic checks every few hours, and you can listen for the runtime.onUpdateAvailable event without needing to call requestUpdateCheck.

This method is only appropriate to call in very limited circumstances, such as if your extension/app talks to a backend service, and the backend service has determined that the client extension/app version is very far out of date and you'd like to prompt a user to update. Most other uses of requestUpdateCheck, such as calling it unconditionally based on a repeating timer, probably only serve to waste client, network, and server resources.

Parameters

callback
function
The callback parameter looks like: (status: RequestUpdateCheckStatus, details?: object) => void
- status
  RequestUpdateCheckStatus
  Result of the update check.
- details
  object optional
  If an update is available, this contains more information about the available update.
  - version
    string
    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.

restartAfterDelay

chrome.runtime.restartAfterDelay(
  seconds: number,
  callback?: function,
)

Chrome 53+

Restart the ChromeOS device when the app runs in kiosk mode after the given seconds. If called again before the time ends, the reboot will be delayed. If called with a value of -1, the reboot will be cancelled. It's a no-op in non-kiosk mode. It's only allowed to be called repeatedly by the first extension to invoke this API.

Parameters

seconds
number
Time to wait in seconds before rebooting the device, or -1 to cancel a scheduled reboot.
callback
function optional
The callback parameter looks like: () => void

sendMessage

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

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 every frame of your extension (except for the sender's frame), 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

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 web messaging.
message
any
The message to send. This message should be a JSON-ifiable object.
options
object optional
- includeTlsChannelId
  boolean optional
  Whether the TLS channel ID will be passed into onMessageExternal for processes that are listening for the connection event.
responseCallback
function optional
The responseCallback parameter looks like: (response: any) => void
- response
  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 runtime.lastError will be set to the error message.

sendNativeMessage

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

Send a single message to a native application.

Parameters

application
string
The name of the native messaging host.
message
object
The message that will be passed to the native messaging host.
responseCallback
function optional
The responseCallback parameter looks like: (response: any) => void
- response
  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 runtime.lastError will be set to the error message.

setUninstallURL

chrome.runtime.setUninstallURL(
  url: string,
  callback?: function,
)

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

url
string
URL to be opened after the extension is uninstalled. This URL must have an http: or https: scheme. Set an empty string to not open a new tab upon uninstallation.
callback
function optional
Chrome 45+
The callback parameter looks like: () => void

Events

onBrowserUpdateAvailable

chrome.runtime.onBrowserUpdateAvailable.addListener(
  callback: function,
)

Deprecated

Please use runtime.onRestartRequired.

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

Parameters

callback
function
The callback parameter looks like: () => void

onConnect

chrome.runtime.onConnect.addListener(
  callback: function,
)

Fired when a connection is made from either an extension process or a content script (by runtime.connect).

Parameters

callback
function
The callback parameter looks like: (port: Port) => void
- port
  Port

onConnectExternal

chrome.runtime.onConnectExternal.addListener(
  callback: function,
)

Fired when a connection is made from another extension (by runtime.connect).

Parameters

callback
function
The callback parameter looks like: (port: Port) => void
- port
  Port

onConnectNative

chrome.runtime.onConnectNative.addListener(
  callback: function,
)

Chrome 74+

Fired when a connection is made from a native application. Currently only supported on Chrome OS.

Parameters

callback
function
The callback parameter looks like: (port: Port) => void
- port
  Port

onInstalled

chrome.runtime.onInstalled.addListener(
  callback: function,
)

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.

Parameters

callback
function
The callback parameter looks like: (details: object) => void
- details
  object
  - id
    string optional
    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'.
  - reason
    OnInstalledReason
    The reason that this event is being dispatched.

onMessage

chrome.runtime.onMessage.addListener(
  callback: function,
)

Fired when a message is sent from either an extension process (by runtime.sendMessage) or a content script (by tabs.sendMessage).

Parameters

callback
function
The callback parameter looks like: (message: any, sender: MessageSender, sendResponse: function) => boolean | undefined
- message
  any
- sender
  MessageSender
- sendResponse
  function
  The sendResponse parameter looks like: () => void
- returns
  boolean | undefined

onMessageExternal

chrome.runtime.onMessageExternal.addListener(
  callback: function,
)

Fired when a message is sent from another extension/app (by runtime.sendMessage). Cannot be used in a content script.

Parameters

callback
function
The callback parameter looks like: (message: any, sender: MessageSender, sendResponse: function) => boolean | undefined
- message
  any
- sender
  MessageSender
- sendResponse
  function
  The sendResponse parameter looks like: () => void
- returns
  boolean | undefined

onRestartRequired

chrome.runtime.onRestartRequired.addListener(
  callback: function,
)

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.

Parameters

callback
function
The callback parameter looks like: (reason: OnRestartRequiredReason) => void
- reason
  OnRestartRequiredReason

onStartup

chrome.runtime.onStartup.addListener(
  callback: function,
)

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.

Parameters

callback
function
The callback parameter looks like: () => void

onSuspend

chrome.runtime.onSuspend.addListener(
  callback: function,
)

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

callback
function
The callback parameter looks like: () => void

onSuspendCanceled

chrome.runtime.onSuspendCanceled.addListener(
  callback: function,
)

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

Parameters

callback
function
The callback parameter looks like: () => void

onUpdateAvailable

chrome.runtime.onUpdateAvailable.addListener(
  callback: function,
)

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(). If your extension is using a persistent background page, the background page of course never gets unloaded, so unless you call chrome.runtime.reload() manually in response to this event the update will not get installed until the next time Chrome itself restarts. If no handlers are listening for this event, and your extension has a persistent background page, it behaves as if chrome.runtime.reload() is called in response to this event.

Parameters

callback
function
The callback parameter looks like: (details: object) => void
- details
  object
  - version
    string
    The version number of the available update.

chrome.runtime

# Manifest

# Examples

# Use getURL to add an extension image to a page

# Getting background data into a content script

# Gathering feedback on uninstall

Summary

Types

MessageSender

Properties

OnInstalledReason

Type

OnRestartRequiredReason

Type

PlatformArch

Type

PlatformInfo

Properties

PlatformNaclArch

Type

PlatformOs

Type

Port

Properties

RequestUpdateCheckStatus

Type

Properties

id

Type

lastError

Type

Properties

Methods

connect

Parameters

Returns

connectNative

Parameters

Returns

getBackgroundPage

Parameters

getManifest

Returns

getPackageDirectoryEntry

Parameters

getPlatformInfo

Parameters

getURL

Parameters

Returns

openOptionsPage

Parameters

reload

requestUpdateCheck

Parameters

restart

restartAfterDelay

Parameters

sendMessage

Parameters

sendNativeMessage

Parameters

setUninstallURL

Parameters

Events

onBrowserUpdateAvailable

Parameters

onConnect

Parameters

onConnectExternal

Parameters

onConnectNative

Parameters

onInstalled

Parameters

onMessage

Parameters

onMessageExternal

Parameters

onRestartRequired

Manifest

Examples

Use `getURL` to add an extension image to a page

Getting background data into a content script

Gathering feedback on uninstall