Types
Port
An object which allows two way communication with other pages.
properties of Port
-
sender
(
optional
MessageSender
)
-
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.
-
tab
(
optional
tabs.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.
-
id
(
optional
string
)
-
The ID of the extension or app that opened the connection, if any.
-
url
(
optional
string
)
-
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.
Properties
lastError
chrome.runtime.lastError
lastError ( )
This will be defined during an API method callback if there was an error
-
message
(
optional
string
)
-
Details about the error which occurred.
id
chrome.runtime.id
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
Callback
The callback parameter should specify a function
that looks like this:
function(window backgroundPage) {...};
-
backgroundPage
(
optional
window
)
-
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.
Properties of return type
getURL
string chrome.runtime.getURL(string 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.
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
reload
chrome.runtime.reload()
Reloads the app or extension.
requestUpdateCheck
chrome.runtime.requestUpdateCheck(function callback)
Requests an update check for this app/extension.
Parameters
Callback
The callback parameter should specify a function
that looks like this:
function(enum of "throttled", "no_update", or "update_available" status, object details) {...};
-
status
(
enum of
"throttled", "no_update", or "update_available"
)
-
Result of the update check.
-
details
(
optional
object
)
-
If an update is available, this contains more information about the available update.
-
-
version
(
string
)
-
The version of the available update.
connect
Port chrome.runtime.connect(
string extensionId,
object connectInfo)
Attempts to connect to other listeners within the extension/app (such as the background page), or other extensions/apps. This is useful for content scripts connecting to their extension processes. 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
(
optional
string
)
-
The ID of the extension/app you want to connect to. If omitted, default is your own extension.
-
connectInfo
(
optional
object
)
-
-
name
(
optional
string
)
-
Will be passed into onConnect 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
-
application
(
string
)
-
The name of the registered application to connect to.
sendMessage
chrome.runtime.sendMessage(string extensionId, any message, function responseCallback)
Sends a single message to onMessage event listeners within the extension (or another extension/app). Similar to chrome.runtime.connect, but only sends a single message with an optional response. The onMessage event is fired in each extension page of the extension. Note that extensions cannot send messages to content scripts using this method. To send messages to content scripts, use tabs.sendMessage.
Parameters
-
extensionId
(
optional
string
)
-
The extension ID of the extension you want to connect to. If omitted, default is your own extension.
-
responseCallback
(
optional
function
)
Callback
If you specify the responseCallback parameter, it should
specify a function that looks like this:
function(any response) {...};
-
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 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
-
application
(
string
)
-
The name of the native messaging host.
-
message
(
object
)
-
The message that will be passed to the native messaging host.
-
responseCallback
(
optional
function
)
Callback
If you specify the responseCallback parameter, it should
specify a function that looks like this:
function(any response) {...};
-
response
(
any
)
-
The response message send 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.
chrome.runtime.getPlatformInfo(function callback)
Returns information about the current platform.
Parameters
-
callback
(
function
)
-
Called with results
Callback
The callback parameter should specify a function
that looks like this:
function(object platformInfo) {...};
-
platformInfo
(
object
)
-
-
os
(
enum of
"mac", "win", "android", "cros", "linux", or "openbsd"
)
-
The operating system chrome is running on.
-
arch
(
enum of
"arm", "x86-32", or "x86-64"
)
-
The machine's processor architecture.
-
nacl_arch
(
enum of
"arm", "x86-32", or "x86-64"
)
-
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
Callback
The callback parameter should specify 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
Callback
The callback parameter should specify 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
Callback
The callback parameter should specify a function
that looks like this:
function(object details) {...};
-
details
(
object
)
-
-
reason
(
enum of
"install", "update", or "chrome_update"
)
-
The reason that this event is being dispatched.
-
previousVersion
(
optional
string
)
-
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
Callback
The callback parameter should specify 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
Callback
The callback parameter should specify 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
Callback
The callback parameter should specify a function
that looks like this:
function(object details) {...};
-
details
(
object
)
-
The manifest details of the available update.
-
-
version
(
string
)
-
The version number of the available update.
onConnect
Fired when a connection is made from either an extension process or a content script.
addListener
chrome.runtime.onConnect.addListener(function callback)
Parameters
Callback
The callback parameter should specify a function
that looks like this:
function(Port port) {...};
onConnectExternal
Fired when a connection is made from another extension.
addListener
chrome.runtime.onConnectExternal.addListener(function callback)
Parameters
Callback
The callback parameter should specify a function
that looks like this:
function(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
Callback
The callback parameter should specify a function
that looks like this:
function(any message, MessageSender sender, function sendResponse) {...};
-
message
(
optional
any
)
-
The message sent by the calling script.
-
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).
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
Callback
The callback parameter should specify a function
that looks like this:
function(any message, MessageSender sender, function sendResponse) {...};
-
message
(
optional
any
)
-
The message sent by the calling script.
-
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).
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
Callback
The callback parameter should specify a function
that looks like this:
function(enum of or "app_update"or "os_update"or "periodic" reason) {...};
-
reason
(
enum of or
"app_update"or "os_update"or "periodic"
)
-
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.
chrome