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 a GUID value in string format. Empty string value means Global Session ID. 

There are 2 named constants in ghostPublicAPI scope, as follows:

  • NEW_SESSION will open a tab in a new Session
  • GLOBAL_SESSION will open a tab in a Global Session
The above modifies the older version of the API (Ghost Browser version prior 2.1.1.16) which used the following DEPRECATED MODEL.

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:
    NEW_SESSION = -1 will open a tab in a new Session
    GLOBAL_SESSION = 0 will open a tab in a Global Session
    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.

Getting Session IDs

Currently we do not have an UI to see/copy Session ID (due to the dynamic nature of Sessions and Sessions' dependency on Workspaces. To help alleviate this, we've created a way to help determine a Session/Identity in which a foreground Tab (or any other Tab) was opened. To achieve this, we've extended chrome’s Tab object (see chrome.tabs extensions API for Tab object definition and functions working with it) with the “ghostPublicAPI” property that has the following structure:

  • ghostPublicAPI.workspace_id [string] - Workspace ID the tab opened in.
  • ghostPublicAPI.session_id [optional, string] - Session ID the tab belongs too.
  • ghostPublicAPI.identity_id [optional, string] - Identity ID the tab belongs too.

While workspace_id is always presented. It can have only session_id or identity_id property at a time based on Tab belongs to a Session or to an Identity. If Tab opened in a Global Session, session_id will exist but will be an empty string.

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