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. Users often use a standard and private browser window or two different browsers to address these requirements.

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 (store) 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, for example, 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:

* Put your multiple online personalities in Firefox Multi-Account Containers
* Security/Contextual Identity Project/Containers
* Firefox support article on containers
APIs for working with contextual identities
-------------------------------------------

Depending on the nature of your extension, you may want to manage contextual identities, associate objects your extension manipulates with contextual identities, or both.

### Managing contextual identities

To manage contextual identities, you use the `contextualIdentities` API. This API enables you to add, query, update, and delete contextual identities. When you create a contextual identity, it is given a unique `cookieStoreId`. You use this ID to work with entities related to the contextual identity.

### Using `cookieStoreId`

Several extension APIs include the `cookieStoreId` in objects to enable extensions to associate these objects with specific contextual identities.

* `browsingData.removeCookies()` and `browsingData.removeLocalStorage()` where you use `browsingData.removalOptions` to set the cookie store items are removed from.
* `contentscripts.register` enables you to register a content script restricted to documents associated with one or more `cookieStoreIds`.
* `downloads` where you can associate a download with a cookie store.
* `proxy` where the details passed into the `proxy.onRequest` listener identify the cookie store associated with the request.
* `tabs` where you can `create` a tab in a container tab, `get` the `cookieStoreId` for a tab, and `query` tabs based on their associated cookie store.
* `userscripts.register` enables you to register a content script restricted to documents associated with one or more `cookieStoreIds`.
* `webrequest` where all the events return the `cookieStoreId` of the request.
* `windows.create` where you can specify the cookie store for the tabs added to a window when it's created.
Permissions
-----------

To use the `contextualIdentities` API, you must include the "contextualIdentities" permission in your manifest.json file.

If an API enables cookies to be modified, you need the "cookies" permission. For example, using `cookieStoreId` in `tabs.query` does not require the "cookies" API, as reading the property doesn't affect the cookies in the containers. However, using `tabs.create` requires the permission because the opened tab can read and modify cookies in a container.

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 tab using its cookies container or remove all of its 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 (browserAction) 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 extension's features 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, the user can 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 any contextual identities are 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` to get all the tabs 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:

* contextualIdentities API reference.
* Multi-Account Containers extension source code. This is code for the Firefox Multi-Account Containers extension. This extension provides users with enhanced functionality for contextual identities, such as the ability to long-click the new tab button and then select the identity to use in the new tab. It showcases contextual identities' capabilities and is well worth a look.