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.
Summary
- Types
- Properties
- Methods
chrome.runtime.connect(extensionId: string, connectInfo: object): Port
chrome.runtime.connectNative(application: string): Port
chrome.runtime.getBackgroundPage(callback: function)
chrome.runtime.getManifest(): object
chrome.runtime.getPackageDirectoryEntry(callback: function)
chrome.runtime.getPlatformInfo(callback: function)
chrome.runtime.getURL(path: string): string
chrome.runtime.openOptionsPage(callback: function)
chrome.runtime.reload()
chrome.runtime.requestUpdateCheck(callback: function)
chrome.runtime.restart()
chrome.runtime.restartAfterDelay(seconds: number, callback: function)
chrome.runtime.sendMessage(extensionId?: string, message: any, options: object, responseCallback: function)
chrome.runtime.sendNativeMessage(application: string, message: object, responseCallback: function)
chrome.runtime.setUninstallURL(url: string, callback: function)
- Events
Types
MessageSender
An object containing information about the script context that sent a message or request.
Properties
- frameIdnumber 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. - idstring optional
The ID of the extension or app that opened the connection, if any.
- nativeApplicationstring optional
The name of the native application that opened the connection, if any.
- originstring optional
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.
- tabtabs.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. - tlsChannelIdstring optional
The TLS channel ID of the page or frame that opened the connection, if requested by the extension or app, and if available.
- urlstring 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.
PlatformInfo
An object containing information about the current platform.
Properties
- arch
The machine's processor architecture.
- nacl_arch
The native client architecture. This may be different from arch on some platforms.
The operating system chrome is running on.
Port
An object which allows two way communication with other pages. See Long-lived connections for more information.
Properties
- disconnectfunction
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 this:
disconnect() => {...}
- namestring
The name of the port, as specified in the call to
connect
. - onDisconnectevents.Event<function>
Fired when the port is disconnected from the other end(s).
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 first and only parameter to the event handler is this disconnected port.Add a listener like this:
onDisconnect.addListener(listener)
- listenerfunction
The listener parameter should be a function that looks like this:
() => {...}
- onMessageevents.Event<function>
This event is fired when postMessage is called by the other end of the port. The first parameter is the message, the second parameter is the port that received the message.
Add a listener like this:
onMessage.addListener(listener)
- listenerfunction
The listener parameter should be a function that looks like this:
() => {...}
- postMessagefunction
Send a message to the other end of the port. If the port is disconnected, an error is thrown.
The postMessage function looks like this:
postMessage(message: any) => {...}
- messageany
The message to send. This object should be JSON-ifiable.
- senderMessageSender optional
This property will only be present on ports passed to onConnect / onConnectExternal / onConnectNative listeners.
OnInstalledReason
The reason that this event is being dispatched.
Enum
"install"
, "update"
, "chrome_update"
, or "shared_module_update"
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.
Enum
"app_update"
, "os_update"
, or "periodic"
PlatformArch
The machine's processor architecture.
Enum
"arm"
, "arm64"
, "x86-32"
, "x86-64"
, "mips"
, or "mips64"
PlatformNaclArch
The native client architecture. This may be different from arch on some platforms.
Enum
"arm"
, "x86-32"
, "x86-64"
, "mips"
, or "mips64"
PlatformOs
The operating system chrome is running on.
Enum
"mac"
, "win"
, "android"
, "cros"
, "linux"
, or "openbsd"
RequestUpdateCheckStatus
Result of the update check.
Enum
"throttled"
, "no_update"
, or "update_available"
Properties
id
The ID of the extension/app.
Type
lastError
This will be defined during an API method callback if there was an error
Properties
- messagestring optional
Details about the error which occurred.
Methods
connect
chrome.runtime.connect(extensionId: string, connectInfo: object): Port
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
- extensionIdstring
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.
- connectInfoobject
- includeTlsChannelIdboolean optional
Whether the TLS channel ID will be passed into onConnectExternal for processes that are listening for the connection event.
- namestring optional
Will be passed into onConnect for processes that are listening for the connection event.
Returns
- returns
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): Port
Connects to a native application in the host machine. See Native Messaging for more information.
Parameters
- applicationstring
The name of the registered application to connect to.
Returns
- returns
Port through which messages can be sent and received with the application
getBackgroundPage
chrome.runtime.getBackgroundPage(callback: function)
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
- callbackfunction
The callback parameter should be a function that looks like this:
(backgroundPage: Window) => {...}
- backgroundPageWindow
The JavaScript 'window' object for the background page.
getManifest
chrome.runtime.getManifest(): object
Returns details about the app or extension from the manifest. The object returned is a serialization of the full manifest file.
Returns
- returnsobject
The manifest details.
getPackageDirectoryEntry
chrome.runtime.getPackageDirectoryEntry(callback: function)
Returns a DirectoryEntry for the package directory.
Parameters
- callbackfunction
The callback parameter should be a function that looks like this:
(directoryEntry: DirectoryEntry) => {...}
- directoryEntryDirectoryEntry
getPlatformInfo
chrome.runtime.getPlatformInfo(callback: function)
Returns information about the current platform.
Parameters
- callbackfunction
Called with results
The callback parameter should be a function that looks like this:
(platformInfo: PlatformInfo) => {...}
- platformInfo
getURL
chrome.runtime.getURL(path: string): string
Converts a relative path within an app/extension install directory to a fully-qualified URL.
Parameters
- pathstring
A path to a resource within an app/extension expressed relative to its install directory.
Returns
- returnsstring
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
or options_page
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
- callbackfunction
The callback parameter should be a function that looks like this:
() => {...}
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 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
- callbackfunction
The callback parameter should be a function that looks like this:
(status: RequestUpdateCheckStatus, details: object) => {...}
- status
Result of the update check.
- detailsobject
If an update is available, this contains more information about the available update.
- versionstring
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)
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
- secondsnumber
Time to wait in seconds before rebooting the device, or -1 to cancel a scheduled reboot.
- callbackfunction
A callback to be invoked when a restart request was successfully rescheduled.
The callback parameter should be a function that looks like this:
() => {...}
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 connect
but only sends a single message, with an optional response. If sending to your extension, the onMessage
event will be fired in every frame of your extension (except for the sender's frame), 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 tabs.sendMessage
.
Parameters
- extensionIdstring 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.
- messageany
The message to send. This message should be a JSON-ifiable object.
- optionsobject
- includeTlsChannelIdboolean optional
Whether the TLS channel ID will be passed into onMessageExternal for processes that are listening for the connection event.
- responseCallbackfunction
The responseCallback function looks like this:
responseCallback(response: any) => {...}
- responseany
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
chrome.runtime.sendNativeMessage(application: string, message: object, responseCallback: function)
Send a single message to a native application.
Parameters
- applicationstring
The name of the native messaging host.
- messageobject
The message that will be passed to the native messaging host.
- responseCallbackfunction
The responseCallback function looks like this:
responseCallback(response: any) => {...}
- responseany
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.
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
- urlstring
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.
- callbackfunction
Called when the uninstall URL is set. If the given URL is invalid,
lastError
will be set.The callback parameter should be a function that looks like this:
() => {...}
Events
onBrowserUpdateAvailable
chrome.runtime.onBrowserUpdateAvailable.addListener(listener: function)
Fired when a Chrome update is available, but isn't installed immediately because a browser restart is required.
Event
- listenerfunction
Deprecated. Please use
onRestartRequired
.The listener parameter should be a function that looks like this:
() => {...}
onConnect
chrome.runtime.onConnect.addListener(listener: function)
Fired when a connection is made from either an extension process or a content script (by connect
).
onConnectExternal
chrome.runtime.onConnectExternal.addListener(listener: function)
Fired when a connection is made from another extension (by connect
).
onConnectNative
chrome.runtime.onConnectNative.addListener(listener: function)
Fired when a connection is made from a native application. Currently only supported on Chrome OS.
onInstalled
chrome.runtime.onInstalled.addListener(listener: 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.
Event
- listenerfunction
The listener parameter should be a function that looks like this:
(details: object) => {...}
- detailsobject
- idstring optional
Indicates the ID of the imported shared module extension which updated. This is present only if 'reason' is 'shared_module_update'.
- previousVersionstring optional
Indicates the previous version of the extension, which has just been updated. This is present only if 'reason' is 'update'.
- reason
The reason that this event is being dispatched.
onMessage
chrome.runtime.onMessage.addListener(listener: function)
Fired when a message is sent from either an extension process (by sendMessage
) or a content script (by tabs.sendMessage
).
Event
- listenerfunction
The listener parameter should be a function that looks like this:
(message: any, sender: MessageSender, sendResponse: function) => {...}
- messageany
The message sent by the calling script.
- sender
- sendResponsefunction
The sendResponse function looks like this:
sendResponse() => {...}
onMessageExternal
chrome.runtime.onMessageExternal.addListener(listener: function)
Fired when a message is sent from another extension/app (by sendMessage
). Cannot be used in a content script.
Event
- listenerfunction
The listener parameter should be a function that looks like this:
(message: any, sender: MessageSender, sendResponse: function) => {...}
- messageany
The message sent by the calling script.
- sender
- sendResponsefunction
The sendResponse function looks like this:
sendResponse() => {...}
onRestartRequired
chrome.runtime.onRestartRequired.addListener(listener: 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.
Event
- listenerfunction
The listener parameter should be a function that looks like this:
(reason: OnRestartRequiredReason) => {...}
- reason
The reason that the event is being dispatched.
onStartup
chrome.runtime.onStartup.addListener(listener: 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.
Event
- listenerfunction
The listener parameter should be a function that looks like this:
() => {...}
onSuspend
chrome.runtime.onSuspend.addListener(listener: 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.
Event
- listenerfunction
The listener parameter should be a function that looks like this:
() => {...}
onSuspendCanceled
chrome.runtime.onSuspendCanceled.addListener(listener: function)
Sent after onSuspend to indicate that the app won't be unloaded after all.
Event
- listenerfunction
The listener parameter should be a function that looks like this:
() => {...}
onUpdateAvailable
chrome.runtime.onUpdateAvailable.addListener(listener: 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.
Event
- listenerfunction
The listener parameter should be a function that looks like this:
(details: object) => {...}
- detailsobject
The manifest details of the available update.
- versionstring
The version number of the available update.