Google Chrome Extensions

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

Types

MessageSender

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

Properties of MessageSender

tab ( optional tabs.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.

Properties of Port

name ( string )
onDisconnect ( events.Event )
onMessage ( events.Event )
postMessage ( function )
sender ( optional MessageSender )
This property will only be present on ports passed to onConnect/onConnectExternal listeners.

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.

Properties of lastError

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. Note that this does not connect to any listeners in a content script. 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 )
name ( optional string )
Will be passed into onConnect for extension processes that are listening for the connection event.

sendMessage

chrome.extension.sendMessage(string extensionId, any message)

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 extension page of the extension. Note that extensions cannot send messages to content scripts using this method. To send messages to content scripts, use chrome.tabs.sendMessage().

Parameters

extensionId ( optional string )
The extension ID of the extension you want to connect to. If omitted, default is your own extension.
message ( any )

Callback function

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 chrome.extension.lastError will be set to the error message.

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.

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

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.

isAllowedIncognitoAccess

chrome.extension.isAllowedIncognitoAccess()

Retrieves the state of the extension's access to Incognito-mode (as determined by the user-controlled 'Allowed in Incognito' checkbox.

isAllowedFileSchemeAccess

chrome.extension.isAllowedFileSchemeAccess()

Retrieves the state of the extension's access to the 'file://' scheme (as determined by the user-controlled 'Allow access to File URLs' checkbox.

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 )

Events

onConnect

chrome.extension.onConnect.addListener(function(Port port) {...});

Fired when a connection is made from either an extension process or a content script.

Listener Parameters

port ( Port )

onConnectExternal

chrome.extension.onConnectExternal.addListener(function(Port port) {...});

Fired when a connection is made from another extension.

Listener Parameters

port ( Port )

onMessage

chrome.extension.onMessage.addListener(function(any message, MessageSender sender) {...});

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.
sender ( MessageSender )

Callback function

The sendResponse parameter should specify a function that looks like this: 

function() {...};

onMessageExternal

chrome.extension.onMessageExternal.addListener(function(any message, MessageSender sender) {...});

Fired when a message is sent from another extension.

Listener Parameters

message ( any )
The message sent by the calling script.
sender ( MessageSender )

Callback function

The sendResponse parameter should specify a function that looks like this: 

function() {...};

Sample Extensions that use chrome.extension

  • Context Menus Sample – Shows some of the features of the Context Menus API
  • Context Menus Sample (with Event Page) – Shows some of the features of the Context Menus API using an event page
  • Cookie API Test Extension – Testing Cookie API
  • Live HTTP headers – Displays the live log with the http requests headers
  • JavaScript pause/resume – Pauses / resumes JavaScript execution
  • Event Page Example – Demonstrates usage and features of the event page
  • `extension.isAllowedFileSchemeAccess` and `extension.isAllowedIncognitoAccess` Example – Demonstrates the `extension.isAllowedFileSchemeAccess` and `extesion.isAllowedIncognitoAccess` APIs
  • Idle - Simple Example – Demonstrates the Idle API
  • Message Timer – Times how long it takes to send a message to a content script and back.
  • Block/allow third-party cookies API example extension – Sample extension which demonstrates how to access a preference.
  • Block/allow referrer API example extension – Sample extension which demonstrates how to access a preference.
  • Speech Recognizer – Recognizes your speech and tells you the most likely result.
  • Stylizr – Spruce up your pages with custom CSS.
  • Tab Inspector – Utility for working with the extension tabs api
  • Test Screenshot Extension – Demonstrate screenshot functionality in the chrome.tabs api. Note: only works for code.google.com
  • Console TTS Engine – A "silent" TTS engine that prints text to a small window rather than synthesizing speech.
  • App Launcher –
  • Page Benchmarker – Chromium Page Benchmarker.
  • Chromium Buildbot Monitor – Displays the status of the Chromium buildbot in the toolbar. Click to see more detailed status in a popup.
  • Google Calendar Checker (by Google) – Quickly see the time until your next meeting from any of your calendars. Click on the button to be taken to your calendar.
  • Catifier – Moar cats!
  • Email this page (by Google) – This extension adds an email button to the toolbar which allows you to email the page link using your default mail client or Gmail.
  • Chrome Sounds – Enjoy a more magical and immersive experience when browsing the web using the power of sound.
  • Google Document List Viewer – Demonstrates how to use OAuth to connect the Google Documents List Data API.
  • Google Mail Checker – Displays the number of unread messages in your Google Mail inbox. You can also click the button to open your inbox.
  • Mappy – Finds addresses in the web page you're on and pops up a map window.
  • News Reader (by Google) – Displays the latest stories from Google News in a popup.
  • Sample - OAuth Contacts – Uses OAuth to connect to Google's contacts service and display a list of your contacts.
  • Per-plugin content settings – Customize your content setting for different plug-ins.
  • Proxy Extension API Sample – Set Chrome-specific proxies; a demonstration of Chrome's Proxy API
  • Speak Selection – Speaks the current selection out loud.
  • Talking Alarm Clock – A clock with two configurable alarms that will play a sound and speak a phrase of your choice.
  • TTS Demo – Demo Chrome's synthesized text-to-speech capabilities.