BlackBerry Spark Communications Services Guide

Support Library for Android

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.

Setup

The Support library has a dependency on the bbm-sdk-release.aar file. You should update the Support/build.gradle section to reference the AAR file:

flatDir {
    // point to shared dir with AAR file in it
    dirs '../../../sdk'
}
  

Dependencies

This library has only been validated with these dependencies. Other configurations have not been validated.

implementation(name: 'bbm_sdk-release', ext: 'aar')

implementation 'com.google.guava:guava:27.1-android'
implementation 'androidx.legacy:legacy-support-v4:1.0.0'
implementation 'androidx.appcompat:appcompat:1.0.2'
implementation 'com.google.android.material:material:1.0.0'
implementation 'androidx.recyclerview:recyclerview:1.0.0'
implementation 'androidx.constraintlayout:constraintlayout:1.1.3'

// Firebase Cloud Messaging dependencies (for push)
api ('com.google.firebase:firebase-core:16.0.9')
api 'com.google.firebase:firebase-messaging:19.0.0'

// Include Google play services auth module to use Open ID.
googleImplementation 'com.google.android.gms:play-services-auth:17.0.0'

//needed for firebase DB to store user management
googleImplementation 'com.google.firebase:firebase-database:18.0.0'

//needed for firebase DB rules checking auth to work
googleImplementation 'com.google.firebase:firebase-auth:18.0.0'

//Google People Api for contact management
googleImplementation 'com.google.apis:google-api-services-people:v1-rev329-1.25.0'

//Microsoft Graph SDK used to access and update users in the active directory
azureImplementation 'com.microsoft.graph:msgraph-sdk-android:1.3.2'

//Microsoft Authentication Library used for requesting authentication tokens
azureImplementation ('com.microsoft.identity.client:msal:0.1.1') {
    //Exclude older versions of app compat and custom tabs included in msal library
    exclude group: 'com.android.support', module: 'appcompat-v7'
    exclude group: 'com.android.support', module: 'customtabs'
}

//Get matching version of customtabs to use with msal
azureImplementation 'androidx.browser:browser:1.0.0'

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.

Gradle Configuration

The Support library includes a Gradle flavor dimension to control which type of identity provider it should use. Use the authProvider flavor to define the supported identity providers in your application.

Flavor Name Description
_mockProvider

This flavor supports sandbox domains where user authentication is disabled.

This flavor includes support for either BlackBerry Key Management Service or Cloud Key Storage.

azure This flavor supports:

This flavor includes the Microsoft Authentication Library for Android and Microsoft Graph SDK for Android libraries as dependencies.

google This flavor supports:

This flavor includes play-services-auth, firebase-database, firebase-auth and google-api-services-people libraries as dependencies.

noAuthProvider

This flavor configures the Support library to not include any specific identity provider or user management support components. Use this flavor if your application integrates with such services on its own. This flavor reduces the dependencies of the Support library and your application.

This flavor includes support for either BlackBerry Key Management Service or Cloud Key Storage.

If your application only requires a single flavor variant, you can omit the matching flavor definitions in your build.gradle file if you include a missingDimensionStrategy.

//This application only uses the _mockProvider flavor
missingDimensionStrategy "authProvider", "_mockProvider"

To add the support library to your project, add a new project reference in your settings.gradle file. The projectDir property should reference the location of the Support library.

include ':Support'
project(':Support').projectDir = new File(settingsDir, "../Support/Support")

Add the Support Library as a dependency in the app build.gradle file.

dependencies {
  implementation project(path: ':Support')
  // ... other dependencies
}

BlackBerry Key Management Service

The Support library includes code that helps you integrate with the SDK's built-in support for the BlackBerry Key Management Service.

To use this feature, initialize the KeySourceManager with an instance of BlackBerryKMSSource. You must provide an implementation of the PasscodeProvider interface to the BlackBerryKMSSource.

KeySource keySource = new BlackBerryKMSSource(new UserChallengePasscodeProvider(context));
KeySourceManager.setKeySource(keySource);
keySource.start();

Cloud Key Storage

The Support library includes code that helps you integrate with your choice of storage solution for Cloud Key Storage.

The Support library's ProtectedManager singleton delegates Cloud Key Storage requests from the SDK to a KeyStorageProvider that you provide to an instance of KeySourceManager. The Support library offers a different set of KeyStorageProvider implementations depending on which flavor you select during Gradle configuration. You can also provide your own your custom KeyStorageProvider implementation if your application uses a storage solution that isn't supported by the library.

When using Cloud Key Storage, the SDK requests the local user's public and private keys from the KeyStorageProvider. The ProtectedManager singleton observes the keyState for chats, users, and the GlobalProfileKeysState. When the keyState or profileKeysState indicate that key import is required, the ProtectedManager class fetches the keys from your storage solution.

You can register a KeyImportFailureListener to be notified when errors occur while importing identity, user, or chat keys.

//Set a default KeyImportFailureListener.
ProtectedManager.getInstance().setKeyImportFailureListener(
    new DefaultKeyImportFailureListener(fbKeyStorageProvider));

Chat Message Loading

The Support library includes the ChatMessageList class to help your applicaton load ChatMessage objects. ChatMessageList will pre-fetch ChatMessage objects for smooth scrolling through a chat. ChatMessageList implements IncrementalListObservable which can be used to connect the ChatMessageList to an adapter. See the SimpleChat example for a guide on how to use ChatMessageList with a RecyclerView.