contextualIdentities API

Hint

The contextualIdentities API is inherited from Firefox, and its primary documentation is maintained by Mozilla at MDN. Thunderbird implements only the subset of functions, events, and types listed here. The MDN pages may provide further details and examples, but they may also reference features that are not supported in Thunderbird.

Use the browser.contextualIdentities API to query and modify contextual identity, also called as containers.

Permissions

The following permissions influence the behavior of the API. Depending on which permissions are requested, additional methods might be available, or certain data may be included in responses.

Hint

Request permissions only when needed. Unnecessary requests may result in rejection during ATN review.

contextualIdentities

contextualIdentities

Grant access to some or all methods of the contextualIdentities API.

Note

The permission contextualIdentities is required to use messenger.contextualIdentities.*.

Functions

create(details)

– [Added in TB 53]

Creates a contextual identity with the given data.

Note

Before version 57, this method resolves its promise with false if the contextual identities feature is disabled.

Parameters

details

details

(object)

Details about the contextual identity being created.

color

color

(string)

The color of the contextual identity.

icon

icon

(string)

The icon of the contextual identity.

name

name

(string)

The name of the contextual identity.

Required permissions

  • contextualIdentities

get(cookieStoreId)

– [Added in TB 53]

Retrieves information about a single contextual identity.

Note

Before version 57, this method resolves its promise with false if the contextual identities feature is disabled.

Note

Before version 57, this method resolves its promise with null if the given identity is not found.

Parameters

cookieStoreId

cookieStoreId

(string)

The ID of the contextual identity cookie store.

Required permissions

  • contextualIdentities

move(cookieStoreIds, position)

– [Added in TB 123]

Reorder one or more contextual identities by their cookieStoreIDs to a given position.

Parameters

cookieStoreIds

cookieStoreIds

(string or array of string)

The ID or list of IDs of the contextual identity cookie stores.

position

position

(integer)

The position the contextual identity should move to.

Required permissions

  • contextualIdentities

query(details)

– [Added in TB 53]

Retrieves all contextual identities

Note

Before version 57, this method resolves its promise with false if the contextual identities feature is disabled.

Parameters

details

details

(object)

Information to filter the contextual identities being retrieved.

name

[name]

(string, optional)

Filters the contextual identity by name.

Required permissions

  • contextualIdentities

remove(cookieStoreId)

– [Added in TB 53]

Deletes a contextual identity by its cookie Store ID.

Note

Before version 57, this method resolves its promise with false if the contextual identities feature is disabled.

Note

Before version 57, this method resolves its promise with null if the given identity is not found.

Parameters

cookieStoreId

cookieStoreId

(string)

The ID of the contextual identity cookie store.

Required permissions

  • contextualIdentities

update(cookieStoreId, details)

– [Added in TB 53]

Updates a contextual identity with the given data.

Note

Before version 57, this method resolves its promise with false if the contextual identities feature is disabled.

Note

Before version 57, this method resolves its promise with null if the given identity is not found.

Parameters

cookieStoreId

cookieStoreId

(string)

The ID of the contextual identity cookie store.

details

details

(object)

Details about the contextual identity being created.

color

[color]

(string, optional)

The color of the contextual identity.

icon

[icon]

(string, optional)

The icon of the contextual identity.

name

[name]

(string, optional)

The name of the contextual identity.

Required permissions

  • contextualIdentities

Events

onCreated

– [Added in TB 57]

Fired when a new container is created.

Parameters for onCreated.addListener(listener)

listener(changeInfo)

listener(changeInfo)

A function that will be called when this event occurs.

Parameters passed to the listener function

changeInfo

changeInfo

(object)

contextualIdentity

contextualIdentity

Contextual identity that has been created

Required permissions

  • contextualIdentities

onRemoved

– [Added in TB 57]

Fired when a container is removed.

Parameters for onRemoved.addListener(listener)

listener(changeInfo)

listener(changeInfo)

A function that will be called when this event occurs.

Parameters passed to the listener function

changeInfo

changeInfo

(object)

contextualIdentity

contextualIdentity

Contextual identity that has been removed

Required permissions

  • contextualIdentities

onUpdated

– [Added in TB 57]

Fired when a container is updated.

Parameters for onUpdated.addListener(listener)

listener(changeInfo)

listener(changeInfo)

A function that will be called when this event occurs.

Parameters passed to the listener function

changeInfo

changeInfo

(object)

contextualIdentity

contextualIdentity

Contextual identity that has been updated

Required permissions

  • contextualIdentities

Types

ContextualIdentity

– [Added in TB 53]

Represents information about a contextual identity.

object

color

color

(string)

The color name of the contextual identity.

colorCode

colorCode

(string)

– [Added in TB 57]

The color hash of the contextual identity.

cookieStoreId

cookieStoreId

(string)

The cookie store ID of the contextual identity.

icon

icon

(string)

The icon name of the contextual identity.

iconUrl

iconUrl

(string)

– [Added in TB 57]

The icon url of the contextual identity.

name

name

(string)

The name of the contextual identity.