Ghost Browser API

We released our first version of our public API on June 24, 2020, which can be used to allow browser extensions talk to our Sessions and Identities. 

The first version of the API will allow extension developers to open tabs with a specific URL into a specific Session or Identity or into a new Session using the openTab function

openTab Function

chrome.ghostPublicAPI.openTab(OpenTabParams, callback)

OpenTabParams consists of the following properties, all of which are optional.

url - URL to open
identity - the ID of the Identity in which the tab should be opened. (The Identity can be found in the Identity Manager interface as shown below)
session - Session identifier - it is an integer with a value of -1, 0, 1, 2, …, 25. There are three named constants in ghostPublicAPI scope, as follows:

  1. NEW_SESSION = -1 will open a tab in a new Session
  2. GLOBAL_SESSION = 0 will open a tab in a Global Session
  3. MAX_SESSION = 25 to open tab in session with maximum possible identifier

active - "true" opens the tab as the active tab. “false” opens the tab as an inactive or background tab. "true" is the default.
index - insert tab at a specific index in the active window (if possible) to set the position in the browser the tab will be opened into. Use "0" to set it as the first tab, "1" to set it after the first tab, etc.
pinned - open the tab in a pinned state.
callback - this returns the tab_id as an argument when the call is successful. This tab_id can then be used to access and control any tab using the standard extensions API.

Notes

Using 'index' parameter with pinned tabs

The index parameter counts tabs from left to right and places your tab in the appropriate location based on that count. However, this placement is subservient to the rule that pinned tabs are always placed before unpinned tabs. Therefore, if you have pinned tabs, or explicitly set the pinned state, it may affect the placement of your tab. For example, If you have 5 pinned tabs open and set a tab to open with 'pinned=false' and an index of 2, the new tab will not be placed after the 2nd tab. Normally, it would but because the 2nd and 3rd tabs are pinned, your new unpinned tab is forced to a position to the right of all of the pinned tabs.

Call Session or Identity, not Both

A tab can either be a Session tab or an Identity tab, but it can't be both. If you add both parameters in an operation it will throw an error. 

Finding the ID of Your Identities

To find an Identity ID, please open the Identity Manager. You will find the ID at the top of the screen where you can edit your Identity. 

Checking your extension executes in Ghost Browser

If you develop a cross-browser extension you can use the following condition to check whether your code is running in Ghost Browser

typeof chrome.ghostPublicAPI !== 'undefined'

For example, execution of openTab function may look like this:

if (typeof chrome.ghostPublicAPI !== 'undefined') {
    chrome.ghostPublicAPI.openTab(OpenTabParams, callback);
}

API Examples

Example 1: Open a new tab in MyIdentity1 at 3rd position and in background mode.

chrome.ghostPublicAPI.openTab(
  { url: "http://somesite",
    index: 2, 
    active: false, 
    identity: "MyIdentity1"},
  function(tab_id) {
      console.log(tab_id)
  }
)

Example 2: Open some site in a new tab with a new Session.

chrome.ghostPublicAPI.openTab(
  { url: "http://somesite",
    session: chrome.ghostPublicAPI.NEW_SESSION}
)