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 string type GUID value. Empty string value means Global Session identifier. 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

Please, have a look at the API Example 2 in the end of the article.
Note: Prior to Ghost Browser 2.1.1.16 session was an Integer value with the range of -1,0,1,2,...,25

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.active - "true" opens the tab as the active tab. “false” opens the tab as an inactive or background tab. "true" is the default.

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. 

Getting Session or Identity IDs programmatically

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.

Please, have a look at the API Example 3 in the end of the article.

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

Example 3: Display Session or Identity ID for active tab of current window

chrome.tabs.query({active: true, currentWindow: true},  function(tabs) {
     if (tabs[0].ghostPublicAPI.identity_id) {
         alert("Tab opened in Identity with ID: " + tabs[0].ghostPublicAPI.identity_id)
     } else {
         alert("Tab opened in Session with ID: " + tabs[0].ghostPublicAPI.session_id);
     }
 })