Getting Started With BlackBerry Messenger Enterprise SDK
Close
    • Getting Started With BlackBerry Messenger Enterprise SDK
    • Notice of Rights
    • Notice of Liability
    • Trademark Notice
    • About SitePoint
    • Architecture Overview
    • Features
    • Example Applications
    • BBMDS: The BBM Data Service Protocol
    • Who Should Read This Book?
    • Conventions Used
    • Getting Started with Android
    • Getting Started with iOS
    • Getting Started with Node.js
    • Getting Started with Web
    • How It Works
    • OAuth 2.0
    • OpenID Connect
    • Azure Identity Management
    • Configure the BBM Enterprise SDK Domain
    • Associating Application and BBM Enterprise User Identities
    • Contact Discovery and Management
    • Firebase User Management
    • Azure User Management
    • Terminology
    • Chats
    • Participants
    • Messages
    • The Lifecycle of a Chat
    • Chat Administration
    • Chat Message Attachments
    • Thumb Attachments
    • File Attachments
    • Chat Message References
    • Push Notifications
    • Persistent and Ephemeral Endpoints
    • Endpoint Management
    • Synchronization
    • Counter
    • Counter Histogram
    • Size Histogram
    • Stat Collection
    • Defined Stats
    • Data Connection
    • Data Channel
    • Cloud Key Storage
    • Cryptography
    • Conclusion

Getting Started

You can integrate the BBM Enterprise SDK into your  Android, iOS, JavaScript (Web or Node.js) application by following the steps outlined in the platform specific guides below. You can download the SDK from the developer resources page.

To use the BBM Enterprise SDK, you require a registered domain for your application. The following onboarding steps gather the necessary information for your BBM Enterprise SDK enabled application to connect to the BBM Enterprise servers.

Before your application can be deployed in a production environment, you must complete the following steps:

  1. Provide the URL for your Open ID connect UserInfo endpoint.
  2. Provide Push Notification details so BBM Enterprise servers can initiate push notification requests.

The BBM Enterprise SDK contains example applications that demonstrates basic SDK usage such as:

  • How to authenticate a user using Open ID Connect
  • How to start BBM Enterprise SDK services.
  • Starting a new conversation.
  • Opening an existing conversation.
  • Sending and receiving messages in a conversation.
  • User typing indicators, message delivery and message read receipts.
  • Voice and Video calling.

Each BBM Enterprise SDK Partner application will be assigned a private domain. User account creation, authentication and instant messaging will only occur within your application's domain. This means your application cannot send and receive messages with BBM Enterprise SDK applications that use other domains, or with the BBM Enterprise standalone application.

Getting Started with Android

This overview will guide you through the steps required to integrate the BBM Enterprise SDK for Android with your application.

Requirements

  • Android Studio version 2.0 or later, with SDK API level 19 or higher
  • Java version 1.7 or later
  • Android 4.4 or later

Adding BBM Enterprise SDK to your project

Add BBM Enterprise SDK Archive to your project

  1. Download and extract the latest version of the BBM Enterprise SDK on your hard drive.
  2. Copy sdk/bbm_sdk-release.aar into your application's libs directory.

Add a dependency on the BBM Enterprise SDK

  1. Open the application's app/build.gradle file
  2. To add a dependency on the BBM Enterprise SDK, see the sample code below.
repositories {    flatDir {        dirs 'libs' // This indicates the location of bbm_sdk-release.aar    }}
dependencies {    compile 'com.google.guava:guava:18.0'       // The guava library is required by    ➥ the BBM Enterprise SDK    compile (name:'bbm_sdk-release', ext:'aar') // This indicates the dependency on    ➥ the BBM Enterprise SDK    ...}

Configure the BBM Enterprise SDK with your registered domain

When you subscribe to use the BBM Enterprise SDK, your application is assigned a registered domain.

  1. Open your application's AndroidManifest.xml
  2. To configure the BBM Enterprise SDK with your registered domain, see the sample code below.
<application

    <!-- Configure the BBM Enterprise SDK with the user domain -->    <meta-data android:name="com.bbm.sdk.UserDomain"     ➥android:value="MY_USER_DOMAIN"/>

Configure your application to connect to the sandbox development servers

It is recommended that you do your development and integration testing in the BBM Enterprise sandbox environment.

To point your application to connect to the BBM Enterprise SDK sandbox environment, add the following to the AndroidManifest.xml:

<application

   <!--This is used to point the SDK to either the Production environment or the    Sandbox by default this is pointed to production. If you want to use the Sandbox   environment add the below to your manifest-->   <meta-data android:name="com.bbm.sdk.environment.sandbox" android:value="true"/>

Start the BBM Enterprise SDK

To start the BBM Enterprise SDK, see the sample code below.

// First, you must initialize the BBM Enterprise SDK,// by passing the application contextBBMEnterprise.getInstance().initialize(getApplicationContext());
// Once initialized, you can start the BBM Enterprise SDK.BBMEnterprise.getInstance().start();

Further information can be found in the BBM Enterprise SDK guide.

Getting Started with iOS

This overview will guide you through the steps required to integrate the BBM Enterprise SDK for iOS with your application.

Requirements

  • Xcode version 8 or later
  • Deployment target of iOS version 9.0 or later

Install the BBM Enterprise SDK and set up your application

Import the BBM Enterprise SDK into your Xcode project

The BBM Enterprise SDK contains a framework must be imported into your project:

  1. Download and extract the BBM Enterprise SDK archive.
  2. Copy the contents of the sdk and sdk-release folders to your Xcode project folder.
  3. Drag BBMEnterprise.Framework into the Frameworks folder of your project in Xcode.

    Use the Correct Version

    There are two versions of the framework included with the BBM Enterprise SDK. The version in sdk includes an i386 and x86_64 simulator segment and as such, is not suitable for submissions to the App Store. The version in sdk-release contains only the armv7 and arm64 segments and is suitable for app store submission. When building your App Store release submission, to ensure the correct version is embedded in your IPA.

  4. Under TARGETS, click the target for your application.
  5. At the top of the screen, click Build Settings.
  6. In the search text field in the upper right corner of the screen, type Framework Search Paths.
  7. On the left side of the screen, drag the directory in which you placed BBMEnterprise.framework into the Framework Search Paths.

Dragging the directory into the right place

  1. In the search text field in the upper right corner of the screen, type Bitcode.
  2. Next to Enable Bitcode, in the drop-down list, select No.

Making sure Bitcode in not enabled

  1. Drag the BBMEnterprise.framework into the Embedded Binaries section of the general settings for your application target.

If You're Building for the Simulator

Embed the BBMEnterprise.framework from sdk, not sdk-release, if building for the simulator.

  1. In Xcode, under TARGETS, click the target for your application.
  2. At the top of the screen, click Capabilities.
  3. Select the check boxes next to all the following modes:
  • Audio, AirPlay, and Picture in Picture - this allows your application to play audio alerts when a user receives voice or video calls (each user must grant permission for the app to use the microphone prior to using it for the first time.
  • Voice over IP - this allows your application to make and receive voice and video calls.

    PushKit

    PushKit is used for handling push notifications for incoming VoIP calls. VoIP background mode is obsolete in iOS 10 and Xcode 8.

  • Remote Notifications - this allows your application to display incoming messages while the application is running in the background.

Adding background modes

This will add the necessary background modes to your application's Info.plist.

<key>UIBackgroundModes</key>  <array>          <string>voip</string>          <string>audio</string>          <string>remote-notification</string>  </array>

See Apple's programming guide on Background execution for additional information.

Start BBM Enterprise

To start the BBM Enterprise SDK, see the sample code below. For more info, see the comments in the sample code below.

// Start BBM Enterprise SDK services by supplying your required unique BBM //Enterprise domain,which is provided by the BBM Enterprise team when you //sign up to use the SDK[[BBMEnterpriseService service] startService:@"<Domain UUID>" environment:kBBM➥Config_Sandbox completionBlock:^(BOOL success) {    // Update the UI once there is a response.    // Perform any appropriate actions here such as display existing chats
    // Once BBM Enterprise SDK services have successfully started,    // you may now invoke BBMEnterprise service API sendAuthToken}];

The environment parameter will determine which servers the BBM Enterprise SDK will connect to. When testing your application, you should specify kBBMConfig_Sandbox as the environment. The application that you ship to customers should specify kBBMConfig_Production as the environment.

BBM Enterprise Support Classes

Source code for several helper classes can be found in /examples/Support. Classes and interfaces for handling authentication, key management, and user management are provided. Where applicable, these classes are written to allow you to utilize your own back-end storage or authentication scheme. Sample implementations based on GoogleId/Firebase and Microsoft Azure Active Directory are provided and used throughout the sample applications.

If using the support code in your application please note the following:

  • A generic Swift bridging header is included but is written specifically to support the BBME sample applications. You may need to modify this to include or exclude the classes you wish to use. If you are not using Firebase or GoogleId, these specific sections should be omitted for example.
  • If your application is a Swift application, ensure that you add the path to the supplied bridging header to the Objective-C Bridging Header bridging headers location in your project properties or add the relevant classes to your existing bridging header
  • Ensure that you add the correct header search paths for the support classes.

    • Further information can be found in the BBM Enterprise SDK guide.

Getting Started with Node.js

This overview will guide you through the steps required to integrate the BBM Enterprise SDK for Node.js with your application.

This SDK is Isomorphic

This SDK is should be used instead of the BBM Enterprise Web SDK for web development where development is done with Node.js tooling.

There are some differences between the BBM Enterprise SDK for JavaScript (Node.js and Web) and the BBM Enterprise SDK for mobile (Android and iOS) because it is intended to operate in either a web browser or a Node.js application. These are the important differences:

  • Data is not stored persistently.

The BBM Enterprise SDK for mobile devices persistently stores all chat messages and metadata that they receive. The BBM Enterprise SDK for Javascript caches messages and chat metadata in memory while running, but it does not store anything persistently. It downloads chat metadata when first launched, and then downloads messages for a chat on demand only.

  • Messages are downloaded on demand.

The BBM Enterprise SDK for mobile devices will download all messages during initial setup. The BBM Enterprise SDK for JavaScript does not, but instead provides APIs to retrieve only some messages at a time from a specified chat.

  • Attachments are not downloaded automatically.

The BBM Enterprise SDK for mobile devices automatically downloads any attachment received, and stores the attachment persistently. The BBM Enterprise SDK for JavaScript does not download attachments automatically. Instead, it provides a download function which will retrieve the attachment attached to a message. The attachments are not cached when they are downloaded. The client can download the attachment multiple times, but this could cause a lot of network traffic.

  • The list of chats may be filtered.

Unlike with the BBM Enterprise SDK for mobile devices, the BBM Enterprise SDK for JavaScript can be configured to act as if the user is subscribed to a subset of the chats to which a user has been granted permission. When in this mode, any message from a chat not on the allowed list is dropped, including invitations to new chats which are not on the list. The list can be reconfigured at any time to add chats to which the user already has permission.

Prerequisites

  • Node.js version 6.0 or later (8.0 or later is recommended)
  • A native compiler which can be run from node-gyp. Only installing the compiler needs to be done as per these instructions, the usage of node-gyp is handled within the SDK.

Adding BBM Enterprise SDK to your project

Install the BBM Enterprise SDK package

  1. Download and extract the latest version of the BBM Enterprise SDK to your hard drive.
  2. Initialize a directory structure for a node project by running:
npm init

From the initialized project, run:

npm install FILENAME --production

where FILENAME is the path to the file downloaded above.

Content Security Policy

If you want to enable Content Security Policy (CSP), the Content-Security-Policy HTTPS header value shown below allows the BBM Enterprise SDK to function correctly. Depending on the implementations chosen, other servers may be accessed by the authentication, user management or key provider modules, and may need to be listed as well.

default-src 'self'; connect-src https://*.bbmenterprise.com wss://*.➥bbmenterprise.com;

Start the BBM Enterprise SDK

In your application, import the BBMEnterprise module:

var BBMEnterprise = require('bbm-enterprise')

Then instantiate the BBM Enterprise SDK by passing the domain, environment, userId, description, getToken function and getKeyProvider function, and optionally the nickname and messageStorageFactory.

// Initialize the BBM Enterprise SDKvar messenger = new BBMEnterprise.Messenger({  // The domain provided to you when registering for usage of BBM Enterprise SDK.  // This will be of the form XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX. where each X is   // a lowercase character or number.  domain: 'domain'
  // It is recommended that you do your development and integration testing   // in the BBM Enterprise sandbox environment.  environment: 'Sandbox'
  // This is the identity of the user to log in as, as provided by   // the identity provider module.  userId: 'identifier'
  // This function will be called as needed by the SDK to retrieve an   // authentication token.When a token is needed, this function should fetch  // a new one. The SDK will request a token once on startup, but will not   //request again after that until the current token  // becomes invalid. The function should not perform caching of the token.  getToken: function() {...}
  // This function returns a KeyProvider corresponding to the KeyProvider interface.  // Please see the JSDoc documentation for a full description of this interface.  getKeyProvider: function() {...}
  // A description of the client. This will be used to describe this endpoint when   // using endpoint management functionality. This should never be empty. The   // description can be a maximum of 2000 Unicode Code Points.  description: 'node ' + process.version
  // A friendly name in addition to the description. The nickname is optional and   // should be set by a user, if desired.  nickname: 'My node client'
  // A storage factory may be chosen based on how the client wants to be notified   // of changes to the message list. The default Immutable storage factory is ideal   // for clients that want to receive messages in immutable list and calculate   // differences from a previous list to see what has changed. The SpliceWatcher   // factory is ideal for clients that want to be notified about what has changed   // through a series of splice calls.  messageStorageFactory: BBMEnterprise.StorageFactory.SpliceWatcher})

Then, start it.

// Start the BBM Enterprise SDKmessenger.setup()

Getting Started with Web

This overview will guide you through the steps required to integrate the BBM Enterprise SDK for Web with your application.

Don't Use This SDK With Node-based Tooling

This SDK should be used when you want to be able to drop an SDK into a web page with the inclusion of a <script> tag. Do not use this SDK with Node-based tooling to process JavaScript modules into a web app. For these tools, use BBM Enterprise SDK for Node.js, which provides the same functionality in an isomorphic node package.

There are some differences between the BBM Enterprise SDK for JavaScript (Node.js and Web) and the BBM Enterprise SDK for mobile (Android and iOS) because it is intended to operate in either a web browser or a Node.js application. These are the important differences:

  • Data is not stored persistently.

The BBM Enterprise SDK for mobile devices persistently stores all chat messages and metadata that they receive. The BBM Enterprise SDK for Javascript caches messages and chat metadata in memory while running, but it does not store anything persistently. It downloads chat metadata when first launched, and then downloads messages for a chat on demand only.

  • Messages are downloaded on demand.

The BBM Enterprise SDK for mobile devices will download all messages during initial setup. The BBM Enterprise SDK for JavaScript does not, but instead provides APIs to retrieve only some messages at a time from a specified chat.

  • Attachments are not downloaded automatically.

The BBM Enterprise SDK for mobile devices automatically downloads any attachment received, and stores the attachment persistently. The BBM Enterprise SDK for JavaScript does not download attachments automatically. Instead, it provides a download function which will retrieve the attachment attached to a message. The attachments are not cached when they are downloaded. The client can download the attachment multiple times, but this could cause a lot of network traffic.

  • The list of chats may be filtered.

Unlike with the BBM Enterprise SDK for mobile devices, the BBM Enterprise SDK for JavaScript can be configured to act as if the user is subscribed to a subset of the chats to which a user has been granted permission. When in this mode, any message from a chat not on the allowed list is dropped, including invitations to new chats which are not on the list. The list can be reconfigured at any time to add chats to which the user already has permission.

Prerequisites

  • A supported browser

The least commonly supported features of browsers used by BBM Enterprise SDK for Web are:

In general, all browsers that support these can run BBM Enterprise SDK for web.

Note that WebCrypto is only available in a secure context, so it is recommended that you serve pages using the BBM Enterprise SDK over HTTPS instead of HTTP.

To check if a browser is supported, call the following function prior to accessing any other functionality, or requiring the user to log in. This will determine if the user's browser is compatible with the SDK and allows them to change to another browser before performing any further steps.:

BBMEnterprise.validateBrowser()

The following browsers are supported:

  • Google Chrome 59 and newer
  • Mozilla Firefox 53 and newer

Safari and Microsoft Edge are not supported because they do not include the P-521 ECC algorithms in WebCrypto. Other than this limitation, the BBM Enterprise SDK will work on Safari 9 or Edge 16.16299. Although an integrator of the SDK can add full WebCrypto support to Safari by including a WebCrypto polyfill prior to the bbm_sdk_web.js script tag, this is strongly not recommended because the polyfill will reduce the security of the system.

The SDK may be run in a web worker in any supported browser as well as in Safari (Safari is subject to the same caveat as when not running in a WebWorker).

For Microsoft Edge, there is the additional problem that there is no source of cryptographically strong random numbers available inside the WebWorker in Edge. As such, providing a polyfill for WebCrypto getRandomValues API will probably require passing at least a random number generator seed into the web worker from outside.

Adding BBM Enterprise SDK to your project

Add BBM Enterprise SDK Archive to your project

  1. Download and extract the latest version of the BBM Enterprise SDK to your hard drive.

  2. Copy sdk/bbm_sdk_web.js to your application's directory.

  3. In your web page, reference the copied file in a script tag.

<script src="path/to/bbm_sdk_web.js"></script>

This provides access to the global BBMEnterprise object, which can be used to access BBMEnterprise SDK functionality.

Content Security Policy

If you want to enable Content Security Policy (CSP), the Content-Security-Policy HTTPS header value shown below allows the BBM Enterprise SDK to function correctly. Depending on the implementations chosen, other servers may be accessed by the authentication, user management or key provider modules, and may need to be listed as well.

default-src 'self'; connect-src https://*.bbmenterprise.com wss://*.➥bbmenterprise.com;

Start the BBM Enterprise SDK

In your application, initialize the BBM Enterprise SDK by passing the domain, environment, userId, description, getToken function and getKeyProvider function, and optionally the nickname and messageStorageFactory.

// Initialize the BBM Enterprise SDKvar messenger = new BBMEnterprise.Messenger({  // The domain provided to you when registering for usage of BBM Enterprise SDK.  // This will be of the form XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX. where each X is   // a lowercase character or number.  domain: 'domain'
  // It is recommended that you do your development and integration testing   // in the BBM Enterprise sandbox environment.  environment: 'Sandbox'
  // This is the identity of the user to log in as, as provided by the identity  // provider module.  userId: 'identifier'
  // This function will be called as needed by the SDK to retrieve an authentication   // token. When a token is needed, this function should fetch a new one. The SDK   // will request a token once on startup, but will not request again after that   // until the current token becomes invalid. The function should not perform caching   // of the token.  getToken: function() {...}
  // This function returns a KeyProvider corresponding to the KeyProvider interface.   // Please see the JSDoc documentation for a full description of this interface.  getKeyProvider: function() {...}
  // A description of the client. This will be used to describe this endpoint when   // using endpoint management functionality. This should never be empty. The   // description can be a maximum of 2000 Unicode Code Points.  description: navigator.userAgent
  // A friendly name in addition to the description. The nickname is optional and   // should be set by a user, if desired.  nickname: 'My web client'
  // A storage factory may be chosen based on how the client wants to be notified  // of changesto the message list. The default Immutable storage factory is ideal   // for clients thatwant to receive messages in immutable list and calculate   // differences from a previous list to see what has changed. The SpliceWatcher   // factory is ideal for clients that want to be notified about what has changed   // through a series of splice calls.  messageStorageFactory: BBMEnterprise.StorageFactory.SpliceWatcher})

Then, start it.

// Start the BBM Enterprise SDKmessenger.setup()

Community Questions