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
Grant access to some or all methods of the contextualIdentities API.
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
Required permissions
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.
Required permissions
getSiteAssociation(details)
Retrieves the association of a site, or null if the site is not associated with any container.
Parameters
details
Return type (Promise)
_returns
The association of the site, null if the site is not associated with any container.
Required permissions
getSupportedColors()
Retrieves the list of colors supported by contextual identities.
Required permissions
getSupportedIcons()
Retrieves the list of icons supported by contextual identities.
Required permissions
Reorder one or more contextual identities by their cookieStoreIDs to a given position.
Parameters
cookieStoreIds
The ID or list of IDs of the contextual identity cookie stores.
position
The position the contextual identity should move to.
Required permissions
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
Required permissions
querySiteAssociations(details)
Retrieves the list of site-to-container associations.
Parameters
details
Required permissions
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.
Required permissions
removeSiteAssociation(details)
Removes the container association for a site.
Parameters
details
Required permissions
setSiteAssociation(details)
Associates a site with a container. Top-level navigations to that site will load in the given container.
Parameters
details
Required permissions
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
The ID of the contextual identity cookie store.
details
Required permissions
Events
onCreated
– [Added in TB 57]
Fired when a new container is created.
Parameters for onCreated.addListener(listener)
listener(changeInfo)
A function that will be called when this event occurs.
Parameters passed to the listener function
changeInfo
contextualIdentity
Contextual identity that has been created
Required permissions
onRemoved
– [Added in TB 57]
Fired when a container is removed.
Parameters for onRemoved.addListener(listener)
listener(changeInfo)
A function that will be called when this event occurs.
Parameters passed to the listener function
changeInfo
contextualIdentity
Contextual identity that has been removed
Required permissions
onSiteAssociationChanged
Fired when a site-to-container association is added, changed, or removed.
Parameters for onSiteAssociationChanged.addListener(listener)
listener(changeInfo)
A function that will be called when this event occurs.
Parameters passed to the listener function
changeInfo
Required permissions
onUpdated
– [Added in TB 57]
Fired when a container is updated.
Parameters for onUpdated.addListener(listener)
listener(changeInfo)
A function that will be called when this event occurs.
Parameters passed to the listener function
changeInfo
contextualIdentity
Contextual identity that has been updated
Required permissions
Types
ContextualIdentity
– [Added in TB 53]
Represents information about a contextual identity.
object
color
The color name of the contextual identity.
colorCode
The color hash of the contextual identity.
cookieStoreId
The cookie store ID of the contextual identity.
icon
The icon name of the contextual identity.
iconUrl
The icon url of the contextual identity.
name
The name of the contextual identity.
SiteAssociation
Represents the association between a site and a contextual identity.