Work with contextual identities

Many people need or want to interact with the web using multiple personas. They may have accounts for web-based work and personal email. They might sign out of their social media accounts before accessing online shopping, to ensure that any tracking scripts on the shopping sites can't pick up their social media activity. To address these requirements, users often end up working with a standard and private browser window or two different browsers.

To address this need, Firefox includes a feature known as contextual identities, container tabs or account containers. This feature enables the creation of a cookie container for each of the identities the user wants to use in their browser. Tabs can be associated with one of these identities, keeping cookies separate from those of other identities in the browser. The practical upshot of this is that, for example, a user could have a personal and work identity. They can then use the personal identity in one tab, where they sign into their personal web mail, and the work identity in another tab, where they sign into their work web mail.

For more background on this feature, see:

APIs for working with contextual identities

To use the contextual identity features in extensions, you'll work with two APIs:

  • contextualIdentities which enable an extension to add, query, update, and delete contextual identities.
  • tabs or more specifically tabs.create which enables you to create a tab that uses a contextual identity's container (cookies store).

Permissions

To use the contextualIdentities API you need to include the "contextualIdentities" permission in your manifest.json file. You don't need the "tabs" permission to use tabs.create however; you do need the "cookies" permission to specify the cookie container you want the tab to use.

Example walkthrough

The example extension contextual-identities provides a toolbar button with a popup that lists the identities in the browser. For each identity, the extension provides options to create a new tab using it's cookies container or remove all of the identity's tabs.

Here is a short video of the extension in action:

manifest.json

The main features of the manifest.json file are:

  • the permissions request:

    json

      "permissions": [
      "contextualIdentities",
      "cookies"
  ],
  • specification of the toolbar button (browseAction) that provides access to the extension's features:

    json

      "browser_action": {
    "default_title": "Contextual Identities",
    "default_popup": "context.html",
    "default_icon": {
      "128": "identity.svg"
    }

context.html

A popup on the toolbar button provides the extension's user interface. context.html implements this popup, but it's just a shell into which the context.js script writes the list of contextual identities and their related options.

html

<body>
  <div class="panel">
    <div id="identity-list"></div>
  </div>
  <script src="context.js"></script>
</body>

context.js

All the features of the extension are implemented through context.js, which is invoked whenever the toolbar popup is displayed.

The script first gets the 'identity-list' div from context.html.

js

let div = document.getElementById("identity-list");

It then checks whether the contextual identities feature is turned on in the browser. If it's not on, information on how to activate it is added to the popup.

js

if (browser.contextualIdentities === undefined) {
  div.innerText = 'browser.contextualIdentities not available. Check that the privacy.userContext.enabled pref is set to true, and reload the add-on.';
} else {

Firefox installs with the contextual identity feature turned off, it's turned on when an extension using the contextualIdentities API is installed. However, it's still possible for the user to turn the feature off, using an option on the preferences page (about:preferences), hence the need for the check.

The script now uses contextualIdentities.query to determine whether there are any contextual identities defined in the browser. If there are none, a message is added to the popup and the script stops.

js

  browser.contextualIdentities.query({})
    .then((identities) => {
      if (!identities.length) {
        div.innerText = 'No identities returned from the API.';
        return;
      }

If there are contextual identities present—Firefox comes with four default identities—the script loops through each one adding its name, styled in its chosen color, to the <div> element. The function createOptions() then adds the options to "create" or "close all" to the <div> before it's added to the popup.

js

     for (const identity of identities) {
       const row = document.createElement('div');
       const span = document.createElement('span');
       span.className = 'identity';
       span.innerText = identity.name;
       span.style = `color: ${identity.color}`;
       console.log(identity);
       row.appendChild(span);
       createOptions(row, identity);
       div.appendChild(row);
     }
  });
}

function createOptions(node, identity) {
  for (const option of ['Create', 'Close All']) {
    const a = document.createElement('a');
    a.href = '#';
    a.innerText = option;
    a.dataset.action = option.toLowerCase().replace(' ', '-');
    a.dataset.identity = identity.cookieStoreId;
    a.addEventListener('click', eventHandler);
    node.appendChild(a);
  }
}

The script now waits for the user to select an option in the popup.

js

function eventHandler(event) {

If the user clicks the option to create a tab for an identity, one is opened using tabs.create by passing the identity's cookie store ID.

js

if (event.target.dataset.action === "create") {
  browser.tabs.create({
    url: "about:blank",
    cookieStoreId: event.target.dataset.identity,
  });
}

If the user selects the option to close all tabs for the identity, the script performs a tabs.query for all tabs that are using the identity's cookie store. The script then passes this list of tabs to tabs.remove.

js

  if (event.target.dataset.action === 'close-all') {
    browser.tabs.query({
      cookieStoreId: event.target.dataset.identity
    }).then((tabs) => {
      browser.tabs.remove(tabs.map((i) => i.id));
    });
  }
  event.preventDefault();
}

Learn more

If you want to learn more about the contextualIdentities API, check out: