BackgroundManager

Contents

1. Description
2. How is it enabled?
3. What does "persistent" property do?
4. Chrome API(s) available to background page
5. Permissions
6. Overview of BackgroundManager

Description

The BackgroundManager exists in the background page of the google chrome extension. Only ONE instance of the background page (Another instance of the background page would be spawned for pages in incognito mode) will exist for the lifetime of an extension until it is terminated by disabling the extension or closing all chrome browser instances. The BackgroundManager's role in the extension is to listen for url changes in the chrome tabs and inform content scripts using chrome message passing API once Github urls are detected.

How is it enabled?

By adding an entry like shown below to the manifest file:

"background": {
    "scripts": [ "src/background-scripts/backgroundscript.js" ],
    "persistent": false
}

For other ways of registering the background page in the extension's manifest, you can visit https://developer.chrome.com/extensions/background_pages#manifest

What does "persistent" property do?

There are two types of background pages, namely the event page and persistent page.

Persistent page

If the persistent property is set to true (or not set at all because it is the default), the background page would be a persistent page and thus will always be active.

Event page

If the persistent property is set to false, the background page would be an event page and therefore will only become active when an event occurred (if there are no events happening, the background page goes back to idle). The event page is often preferred because it is inactive most of the time and so it helps conserve limited browser resources.

Does that mean persistent pages are bad?

Although event pages are preferred, that does not mean that persistent pages does not have its merits because persistent pages is helpful in quickly obtaining the background page from other non-background scripts (for calling functions and retrieving data from the background page) when using the getBackgroundPage() API.

Chrome API(s) available to background page

Some Chrome API(s) include:

chrome.tabs API
chrome.webNavigation API
...

To learn more, visit https://developer.chrome.com/extensions/api_index . Occasionally, there may be situations when you need to invoke some chrome API(s) from non-background scripts but will be unable to do so because there exist some privileged chrome API(s) that can only be invoked from the background page and thus the proper way to call those functions would be to invoke them in the background page and pass the data to the non-background scripts using chrome message passing API.

Permissions

Before using most of chrome's API, you must declare permissions needed in the extension's manifest like shown below:

"permissions": [ "tabs",
                 "https://github.com/*", 
                 "http://github.com/*" ]

To learn more about permissions, visit https://developer.chrome.com/extensions/declare_permissions

Overview of BackgroundManager

1. The BackgroundManager attaches a url event listener using:

   chrome.tabs.onUpdated.addListener(this.handleUrlChange.bind(this));

2. When the url of a tab changes, the handleUrlChange(tabId, changeInfo, tab) function is called. A preview of the handleUrlChange function is shown below:

   if(tab && tab.status === "complete" && this.isGithubUrl(tab.url)){
       chrome.tabs.sendMessage(tabId, {});
   }

3. Within the handleUrlChange() function, it checks to see if the page is completely loaded using the tab.status variable and checking the url in tab.url using the following regex:

   ^https?:\/\/github\.com(\/.*$|$)+

4. If conditions are met as shown in the code in step 2, the BackgroundManager will send a notification message to the content script asking it to run on the current page residing in the tab with tabId using the chrome.tabs.sendMessage API.

Note: In order to use the chrome.tabs API, the tabs permission must be registered in the manifest