BlackBerry Spark Communications Services Guide

Support Library for JavaScript

The Support library contains a suite of basic implementations you can use to fast track your application development.

This folder is included as part of the SDK package in the examples/support directory.

Features

Reference Implementations

The Support library comes with code that you can use to authenticate with popular identity providers and perform user management and Cloud Key Storage with popular cloud services.

You can configure the Support library to use these services with the same steps that you use to configure some of the examples.

Identity Providers

The Support library provides classes that help you integrate your application with an identity provider.

Classes Description
MockAuthManager This can generate unsigned JWT access tokens for sandbox domains with user authentication disabled.
GoogleAuthManager This can obtain access tokens for your application when it uses Google Sign-In as your Identity Provider.
AzureAuthManager This can obtain access tokens for your application when it uses Azure Active Directory as your Identity Provider.

Web Components

The Support library includes several web components to simplify display of some parts of the user interface.

Web Component Description
bbmChat Conveniently display everything needed to interact with a chat.
bbmChatHeader Display metadata for a chat and access chat operations.
bbmChatInput Send messages and files to a chat.
bbmChatMessageList Display a chat's messages, each in a custom bubble.
bbmRichChatMessageList Display a chat's messages, each in a default rich bubble.
bbmChatList Display a list of chats to which the user is subscribed.
bbmChatMessageStateList Display which intended recipients have received or read a message.
bbmChatTypingNotification Display which users are currently typing a message in a chat.
bbmCall Display an audio-video call.
bbmChatMessageList Display the messages of a chat.
bbmChatUserPassword Allow the application to collect a password from the user.
bbmContactList Allow user to browse and manage their contacts.
bbmUserEmailDialog Allow the application to collect the user's email address.

To display the list of chats, create a bbmChatList. Each chat will be displayed in a custom bubble controlled by a template applied to the chat list.

The bbmChat web component will display chat metadata, incoming messages, and an area to choose text or files for outgoing messages. The bbmChat web component is a composition of other web components. Using bbmChat is the quickest way to get started on displaying a chat. However the web components that make up bbmChat can also be instantiated individually. Visit the RichChat example for information on how to use the bbmChat web component.

The bbmRichChatMessageList displays message bubbles for text messages, files and pictures and is the default bubble for bbmChat. To display different types of bubbles, or to display these types differently, a bbmChatMessageList can be used. A bbmChatMessageList requires an HTML template to describe a bubble and will instantiate this template for each message rather than using the default bubble.

Google Sign-In and Google People Support

Authenticating with Google Sign-In

In your application, define a GoogleAuthManager.AuthConfig object with the configuration values for your Google client.

In the Google developer console, create a new OAuth client ID for a Web application. For this client, add an Authorized redirect URI with the full URI to the landing page for OAuth2 redirects. In the web example applications this is usually the HTML page where GoogleAuthManager is instantiated. For example, for RichChat the Authorized redirect URI could be https://example.com/examples/RichChat/index.html. Once you have completed creation of the client ID, replace YOUR_CLIENT_ID with the client ID value shown.

In your application, create an instance of GoogleAuthManager.

const authManager = new GoogleAuthManager({
  authService: 'https://accounts.google.com/o/oauth2/v2/auth',
  scope: 'profile',
  clientId: 'YOUR_GOOGLE_SIGN_IN_WEB_CLIENT_ID'
});

Check if the user is already authenticated.

if (authManager.isAuthenticated()) {
  // User is already authenticated.
}

If not authenticated, then authenticate the user.

const userInfo = await authManager.authenticate();
// User is now authenticated.
// The userInfo is a support.identity.GenericUserInfo object.

User Discovery with Google People

The Support library can use Google People for User Management. The GooglePeopleUserManager class manages synchronizing users from a Google account to the example application. To use user discovery with Google People, include the GooglePeopleUserManager in your application:

<script src="../support/identity/GooglePeopleUserManager.js"></script>

And instantiate it:

const userManager = new GooglePeopleUserManager(userRegId, authManager, getIdentities, AUTH_CONFIGURATION);
await userManager.initialize();

Firebase Cloud Key Storage

If your application needs complete control of its cryptographic security keys, you can secure these keys by using Firebase for Cloud Key Storage.

The FirebaseKeyProvider class in the Support library allows your application to read and write protected keys from a Firebase database.

To use FirebaseKeyProvider, you must add a value to the scope argument of GoogleAuthManager:

const authManager = new GoogleAuthManager({
  authService: 'https://accounts.google.com/o/oauth2/v2/auth',
  scope: 'profile https://www.googleapis.com/auth/firebase',
  clientId: 'YOUR_GOOGLE_SIGN_IN_WEB_CLIENT_ID'
});

Include the FirebaseKeyProvider in your application.

<script src="../support/protect/firebase/FirebaseKeyProvider.js"></script>

Create the FirebaseKeyProvider.

const keyProvider = FirebaseKeyProvider.factory.createInstance(
  uid,
  {
    apiKey: 'YOUR_FIREBASE_API_KEY',
    authDomain: 'YOUR_FIREBASE_AUTH_DOMAIN',
    databaseURL: 'YOUR_FIREBASE_DATABASE_URL',
    projectId: 'YOUR_FIREBASE_PROJECT_IDENTIFIER',
    storageBucket: 'YOUR_FIREBASE_STORAGE_BUCKET',
    messagingSenderId: 'YOUR_FIREBASE_MESSAGING_SENDER_IDENTIFIER'
  },
  accessToken,
  importFailedCallback,
  keyProtect,
  BBMEnterprise.getIdentitiesFromRegId);

Pass the keyProvider to the constructor of BBMEnterprise using the BBMEnterprise.keyProviderCallback. See Getting Started with Web for details.

The Support library code for Cloud Key Storage in Firebase is compatible across iOS, Android, and JavaScript.

Azure Active Directory Support

Authenticating with Active Directory

Include the AzureAuthManager in your application.

<script src="../support/auth/AzureAuthManager.js"></script>

Authenticate the User

In your application, create an instance of the AzureAuthManager with the identifiers your application was assigned when you configured Azure Active Directory as your Identity Provider.

const authManager = new AzureAuthManager({
  authService: 'https://login.microsoftonline.com/YOUR_AZURE_DIRECTORY_ID/oauth2/v2.0/authorize',
  clientId: YOUR_AZURE_APPLICATION_ID
  scope: 'api://YOUR_AZURE_APPLICATION_ID/Messaging.All https://graph.microsoft.com/User.ReadWrite https://graph.microsoft.com/User.ReadBasic.All'
}); 

The scope must be what you defined in the Microsoft Application Registration Portal as the permission to access Spark Communications Services. Replace YOUR_AZURE_APPLICATION_ID with the Application ID that is registered in the Microsoft Application Registration Portal. Replace YOUR_AZURE_DIRECTORY_ID with your Azure Directory ID.

Check if the user is already authenticated.

if (authManager.isAuthenticated()) {
  // User is already authenticated.
}

If not authenticated, then authenticate the user.

const userInfo = await authManager.authenticate();
// User is now authenticated.
// The userInfo is a support.identity.GenericUserInfo object.
// You will need the userInfo.id for the next step.

The tokens used for the SDK and the Microsoft Graph API can be accessed using the getBbmSdkToken() and getUserManagerToken() functions, respectively.

Now that you have the userInfo, create the BBMEnterprise instance. Pass userInfo.userId and authManager.getBbmSdkToken to the constructor.

const sdk = new BBMEnterprise({
  // The userId of the logged in user.
  userId: userInfo.userId,

  // The function the SDK can use to fetch a fresh token on demand.
  getToken: () => authManager.getBbmSdkToken(),

  // ...
});

User Discovery with Azure Active Directory

The AzureUserManager class in the Support library allows your application to read user data from Azure Active Directory using the Microsoft Graph API.

The SDK for JavaScript must be started before the AzureUserManager instance is created. Your application must pass the regId of the logged in user from the SDK and the instance of AzureAuthManager to its constructor. The AzureUserManager will authenticate with Azure Active Directory using the access token obtained from AzureAuthManager.

Include the AzureUserManager in your application.

<script src="../support/identity/AzureUserManager.js"></script>

After endpoint setup completes, create a new instance of the AzureUserManager.

// Create the user manager.
const userManager = new AzureUserManager(
  userRegId, authManager, BBMEnterprise.getIdentitiesFromAppUserIds);

You can add event listeners to the UserManager that notify your application when contacts are added or changed.

userManager.addEventListener('user_added', onContactAdded);
userManager.addEventListener('user_changed', onContactChanged);

If your application uses the bbmChat web component from the Support library, then you can set the UserManager as follows.

bbmChat.setContactManager(userManager);

Azure Cosmos DB Cloud Key Storage

If your application needs complete control of its cryptographic security keys, you can secure these keys by using Azure Cosmos DB for Cloud Key Storage with the Key Provider Server example server that comes with the SDK.

The CosmosDbKeyProvider class in the Support library allows your application to read and write protected keys from the Key Provider Server.

Include the CosmosDbKeyProvider in your application.

<script src="../support/protect/cosmosdb/CosmosDbKeyProvider.js"></script>

Create the CosmosDbKeyProvider.

const keyProvider = CosmosDbKeyProvider.factory.createInstance(
  uid,
  // The URL of your Key Provider Server instance.
  'https://server/',   
  () => authManager.getBbmSdkToken(),
  importFailedCallback,
  keyProtect,
  BBMEnterprise.getIdentitiesFromRegId);

Pass the keyProvider to the constructor of BBMEnterprise using the BBMEnterprise.keyProviderCallback. See Getting Started with Web for details.

The Support library code for Cloud Key Storage in Azure Cosmos DB is compatible across iOS, Android, and JavaScript.