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 ( string )
- The ID of the extension or app that opened the connection.
- url ( optional string )
- The URL of the page or frame that opened the connection. This property will only be present when the connection was opened from a tab (including content scripts).
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(global backgroundPage) {...};
-
backgroundPage
(
optional
global
)
-
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.
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.
Events
onStartup
chrome.runtime.onStartup.addListener(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.
onInstalled
chrome.runtime.onInstalled.addListener(function(object details) {...});
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.
Listener Parameters
- 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
chrome.runtime.onSuspend.addListener(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.
onSuspendCanceled
chrome.runtime.onSuspendCanceled.addListener(function() {...});
Sent after onSuspend to indicate that the app won't be unloaded after all.
onUpdateAvailable
chrome.runtime.onUpdateAvailable.addListener(function(object details) {...});
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().
Listener Parameters
- details ( object )
- The manifest details of the available update.
-
- version ( string )
- The version number of the available update.
onBrowserUpdateAvailable
chrome.runtime.onBrowserUpdateAvailable.addListener(function() {...});
Fired when a Chrome update is available, but isn't installed immediately because a browser restart is required.
onConnect
chrome.runtime.onConnect
.addListener(function(
Port port)
{...});
Fired when a connection is made from either an extension process or a content script.
Listener Parameters
onConnectExternal
chrome.runtime.onConnectExternal
.addListener(function(
Port port)
{...});
Fired when a connection is made from another extension.
Listener Parameters
onMessage
chrome.runtime.onMessage
.addListener(function(
any message,
MessageSender sender,
function sendResponse)
{...});
Fired when a message is sent from either an extension process or a content script.
Listener Parameters
- message ( 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).
Callback
The sendResponse parameter should specify a function
that looks like this:
function() {...};
onMessageExternal
chrome.runtime.onMessageExternal
.addListener(function(
any message,
MessageSender sender,
function sendResponse)
{...});
Fired when a message is sent from another extension/app. Cannot be used in a content script.
Listener Parameters
- message ( 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).
Callback
The sendResponse parameter should specify a function
that looks like this:
function() {...};
chrome extensions