Namespaces

new SparkCommunications(configuration)

Parameter

Name Type Optional Description

configuration

SparkCommunications.Configuration

 

An object containing the configuration parameters to set up the Spark Communications SDK.

Extends
EventEmitter
Throws

(TypeError or RangeError)

When an invalid parameter is provided.

Classes

Interfaces

Namespaces

Properties

constant static

SdkRegion  string

An enumeration of SDK production regions.

Properties

Name Type Optional Description

Global

 

 

Use the world-wide region. This is the default.

UnitedStates

 

 

Use BlackBerry Infrastructure that is hosted within the United States of America.

constant static

SetupState  string

The current setup state.

Properties

Name Type Optional Description

NotRequested

 

 

The SDK setup hasn't started. In this state, the SDK is waiting for the SparkCommunications#setupStart function to be called before proceeding.

Ongoing

 

 

The SDK is performing setup actions.

Success

 

 

The SDK successfully completed setup. The SparkCommunications#messenger, SparkCommunications#media, and SparkCommunications#getRegistrationInfo are available for use.

SyncRequired

 

 

This state only occurs when the application uses the BlackBerry Key Management Service (KMS).

The SparkCommunications#syncStart function must be called to perform a sync with KMS, or setup can be abandoned by calling SparkCommunications#shutdown.

SyncStarted

 

 

This state only occurs when the application uses the BlackBerry Key Management Service (KMS).

The sync with KMS has been started.

constant static

SyncPasscodeKdf  string

An enumeration of the key derivation functions (KDFs) that can be used with a passcode to derive an encryption key to protect keys stored in the BlackBerry Key Management Service (KMS).

Properties

Name Type Optional Description

Argon2

 

 

A password-based key derivation function suitable for use with passcodes that are not generated from a secure random bit generator. For example, if your application collects passcodes directly from your users, use this KDF.

When using this KDF:

AnsiX963Sha512

 

 

A key derivation function suitable for passcodes that are generated from a secure random bit generator that uses the ANSI-X9.63 KDF and SHA-512 algorithms. For example, if your application uses securely generated random data for its passcodes and manages them internally on behalf of your users, use this KDF.

When using this KDF:

constant static

SyncPasscodeState  string

The state of the passcode sync with the BlackBerry Key Management Service (KMS).

Properties

Name Type Optional Description

None

 

 

No sync passcode is currently required.

New

 

 

The application must provide a new management key passcode that the SDK will use to store new profile keys in KMS.

Existing

 

 

The application can provide an existing management key passcode that the SDK will use to retrieve existing profile keys from KMS. Or the application can provide a new management key passcode to generate new profile keys that will be stored in KMS.

constant static

SyncStartAction  string

The action to perform when calling SparkCommunications#syncStart with the BlackBerry Key Management Service (KMS) management key passcode.

Properties

Name Type Optional Description

New

 

 

The application is providing a new management key passcode that the SDK will use to store new profile keys in KMS. Any existing keys will be discarded.

Existing

 

 

The application is providing an existing management key passcode that the SDK will use to retrieve existing profile keys from KMS.

read-only static

version  string

The opaque version string of the SDK.

read-only

endpointId  String

The identifier of this endpoint on the BlackBerry Infrastructure.

read-only

media  SparkCommunications.Media

The media object is the interface used to manage media calls. Undefined when the SDK is not setup. Null if media is not supported.

read-only

messenger  SparkCommunications.Messenger

The messenger object is the interface to high level chat functionality.

read-only

networkState  SparkCommunications.NetworkState

The current network connectivity state of the SDK.

read-only

setupState  SparkCommunications.SetupState

Tracks the current setup state.

read-only

syncPasscodeState  SparkCommunications.SyncPasscodeState

Tracks the sync passcode state for the BlackBerry Key Management Service (KMS).

Methods

deleteEndpoint(endpointId) → Promise

Sends a request to delete a specified endpoint associated with the local regId. After this, the endpoint must register again to continue to function.

Parameter

Name Type Optional Description

endpointId

String

 

The endpoint identifier the endpoint to delete.

Throws

SparkCommunications.Error.Error

When called before setup is complete.

Returns

Promise

A promise which is resolved when the request succeeds, or rejected when the request fails.

The promise will be rejected with a SparkCommunications.Error.TemporaryFailure if the request failed and may be retried. No internal retry logic is applied to this request.

The promise will be rejected with a SparkCommunications.Error.PermanentFailure if the request failed and must not be retried.

getAllEndpoints() → Promise containing SparkCommunications.EndpointList

Sends a request to get all endpoints associated with the local regId.

Throws

SparkCommunications.Error.Error

When called before setup is complete.

Returns

Promise containing SparkCommunications.EndpointList

The promise of the requested endpoint list.

The promise will be rejected with a SparkCommunications.Error.TemporaryFailure if the request failed and may be retried. No internal retry logic is applied to this request.

The promise will be rejected with a SparkCommunications.Error.PermanentFailure if the request failed and must not be retried.

getIdentitiesFromAppUserId(appUserId) → Promise containing SparkCommunications.Identity

Get the identity information for the given appUserId.

Parameter

Name Type Optional Description

appUserId

string

 

The application user ID to get identity information for.

Throws

SparkCommunications.Error.Error

When the SDK is not set up.

TypeError

When an invalid argument is provided.

Returns

Promise containing SparkCommunications.Identity

A Promise of the resolved identity information.

The promise will be rejected with a SparkCommunications.Error.NotFoundError if no identity information is available.

The promise will be rejected with a SparkCommunications.Error.TemporaryFailure if an error occurs and the request may be retried. No internal retry logic is applied to this request.

The promise will be rejected with a SparkCommunications.Error.PermanentFailure if the request failed and must not be retried.

getIdentitiesFromAppUserIds(appUserIds) → Promise containing Array of SparkCommunications.Identity

Get the identity information for the given appUserIds.

Parameter

Name Type Optional Description

appUserIds

Array of string

 

The application user IDs to get identity information for. A maximum of 50 IDs can be present in one request.

Throws

SparkCommunications.Error.Error

When the SDK is not set up.

TypeError

When an invalid argument is provided.

Returns

Promise containing Array of SparkCommunications.Identity

A Promise of the resolved identity information. A list of identity information will be returned and any appUserIds for which no identity information was found will be omitted from the list.

The promise will be rejected with a SparkCommunications.Error.TemporaryFailure if an error occurs and the request may be retried. No internal retry logic is applied to this request.

The promise will be rejected with a SparkCommunications.Error.PermanentFailure if the request failed and must not be retried.

getIdentitiesFromRegId(regId) → Promise containing SparkCommunications.Identity

Get the identity information for the given regId.

Parameter

Name Type Optional Description

regId

string

 

The regId get identity information for.

Throws

SparkCommunications.Error.Error

When the SDK is not set up.

TypeError

When an invalid argument is provided.

Returns

Promise containing SparkCommunications.Identity

A Promise of the resolved identity information.

The promise will be rejected with a SparkCommunications.Error.NotFoundError if no identity information is available.

The promise will be rejected with a SparkCommunications.Error.TemporaryFailure if an error occurs and the request may be retried. No internal retry logic is applied to this request.

The promise will be rejected with a SparkCommunications.Error.PermanentFailure if the request failed and must not be retried.

getIdentitiesFromRegIds(regIds) → Promise containing Array of SparkCommunications.Identity

Get the identity information for the given regIds.

Parameter

Name Type Optional Description

regIds

Array of string

 

The regIds to get identity information for. A maximum of 50 IDs can be present in one request.

Throws

SparkCommunications.Error.Error

When the SDK is not set up.

TypeError

When an invalid argument is provided.

Returns

Promise containing Array of SparkCommunications.Identity

A Promise of the resolved identity information. A list of identity information will be returned and any regIds for which no identity information was found will be omitted from the list.

The promise will be rejected with a SparkCommunications.Error.TemporaryFailure if an error occurs and the request may be retried. No internal retry logic is applied to this request.

The promise will be rejected with a SparkCommunications.Error.PermanentFailure if the request failed and must not be retried.

getRegistrationInfo() → SparkCommunications.RegistrationInfo

Return the registration information of the SDK. The return value will be undefined if the SDK is not set up.

Throws

SparkCommunications.Error.Error

When the SDK is not set up.

Returns

SparkCommunications.RegistrationInfo 

isSetup() → Boolean

Return whether or not the SDK is currently in a set up state.

Returns

Boolean

True if the SDK has been set up. False if it has not been set up, or has been set up, then shut down.

retryServerRequests()

This function may be called at any time user activity resumes after an idle period. Any event that is considered to be a good representation of the user becoming interested in interacting with Spark Communications again may be used to trigger this function, and thus will make a good event to use as a user-driven retry trigger. For example an application could call this function whenever the application goes from being 'not on the screen' or 'out of focus' to being 'on the screen' or 'in focus'. However, the application may also choose to tie this trigger to an explicit user action such as a 'Refresh' button.

The application does not need to 'rate limit' or otherwise filter calls to this function.

setupStart()

Start setting up the SDK setup.

As setup progresses SparkCommunications#event:setupState events will be fired. The application should monitor these events and react accordingly.

If an error occurs that can't be retried automatically a SparkCommunications#event:setupError event will be fired. The application can manually retry setup later.

The application may choose to call SparkCommunications#shutdown at any time to abandon its attempt to setup the SDK. It may also take the additional step of instantiating a new SDK instance if it would like to change user identities.

Calling SparkCommunications#shutdown will reset the SparkCommunications#setupState to 'NotRequested' and SparkCommunications#setupStart may be called again to re-initiate the event driven setup.

Fires
SparkCommunications#event:setupState
SparkCommunications#event:setupError
Throws

SparkCommunications.Error.Error

When setup is already in progress or completed.

shutdown() → Promise

Reset the SDK to its unsetup state. This will stop the endpoint from performing network operations and allows the endpoint to be garbage collected once the application has released it's handle on the endpoint.

Calling SparkCommunications#setupStart on an endpoint that has been shutdown will begin the setup process for the endpoint.

This does not allow changing the user identity used by the endpoint. Changing identity requires creation of a new endpoint.

Fires
SparkCommunications#event:setupState
Returns

Promise

The promise resolves when the SDK is shutdown. The promise is rejected with an error if the shutdown fails in which case the SDK should not be set up again.

syncPasscodeChange(passcode) → Promise

This function is only used by apps that use the BlackBerry Key Management Service (KMS).

Called to change the user's key management passcode for KMS after setup completes.

Parameter

Name Type Optional Description

passcode

(string or Uint8Array)

 

The new management key passcode to use for KMS.

The type required for this parameter is determined by the value of the kmsSyncPasscodeKdf configuration option when the SDK was instantiated.

Throws

SparkCommunications.Error.Error

When setup is not complete, or KMS is not enabled.

(TypeError or RangeError)

When a parameter has an unexpected type or value.

Returns

Promise

A resolved promise if the passcode was successfully changed. Otherwise a rejected promise.

syncStart(passcode, action)

This function is only used by apps that use the BlackBerry Key Management Service (KMS).

Called by the application when the SparkCommunications#setupState is 'SyncRequired'.

If the SparkCommunications#syncPasscodeState is 'New', then no sync data exists in KMS for this identity and it must create new sync data. The application must call SparkCommunications#syncStart with a SparkCommunications.SyncStartAction of 'New' and supply the 'passcode' that will be used to protect the new sync data in KMS.

If the SparkCommunications#syncPasscodeState is 'Existing', then existing sync data was found in KMS, and the application can do one of the following:

Restore the existing sync data by calling SparkCommunications#syncStart with a SparkCommunications.SyncStartAction of 'Existing' and supply the existing 'passcode'.

Generate new sync data and delete the existing data by calling SparkCommunications#syncStart with a SparkCommunications.SyncStartAction of 'New' and a supply a new 'passcode' to protect the new sync data in KMS.

On successful sync with KMS the SparkCommunications#setupState will advance to 'Success'.

On a sync failure the SparkCommunications#setupState may transition back to 'SyncRequired' in which case the application can retry. On permanent errors a SparkCommunications#event:setupError would be fired.

Parameters

Name Type Optional Description

passcode

(string or Uint8Array)

 

The management key passcode used to protect the sync data in KMS.

The type required for this parameter is determined by the value of the kmsSyncPasscodeKdf configuration option when the SDK was instantiated.

action

SparkCommunications.SyncStartAction

 

The action to perform with the passcode.

Fires
SparkCommunications#event:setupState
SparkCommunications#event:setupError
Throws

SparkCommunications.Error.Error

When the SparkCommunications#setupState is not 'SyncRequired'.

(TypeError or RangeError)

When a parameter has an unexpected type or value.

Abstract types

static

Configuration  Object

Properties

Name Type Optional Description

domain

string

 

Your application operates within a domain that is statically assigned to your application when you sign up to use the BlackBerry Infrastructure. Each domain has an ID, and this argument must be set to that domain ID.

Your application must set its domain, or the SDK will fail to start.

sandbox

boolean

Yes

Your application can operate within the production environment for general use, or the sandbox environment for developer testing. Set this flag to specify whether the SDK should connect to the sandbox environment instead of the production environment.

The default is false.

region

SparkCommunications.SdkRegion

Yes

When you are ready to release your application, you can configure the SDK to operate within one of the BlackBerry Infrastructure's production regions.

See the Developer Guide for more information on configuring and using regions in your application.

The default is to use Global.

environment

string

Yes

Deprecated. This parameter will be removed in a future release. Use the sandbox and region options to configure the environment used by your application. If you configure either of the sandbox or region options, this option must be undefined.

The environment that the SDK is pointing to. The possible values are: 'Sandbox', 'Production'.

userId

string

 

The identity of the user. This is determined by the authentication server.

description

string

 

A description of the endpoint. This should be an appropriate localized string based on what it can learn about the endpoint, for example "Windows PC" or "Firefox". This information about the endpoint will be displayed by other devices doing endpoint management. The maximum length is 2000 codepoints. Anything longer will be truncated.

getToken

SparkCommunications#authTokenCallback

 

This function will be invoked to get a new authentication token. The implementation should call out to a server to retrieve a new authentication token. It should never return a cached token - the implementation will internally cache the token and will call out to this function only when there is no known token, or the known token is not valid.

getKeyProvider

SparkCommunications#keyProviderCallback

Yes

When defined, the SDK will call this function when the application's implementation of the KeyProviderInterface is needed. Otherwise, the BlackBerry Key Management Service (KMS) will be used.

kmsSyncPasscodeKdf

SparkCommunications.SyncPasscodeKdf

Yes

The key derivation function (KDF) to use with the BlackBerry Key Management Service (KMS) passcode. When not specified, the default is Argon2.

Important: All clients operating within the same SDK domain must use the same KMS KDF.

kmsArgonWasmUrl

string

Yes

The URL or relative path of the Argon2 WASM file. Only needed when running in KMS mode using the Argon2 WASM module in a location other than "environment_argon2.wasm".

filter

Array of string

Yes

Filter the chat list to only allow the local endpoint to interact with chats whose identifiers are among the specified set. This is the only mechanism by which a local endpoint may see a different set of chats than another endpoint belonging to the same user.

If unspecified, allow interactions with any chat for which the client has permission. An empty array is not the same as unfiltered, it results in not allowing interaction with any chats.

Note that to be invited to a new chat when using a filter, that chat must be added to the filter before the invite is received. The set may be modified by calling SparkCommunications.Messenger#filterAdd and SparkCommunications.Messenger#filterRemove.

When using a filter, creating a chat will result in the chat being added to the filter for the local endpoint only. Other endpoints belonging to the local user must call SparkCommunications.Messenger#filterAdd to have access to the chat.

Any chats added to the filter during instantiation or subsequently using SparkCommunications.Messenger#filterAdd are not affected by calls to SparkCommunications#shutdown and SparkCommunications#setup.

logLevel

number

Yes

The amount of log output to produce. 0 produces the least logging, 3 produces the most. The default is 2 if unspecified.

nickname

string

Yes

A nickname for the endpoint. This information about the endpoint will be displayed by other devices doing endpoint management. It should be provided by the user, and may be anything they want. The maximum length is 2000 codepoints. Anything longer will be truncated.

persistent

SparkCommunications.PersistentInfo

Yes

The optional configuration for persistent endpoints.

messageStorageFactory

SparkCommunications.MessageStorageInterface

Yes

A factory to construct the data structures to store messages for a chat. This may be replaced in order to do things including associating data with each chat message, applying transforms such as filtering to the message list, or getting precise notifications of any changes to the message list. The default implementation will return a message list in the form of an immutable array.

static

Endpoint  Object

Properties

Name Type Optional Description

endpointId

string

 

The identifier of an endpoint.

description

string

 

The description of the endpoint, specified when the endpoint was registered.

ephemeral

boolean

 

Whether the endpoint is ephemeral (true) or persistent (false).

static

EndpointList  Object

A list of endpoints registered to the local user.

Properties

Name Type Optional Description

maxPersistentEndpoints

number

 

Specifies the maximum number of persistent endpoints which can be concurrently registered.

maxEphemeralEndpoints

number

 

Specifies the maximum number of ephemeral endpoints which can be concurrently registered.

endpoints

Array of SparkCommunications.Endpoint

 

An array of objects describing registered endpoints.

static

Identity  Object

The identity information returned when resolving an identity.

Properties

Name Type Optional Description

appUserId

string

 

The identity's application user id.

regId

string

 

The identity's regId.

static

PersistentInfo  Object

The configuration values specific to persistent endpoints.

Properties

Name Type Optional Description

endpointId

string

Yes

When running as a persistent endpoint, your application must identify itself as the same endpoint each time it connects to the BlackBerry Infrastructure. To do this, you must persist the endpointId that is assigned to you during the endpoint's first registration and then pass it as the endpointId value when starting the SDK every time after that.

When no endpointId is specified here, a new one will be assigned. If your application has lost its original endpointId, it can ask for a new one by leaving this undefined. The old endpointId will eventually be automatically deregistered after enough new persistent endpoints register.

When an endpointId is specified here, it must be a valid endpointId that was previously assigned this endpoint by the SDK.

pushCookie

string

Yes

When running as a persistent endpoint, your application infrastructure can receive Push Proxy notifications when this endpoint is disconnected from the BlackBerry Infrastructure. This field contains opaque data that will be passed in those Push Proxy notifications to help you process them and wake up your application. (See the Developer Guide for more information about using a Push Proxy with your application.)

The size limit for this field is 4096 bytes when encoded as UTF-8.

static

RegistrationInfo  Object

Information about a successful registration.

Properties

Name Type Optional Description

regId

string

 

The regId of the user.

registrationToken

string

 

The registration token returned by the server after a successful registration. This token contains trusted information about the association of the application user ID with the assigned regId.

static

SetupResult  Object

The result of performing setup. It contains the objects through which communication can be accomplished.

Properties

Name Type Optional Description

messenger

SparkCommunications.Messenger

 

An object through which messages and files can be sent and received.

media

(SparkCommunications.Media or null)

 

An object through which voice, video and data-only calls can be made or received. This will be null if media functionality is unavailable for the platform.

authTokenCallback() → Promise containing string

This callback type is invoked when there is a change in the connection state.

Returns

Promise containing string

Returns a promise of a new authentication token.

keyProviderCallback(regId, authToken) → Promise containing SparkCommunications.KeyProviderInterface

The function used to call back on the application during setup of the SDK when a key provider set up for use with the given regId is needed. The key provider returned by the promise must implement the KeyProviderInterface.

Any rejection of the returned promise will result in a failure to complete registration of the SDK with the BlackBerry Infrastructure.

Parameters

Name Type Optional Description

regId

string

 

The regId of the local user.

authToken

string

 

Deprecated. This parameter will be removed in a future release. The most recent authentication token that was acquired via the application provided SparkCommunications#authTokenCallback function.

Returns

Promise containing SparkCommunications.KeyProviderInterface

Returns the promise of an object that implements the SparkCommunications.KeyProviderInterface.

Events

networkState  SparkCommunications.NetworkState

The event indicating a change in the network state. This event can be emitted after SparkCommunications#setupStart has been called.

setupError  SparkCommunications.Event.SetupError

The SDK setup failed with an error. This event can be emitted by the SDK any time after SparkCommunications#setupStart has been called. This event may also be called after the SparkCommunications#setupState has transitioned to 'Success' to indicate that the SDK is no longer setup.

When this event is emitted, the SparkCommunications#setupState will be transitioned to 'NotRequested' and SparkCommunications#shutdown will have been automatically called by the SDK.

setupState  SparkCommunications.Event.SetupState

The event indicating a change in the setup state. This event can be emitted after SparkCommunications#setupStart or SparkCommunications#syncStart has been called.