chrome.extension
The chrome.extension module
has utilities that can be used by any extension page.
It includes support for exchanging messages
between an extension and its content scripts
or between extensions,
as described in detail in
Message Passing.
Support for content scripts
Unlike the other chrome.* APIs,
parts of chrome.extension
can be used by content scripts:
-
sendMessage() and
onMessage
-
Simple communication with extension pages
-
connect() and
onConnect
-
Extended communication with extension pages
-
getURL()
-
Access to extension resources such as image files
For details, see
Content Scripts.
API reference: chrome.extension
Properties
lastError
chrome.extension.lastError
lastError
(
optional
object
)
Set for the lifetime of a callback if an ansychronous extension api has resulted in an error. If no error has occured lastError will be undefined.
-
message
(
string
)
- Description of the error that has taken place.
inIncognitoContext
chrome.extension.inIncognitoContext
inIncognitoContext
(
optional
boolean
)
True for content scripts running inside incognito tabs, and for extension pages running inside an incognito process. The latter only applies to extensions with 'split' incognito_behavior.
Methods
connect
Port
chrome.extension.connect(string
extensionId, object
connectInfo)
Attempts to connect to other listeners within the extension (such as the extension's background page). This is primarily useful for content scripts connecting to their extension processes. Extensions may connect to content scripts embedded in tabs via chrome.tabs.connect().
Parameters
-
extensionId
(
optional
string
)
- The extension ID of the extension you want to connect to. If omitted, default is your own extension.
-
connectInfo
(
optional
object
)
-
Undocumented.
-
-
name
(
optional
string
)
- Will be passed into onConnect for extension processes that are listening for the connection event.
Returns
-
- Port through which messages can be sent and received with the extension. The port's onDisconnect event is fired if extension does not exist.
getBackgroundPage
global
chrome.extension.getBackgroundPage()
Returns the JavaScript 'window' object for the background page running inside the current extension. Returns null if the extension has no background page.
Returns
getURL
string
chrome.extension.getURL(string
path)
Converts a relative path within an extension install directory to a fully-qualified URL.
Parameters
-
path
(
string
)
- A path to a resource within an extension expressed relative to its install directory.
Returns
-
(
string
)
- The fully-qualified URL to the resource.
getViews
array of global
chrome.extension.getViews(object
fetchProperties)
Returns an array of the JavaScript 'window' objects for each of the pages running inside the current extension.
Parameters
-
fetchProperties
(
optional
object
)
-
Undocumented.
-
-
type
(
optional
enumerated
string
["tab", "infobar", "notification", "popup"]
)
- The type of view to get. If omitted, returns all views (including background pages and tabs). Valid values: 'tab', 'infobar', 'notification', 'popup'.
-
windowId
(
optional
integer
)
- The window to restrict the search to. If omitted, returns all views.
Returns
-
(
array of
global
)
- Array of global objects
isAllowedFileSchemeAccess
chrome.extension.isAllowedFileSchemeAccess(function
callback)
Retrieves the state of the extension's access to the 'file://' scheme (as determined by the user-controlled 'Allow access to File URLs' checkbox.
Parameters
-
callback
(
function
)
-
Undocumented.
This function was added in version 12.0.706.0.
If you require this function, the manifest key
minimum_chrome_version
can ensure that your extension won't be run in an earlier browser version.
isAllowedIncognitoAccess
chrome.extension.isAllowedIncognitoAccess(function
callback)
Retrieves the state of the extension's access to Incognito-mode (as determined by the user-controlled 'Allowed in Incognito' checkbox.
Parameters
-
callback
(
function
)
-
Undocumented.
This function was added in version 12.0.706.0.
If you require this function, the manifest key
minimum_chrome_version
can ensure that your extension won't be run in an earlier browser version.
sendMessage
chrome.extension.sendMessage(string
extensionId, any
message, function
responseCallback)
Sends a single message to other listeners within the extension. Similar to chrome.extension.connect, but only sends a single message with an optional response. The chrome.extension.onMessage event is fired in each page of the extension.
Parameters
-
extensionId
(
optional
string
)
- The extension ID of the extension you want to connect to. If omitted, default is your own extension.
-
message
(
any
)
-
Undocumented.
-
responseCallback
(
optional
function
)
-
Undocumented.
-
Parameters
-
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 chrome.extension.lastError will be set to the error message.
setUpdateUrlData
chrome.extension.setUpdateUrlData(string
data)
Sets the value of the ap CGI parameter used in the extension's update URL. This value is ignored for extensions that are hosted in the Chrome Extension Gallery.
Parameters
-
data
(
string
)
-
Undocumented.
Events
onConnect
chrome.extension.onConnect.addListener(function(Port port) {...});
Fired when a connection is made from either an extension process or a content script.
onConnectExternal
chrome.extension.onConnectExternal.addListener(function(Port port) {...});
Fired when a connection is made from another extension.
onMessage
chrome.extension.onMessage.addListener(function(object details) {...});
Fired when a message is sent from either an extension process or a content script.
Listener parameters
-
details
(
object
)
-
Undocumented.
-
-
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).
Listener returns
-
(
optional
boolean
)
- Return true from the event listener if you wish to call
sendResponse after the event listener returns.
onMessageExternal
chrome.extension.onMessageExternal.addListener(function(object details) {...});
Fired when a message is sent from another extension.
Listener parameters
-
details
(
object
)
-
Undocumented.
-
-
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).
Listener returns
-
(
optional
boolean
)
- Return true from the event listener if you wish to call
sendResponse after the event listener returns.
Types
MessageSender
(
object
)
An object containing information about the script context that sent a message or request.
-
tab
- This property will only be present when the connection was opened from a tab or content script.
-
id
(
string
)
- The extension ID of the extension that opened the connection.
Port
(
object
)
An object which allows two way communication with other pages.
-
name
(
string
)
-
Undocumented.
-
onDisconnect
-
Undocumented.
-
postMessage
(
function
)
-
Undocumented.
-
sender
- This property will only be present on ports passed to onConnect/onConnectExternal listeners.
