Ghost Browser API

We released the first version of Ghost Browser's public API on June 24, 2020, which can be used to allow browser extensions to talk to Ghost Browser's tabs and Identities.

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

Please note that as of December 2020, "Sessions" were renamed "Temporary Identities". To learn more about Temporary Identities please click here.

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, or in the Getting IDs Programmatically section below.) An empty string value equals the Default Identity identifier. There are 2 named constants in ghostPublicAPI scope, as follows:

NEW_TEMPORARY_IDENTITY will open a tab in a new Temporary Identity

DEFAULT_IDENTITY will open a tab in the Default Identity (Note: please use this constant instead of an empty string value whenever you work with the Default Identity identifier)

Please refer to the API Example 2 at the end of the article.

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.

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 Identity IDs programmatically

Currently we do not have a UI to see/copy Temporary Identity IDs (due to the dynamic nature of Temporary Identities and their dependency on Workspaces.) To help alleviate this, we've created a way to help determine an 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.identity_id [string] - Identity ID the tab belongs to.
ghostPublicAPI.is_temporary_identity [boolean] - true if it's a Temporary Identity, false otherwise.

If a tab is opened in the Default Identity, its identity_id will be equal to ghostPublicAPI.DEFAULT_IDENTITY constant value.

Please refer to the API Example 3 at 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 MyIdentity (using its ID) at 3rd position and in background mode.

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

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

chrome.ghostPublicAPI.openTab(
  { url: "http://somesite",
    identity: chrome.ghostPublicAPI.NEW_TEMPORARY_IDENTITY}
)

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

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