Ghost Browser API
The Ghost Browser API is primarily designed for extension developers and AI tools to interact with Ghost Browser's special features, such as Identities.
OpenTabParams
chrome.ghostPublicAPI.openTab(OpenTabParams, callback)
The OpenTabParams
object supports the following optional properties:
url
URL to open.
identity
The ID of the Identity in which the tab should be opened.
- The Identity ID can be found in the Identity Manager (see the section below) or in the "Getting IDs Programmatically" section.
- An empty string value equals the Default Identity identifier.
- There are 2 named constants in the
ghostPublicAPI
scope:- NEW_TEMPORARY_IDENTITY: Opens a tab in a new Temporary Identity.
DEFAULT_IDENTITY: Opens a tab in the Default Identity.
Note: Please use the
DEFAULT_IDENTITY
constant instead of an empty string when referring to the Default Identity.index
Insert the tab at a specific index in the active window (if possible) to control its position.
Use
"0"
to set it as the first tab,"1"
to set it after the first tab, etc.active
Controls whether the tab opens as the active tab.
"true"
opens the tab as active (default)."false"
opens the tab as inactive/background.
pinned
Opens the tab in a pinned state.
callback
A function that returns the
tab_id
as an argument when the call is successful. Thistab_id
can then be used to access and control the tab via the standard extensions API.
Note on the 'index' Parameter with Pinned Tabs
- The
index
parameter counts tabs from left to right and positions your tab accordingly. - However, pinned tabs are always placed before unpinned tabs.
- For example, if you have 5 pinned tabs open and you set a new tab with
pinned=false
and anindex
of 2, the new unpinned tab will be forced to a position to the right of all pinned tabs rather than immediately after the 2nd tab.
- For example, if you have 5 pinned tabs open and you set a new tab with
Finding the ID of Your Identities
Manual Method:
Open the Identity Manager. The Identity ID is displayed at the top of the screen where you can edit your Identity.
Getting Identity IDs Programmatically
Since there is no UI to view or copy Temporary Identity IDs (due to their dynamic nature and dependency on Workspaces), Ghost Browser extends Chrome’s Tab
object with the ghostPublicAPI
property. This property includes:
ghostPublicAPI.workspace_id [string]
The Workspace ID where the tab was opened.
ghostPublicAPI.identity_id [string]
The Identity ID to which the tab belongs.
- If a tab is opened in the Default Identity, its
identity_id
equals theghostPublicAPI.DEFAULT_IDENTITY
constant.
- If a tab is opened in the Default Identity, its
ghostPublicAPI.is_temporary_identity [boolean]
true
if the tab is in a Temporary Identity,false
otherwise.
Please refer to the API Example 3 at the end of the article.
Checking Your Extension Executes in Ghost Browser
For cross-browser extensions, you can verify if your code is running in Ghost Browser. For example, when executing the openTab
function, your extension can include a check specific to 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); } })