Google Chrome Extensions
About
Extensions are small event-based software programs that tailor the functionality and behavior of the Google Chrome browser.
Extensions are built with HTML, JavaScript, and CSS, and work by listening for events, or browser triggers, such as clicking the extension icon, navigating to a new page, downloading a file, removing a bookmark, or closing a tab. Extensions monitor these events and when they happen, react with specified instructions.
All file assets for an extension are zipped into a single .crx
package that users download and install. This means extensions do not depend on content from the web, unlike ordinary web apps.
A Chrome extension consists of three parts:
- Popup
The UI seen when the icon for the extension is clicked. - Content Scripts
Scripts that run on top of existing web pages. - Background Scripts
Scripts that run in the background of Google Chrome.
These individual parts live in their own scopes. They are fully sandboxed, have no knowledge of one another and, as a result, cannot directly access each other. However, information can be passed between the parts via the Chrome API.
- Chrome Extensions Documentation
- Chrome Extensions Developer Documentation
- Chrome Extension Components
- Chrome APIs
Project Directory
Extensions which are in development keep their files in a project directory which can reside anywhere on the development system.
The only required file is manifest.json
, all other extension files can be named anything and can exist directly in the project directory or in any directory beneath it.
manifest.json File
https://chrome-apps-doc2.appspot.com/extensions/manifest.html
The manifest.json
file sits in the root of the project directory and defines the settings and file paths for scripts and other files used by the extension.
For security, in-line JavaScript is forbidden. All JavaScripts must be placed in a .js
file somewhere under the project directory and referenced in the manifest.json
file.
Extension Manager Page
Extensions which are in development need to be refreshed each time a change is made. Extensions can be loaded, unloaded and refreshed from the Extension Manager page.
Go to the extension manager page in the Chrome browser: chrome://extensions/
To load the extension into Chrome, click the Load unpacked button and when prompted, navigate to the extensions local project directory.
While developing, if changes are made, the extension needs to be reloaded from this page using the refresh button. Any extension errors can also be found here.
Sometimes critical errors cause the extension to lock-up or break, and may need to be unloaded, and then loaded again to clear all of its parts from memory.
General Info
The most basic extension requires only that a manifest.json
file exist in the root of its project directory. The name
, version
, and manifest_version
keys are the only required setting in the file:
{
"manifest_version": 2,
"name": "Example Chrome Extension",
"version": "1.0"
}
Property | Description |
---|---|
manifest_version |
Required: Which version of the manifest file is the extension using? |
name |
Required: The name of the extension. |
version |
Required: The version number of the extension. |
description |
Optional: A brief plain-text description of the extension. |
default_locale |
Optional: en is the default. |
icons |
Optional: The file paths to one or more icons that represent the extension. |
Popup
https://developers.chrome.com/extensions/user_interface#popup
https://developers.chrome.com/extensions/browserAction
https://developers.chrome.com/extensions/pageAction
The Popup is the UI which opens when the icon for the extension is clicked. The popup window content is a fully-realized webpage and automatically sized to fit its contents. It’s built with HTML, CSS and JavaScript. The only difference between a webpage and a Chrome extension popup, is that the HTML file must be registered in the manifest.json
file.
Note: Each time the popup is closed, it’s as if the webpage were closed, everything that was stored in memory is lost.
browser_action
The Popup is managed by the chrome.browserAction API. Settings are defined under the browser_action
key in the manifest.json
file.
{
"name": "My extension",
...
"browser_action": {
"default_icon": { // optional. Icons specific to the toolbar.
"16": "images/icon16.png", // optional
"24": "images/icon24.png", // optional
"32": "images/icon32.png", // optional
"128": "images/icon128.png" // optional
},
"default_title": "Google Mail", // optional; shown in tooltip
"default_popup": "popup.html" // optional
},
...
}
Property | Description |
---|---|
default_popup |
The HTML file to open as the UI when the extension icon is clicked. |
default_icon |
Icons specific to the toolbar. Including multiple sizes is encouraged. At minimum, 16×16 and 32×32 sizes are recommended. |
default_title |
The tooltip or rollover text of the extension icon. |
Including multiple sizes is encouraged to scale for the 16-dip space. At minimum, 16×16 and 32×32 sizes are recommended.
popup.html
<!doctype html>
<html>
<head>
<title>My extension</title>
<script src="js/popup.js"></script>
<link rel="stylesheet" type="text/css" href="css/popup.css">
</head>
<body>
<h1>My extension</h1>
Hello, World!
</body>
</html>
Icon Badges
Browser actions can optionally display a badge — a bit of text that is layered over the icon. Badges make it easy to update the browser action to display a small amount of information about the state of the extension.
Content Scripts
https://developer.chrome.com/extensions/content_scripts
Content Scripts contain JavaScript that executes in the contexts of a page that has been loaded into the browser, as if they were shipped with the website itself.
These scripts have access to everything in the DOM. They can read and write to web pages
content_scripts
content_scripts
defines the URLs on which the extensions JavaScript and CSS files are injected by the extension. By using the DOM, injected JavaScripts are able to read details of the web pages the browser visits, make changes to them and pass information to their parent extension.
"content_scripts": [
{
"matches": ["<all_urls>"],
"css": ["background.css"],
"js": ["background.js"]
}
],
Property | Description |
---|---|
matches |
Required: array of strings Specifies which URLs this content script will be injected into. To inject on all sites: "matches": ["<all_urls>"] Regex can be used for URL values. To inject on a single site, like Twitter for example: "matches": ["https://twitter.com/*"] Chrome will grey-out the extension icon when it’s inactive. |
css |
Optional: array of strings The list of CSS files to be injected into matching pages. These are injected in the order they appear in this array, before any DOM is constructed or displayed for the page. |
js |
Optional: array of strings The list of JavaScript files to be injected into matching pages. These are injected in the order they appear in this array. |
match_about_blank |
Optional: boolean Whether the script should inject into an about:blank frame where the parent or opener frame matches one of the patterns declared in matches. Defaults to false. |
Background Scripts
background
"background": {
"scripts": ["background.js"],
"persistent": false
},
Permissions
https://developer.chrome.com/extensions/declare_permissions
Many of the APIs Chrome exposes for extensions require permissions. Most APIs must be registered under the “permissions” field in the manifest for the extension to use them.
The permissions needed depend on what the extension needs to do.
Permission | Description |
---|---|
activeTab |
Required to get the URL of the current tab. |
"permissions": [
"activeTab"
]
Chrome APIs
https://developers.chrome.com/extensions/api_index
https://developers.chrome.com/extensions/devguide
Scripts can tap-in to the browser functionality and behavior using the Chrome APIs.
Most APIs must be registered under the “permissions” field in manifest.json
for the extension to use them.
API | Description |
---|---|
Messages | The Messaging API contains all the methods used for the exchange of messages within the extension ecosystem and doesn’t require any permissions. |
Tabs | The Tabs API allows you to interact with all the tabs that a particular chrome window has opened. |
Examples
Open the popup with a keyboard shortcut
Place in the root of the
"commands": {
"_execute_browser_action": {
"suggested_key": {
"default": "Ctrl+Shift+F",
"mac": "MacCtrl+Shift+F"
},
"description": "Opens the extension popup"
}
}