BlackBerry Dynamics

Get Started with BlackBerry Development Tools

Get Started with BlackBerry Dynamics SDK

Develop your first secure mobile app now at no cost with the help of the powerful BlackBerry Dynamics Secure Mobility Platform.

The BlackBerry Dynamics Platform provides a range of SDKs and plugins that allow you to develop in the environment of your choice and build native, hybrid, or web apps. 

This resource is intended to give you a quick start in developing your first BlackBerry Dynamics app. To see the full Development Guide and Release Notes for each available platform of the BlackBerry Dynamics SDK, visit BlackBerry Docs.

Choose a platform and click Next.

Discover the components and benefits of the BlackBerry Dynamics Secure Mobility Platform. This resource provides information about using the BlackBerry Dynamics SDK for iOS, Android, Cordova and React Native. For more information about using the SDK for all available platforms, see the BlackBerry Dynamics SDK Documentation.

 

Discover the components and benefits of the BlackBerry Dynamics Secure Mobility Platform. This resource provides information about using the BlackBerry Dynamics SDK for iOS, Android, Cordova and React Native. For more information about using the SDK for all available platforms, see the BlackBerry Dynamics SDK Documentation.

 

Discover the components and benefits of the BlackBerry Dynamics Secure Mobility Platform. This resource provides information about using the BlackBerry Dynamics SDK for iOS, Android, Cordova and React Native. For more information about using the SDK for all available platforms, see the BlackBerry Dynamics SDK Documentation.

 

Discover the components and benefits of the BlackBerry Dynamics Secure Mobility Platform. This resource provides information about using the BlackBerry Dynamics SDK for iOS, Android, Cordova and React Native. For more information about using the SDK for all available platforms, see the BlackBerry Dynamics SDK Documentation.

 

The BlackBerry Dynamics SDK provides a powerful set of tools to ISV and enterprise developers. It allows developers to focus on building commercial and business apps rather than learning how to secure, deploy, and manage those apps. The BlackBerry Dynamics Platform includes:

  • Lifecycle management
  • Security and compliance policies
  • Secure connectivity to enterprise services
  • Secure storage
  • Secure inter-app communication
  • Application configuration and application specific policies

The simplest way to understand the BlackBerry Dynamics platform is to think of it as three key components: the BlackBerry Dynamics SDK and BlackBerry servers (BlackBerry UEM) connected by BlackBerry Cloud Infrastructre (or Network Operatioons Centre). BlackBerry Dynamics provides the services and architecture to build, securely deploy, and manage apps. BlackBerry UEM includes the BlackBerry Dynamics Secure Mobility Platform and delivers the Enterprise Mobility Management (EMM) solution to securely manage devices.

With the acquisition of Good Technology by BlackBerry, BlackBerry has created a unified product with best-in-class Bring Your Own Device (BYOD), EMM, and Mobile Device Management (MDM) capabilities.

 

BlackBerry Dynamics Secure Mobility Platform

The BlackBerry Dynamics (BD) platform consists of BD Runtime, the BD Network Operation Center (NOC), and BD servers.

The BD Runtime is included in every BD mobile app. The runtime has an API that gives the app access to activation, user authentication, secure storage, communication behind the firewall, and much more, all while enforcing security policies on behalf of the organization. To work with the BD Runtime, you need to download the BlackBerry Dynamics SDK for the target platform (iOS, Android, Cordova, React Native).

By including the BlackBerry Dynamics SDK in your app, you will have access to app policies, inter-app communication, secure storage, shared services, authentication delegation, single sign-on (KCD), user and app config information, and much more.

 

BlackBerry UEM

BlackBerry UEM is the server component that brings everything together. It merges the best-in-class BYOD functionality of BlackBerry Dynamics with the best-in-class EMM (including MDM) solution. Administrators use UEM to manage users, groups, policies, apps, app configurations, and more.

The BlackBerry Cloud Infrastructure (or NOC) enables secure communication between your BD Runtime app and the BlackBerry Proxy. The BlackBerry Cloud also verifies the validity of user and access keys before data touches your enterprise, in addition to supporting the secure push infrastructure from server-side apps to BD Runtime apps.

UEM includes the BlackBerry Proxy servers as part of the EMM solution. They provide various services to users, devices and apps.

For app developers, you get:

  • Security and compliance policies
  • Secure connectivity to enterprise services
  • App configuration
  • App policies
  • Secure storage on-device
  • Wipe and lock functionality
  • Secure inter-app communication
  • Application lifecycle management

 

BlackBerry Enterprise Mobility Server (BEMS)

The BlackBerry Dynamics platform offers enterprise mBaaS (Mobile Backend as a Service) capabilities. Many of these mBaaS services are implemented in the BlackBerry Enterprise Mobility Server (BEMS). BEMS provides programmatic connectivity through standardized APIs to enterprise systems including Microsoft SharePoint, Microsoft Teams, Microsoft Exchange, Cisco Jabber, Active Directory and more. BEMS provides APIs to invoke services such as push notifications, directory lookups, key value store, document access, IM, and presence. Developers can add these services to apps without having extensive knowledge of how to configure or connect to specific back-end systems of records.

These high quality enterprise back-end services are leveraged by BlackBerry Work, BlackBerry Connect, and other BlackBerry Secured apps. ISV and custom BlackBerry Secured apps can also make use of these services.

The BlackBerry Dynamics Platform provides a range of SDKs and plug-ins, allowing developers to work in familiar environments to build native, hybrid, and web apps. Once apps are built, developers can assume the role of an IT admin to quickly validate the management and distribution of their apps through the BlackBerry Dynamics Platform.

The BlackBerry Dynamics SDK is available natively to major platforms and development technologies including iOS and Android.

In addition, BlackBerry supports cross-platform development frameworks via dedicated BlackBerry Dynamics SDKs for Cordova and React Native.

Security Services

Security Services allow you to address security concerns about making sensitive company information available on mobile devices. You can ensure that the content that is stored on devices, exchanged with resources behind the corporate firewall, or shared between BlackBerry-secured apps is always encrypted. Since the platform uses government-grade device-independent crypto libraries, content is always encrypted. The BlackBerry Dynamics SDK includes support for the following security services:

  • Identity & Authorization APIs
  • Secure Storage APIs
  • Secure Communications APIs
  • Secure Inter-App Data Exchange APIs

Mobile Services

Mobile Services allow you to create engaging apps that will improve user productivity. You can reduce development time by using existing services -- no more building everything from scratch! And because the BlackBerry Dynamics Platform is the foundation for all services, government-grade encryption ensures end-to-end security. The BlackBerry Dynamics SDK includes support for the following mobile services:

  • Presence Service
  • Send Email Service
  • Transfer Files Service
  • Push Service
  • Directory Lookup Service
  • Docs Service
  • Launch Service

Platform Services

Platform Services make it easy to integrate apps with enterprise infrastructure (e.g., Active Directory, SharePoint, Exchange, Office 365, Lync). Focus on creating innovative apps without worrying about programming for the back-end, server maintenance, or deploying complex infrastructure. Single sign-on, horizontal scaling, HA/DR, VPN-less access to the intranet -- simply building on the current version of the BlackBerry Dynamics Platform enables it all. The BlackBerry Dynamics SDK includes support for the following mobile services:

  • Identity & Access Management
  • Single Sign-on Authentication
  • Reliable App Deployment at Scale
  • Secure Access to Corporate Data
  • App-Level Controls for IT

Software requirements

See Requirements and support for platform-specific features in the BlackBerry Dynamics SDK Development Guide.

Download, install & configure the BlackBerry Dynamics SDK for iOS

Use one of the following methods to integrate the BlackBerry Dynamics SDK. It is a best practice to integrate the SDK using CocoaPods.

  1. If you don't have a Podfile refer to https://cocoapods.org/ for how to create one
  2. In your Podfile add the following reference to the BlackBerry Dynamics SDK pod:pod 'BlackBerryDynamics'
  3. To add the BlackBerry Dynamics ATSL to the target app for UI tests, in your Podfile add the following pod:pod 'BlackBerryDynamicsAutomatedTestSupportLibrary'
    For more information, see Add automated testing to your BlackBerry Dynamics iOS app.
  4. If default. xcconfig is used by your application, add the following to the end of your Podfile:
    post_install do |installer|
        # Append configuration from default.xcconfig to configuration generated by Cocoapods
        if Dir.glob("**/default.xcconfig").first()
            system("find Pods -name 'Pods-*.xcconfig' -exec sh -c 'cat 'find . -name default.xcconfig' »> $1' -- (} \ \;")
        end
    end
  5. Install the pods, then open your workspace file to see the project in Xcode:$ pod install 
  1. Extract the contents of the BlackBerry_Dynamics_SDK_for_iOS_<version>_dylib.tar.gz file into a directory.
  2. From the directory Frameworks in the extracted SDK package copy all the framework files into your desired directory.
  3. Import the frameworks into the project by dragging them from the directory
  4. In the Frameworks, Libraries and Embedded Content list of the project target:

    • Add BlackBerryDynamics.xcframework, BlackBerryCerticom.xcframework, BlackBerryCerticomSBGSE.xcframework; if needed add the BlackBerryDynamicsAutomatedTestSupportLibrary.xcframework
    • Set all of the above frameworks to Embed and Sign so that Xcode will change the project file by adding the frameworks to the Embed Frameworks step in the Build Phases and will configure the Runpath Search Paths accordingly.

For complete instructions, including how to prepare existing and new apps to use the frameworks, see the BlackBerry Dynamic SDK Development Guide.

Software requirements

See Requirements and support for platform-specific features in the BlackBerry Dynamics SDK Development Guide.

Download, install & configure the BlackBerry Dynamics SDK for Android

The BlackBerry Dynamics SDK can be integrated into an Android app using Gradle.

In the build.gradle file of the app add the following:

Repositories configuration

repositories {

    // BlackBerry Dynamics SDK repository
    maven { url 'https://software.download.blackberry.com/repository/maven' }

    // other repositories
}

Dependencies configuration

// Adjust this value according to the latest version available on the BlackBerry developer website
def dynamicsVersion = '11.2.0.10'

dependencies {

    // Main BlackBerry Dynamics SDK library
    implementation "com.blackberry.blackberrydynamics:android_handheld_platform:${dynamicsVersion}"

    // Optional libraries of BlackBerry Dynamics SDK

    // To use the secure version of the AndroidWebView
    implementation "com.blackberry.blackberrydynamics:android_webview:${dynamicsVersion}"

    // Provides support for secure backup if the app uses the feature
    implementation "com.blackberry.blackberrydynamics:android_handheld_backup_support:${dynamicsVersion}"

    // Include this if the app performs SafetyNet or PlayStore attestation flows
    implementation "com.blackberry.blackberrydynamics:android_handheld_gd_safetynet:${dynamicsVersion}"

    // For integration with BlackBerry Protect
    implementation "com.blackberry.blackberrydynamics:android_handheld_blackberry_protect_support:${dynamicsVersion}"

    // For automated testing of UI controlled by BlackBerry Dynamics SDK
    testImplementation "com.blackberry.blackberrydynamics:atsl:${dynamicsVersion}"

    // other dependencies
}

Note: The BlackBerry Dynamics SDK package available in the Downloads section of the BlackBerry developer website contains a convenient folder that contains a Maven-compliant structure so it can be used locally or uploaded to any internal Maven-compliant server; to use it, the URL of the Maven repository in the app's build.gradle will have to be adjusted accordingly.

For complete instructions, including how to prepare existing and new apps to use the frameworks, see the BlackBerry Dynamic SDK Development Guide.

Software requirements

See Requirements and support for platform-specific features in the BlackBerry Dynamics SDK Development Guide.

Install the BlackBerry Dynamics SDK for Cordova

1. Visit BlackBerry Developer Downloads to download the BlackBerry Dynamics SDK for Cordova.

2. Extract the BlackBerry Dynamics SDK for Cordova package to the desired project directory.

3. When you add the BlackBerry Dynamics Base plug-in to your project, the BlackBerry Dynamics SDK for iOS is automatically downloaded using CocoaPods. For additional information, see the BlackBerry Dynamics SDK Development Guide.

4. Install Xcode.

5. Install Node.js.

After the installation completes, the npm command is available in your terminal shell.

  • In the config.xml file, set the following to enable the enterprise discovery scheme that is required for key BlackBerry Dynamics features:

<preference name=“BBD_Enterprise_Discovery” value=“true” />

  • To enable enterprise simulation mode, in the config.xml file, set the following:

<preference name=“GDEnterpriseSimulationMode” value=“true” />

Software requirements

See Requirements and support for platform-specific features in the BlackBerry Dynamics SDK Development Guide.

Install the BlackBerry Dynamics SDK for Cordova

1. Visit BlackBerry Developer Downloads to download the BlackBerry Dynamics SDK for Cordova.

2. Extract the BlackBerry Dynamics SDK for Cordova package to the desired project directory.

3. Install the Android SDK.

4. Integrate the BlackBerry Dynamics SDK for Android. You can use the Base plug-in to download the BlackBerry Dynamics SDK for Android using Gradle. For additional information, see the BlackBerry Dynamics SDK Development Guide.

5. Install the Android SDK/ADT bundle.

6. Install Node.js.

After the installation completes, the npm command is available in your terminal shell.

  • Follow the steps on the Develop tab to install the BlackBerry Dynamics SDK Cordova plug-ins.
  • To enable enterprise simulation mode, in the config.xml file, set the following:

<preference name=“GDEnterpriseSimulationMode” value=“true” />

Develop a BlackBerry Secured App for iOS using Apache Cordova

We’ll be using the standard Cordova CLI to execute all commands.

1. Open your favorite Terminal program.

2. Create a new Cordova project.

$ cordova create HelloBBD com.company.appname

3. Change to the project folder.

$ cd HelloBBD

4. Add platforms.

$ cordova platform add ios

5. Add BlackBerry Dynamics plug-ins. At a minimum, you must add the base plug-in if you want to secure your application with BlackBerry Dynamics.

$ cordova plugin add <path-to-bbd-cordova-plugins>/cordova-plugin-bbd-all

6. Optionally, install the ios-deploy package if you want to install iOS apps from the Cordova command-line.

$ sudo npm install –g ios-deploy

  • If your macOS is v10.11 or greater, you will likely need to run the following command instead (refer to the ios-deploy GitHub repo for more detailed usage instructions: https://github.com/phonegap/ios-deploy:

$ sudo npm install –g ios-deploy --unsafe-perm=true

7. Build the application in Terminal (or Xcode).

$ cordova build ios

You can now deploy and test your app, and can explore development with additional BlackBerry Dynamics APIs. Advance to the next steps to continue.

We’ll be using the standard Cordova CLI to execute all commands.

1. Open your favorite Terminal program.

2. Change to your existing projects folder.

$ cd <MyApp>

3. Add BlackBerry Dynamics plug-ins. At a minimum, you must add the base plug-in if you want to secure your application with BlackBerry Dynamics.

$ cordova plugin add <path-to-bbd-cordova-plugins>/cordova-plugin-bbd-all

4. Build the application.

$ cordova build ios

You can now deploy and test your app, and can explore development with additional BlackBerry Dynamics APIs. Advance to the next steps to continue.

Develop a BlackBerry Secured App for Android using Apache Cordova

We’ll be using the standard Cordova CLI to execute all commands.

1. Open your favorite Terminal program.

2. Create a new Cordova project.

$ cordova create HelloBBD com.company.appName

3. Change to the project folder.

$ cd HelloBBD

4. Add platforms.

$ cordova platform add android

5. Add the BlackBerry Dynamics plugins. At a minimum, you must add the base plugin if you want to secure your application with BlackBerry Dynamics.

$ cordova plugin add <path-to-bbd-cordova-plugins>/cordova-plugin-bbd-all

6. Build the project.

$ cordova build

You can now deploy and test your app, and can explore development with additional BlackBerry Dynamics APIs. Advance to the next steps to continue.

We’ll be using the standard Cordova CLI to execute all commands.

1. Open your favorite Terminal program.

2. Change to your existing projects folder.

$ cd <MyApp>

3. Add BlackBerry Dynamics plugins. At a minimum, you must add the base plugin if you want to secure your application with BlackBerry Dynamics.

$ cordova plugin add <path-to-bbd-cordova-plugins>/cordova-plugin-bbd-all

4. Build the project.

$ cordova build

You can now deploy and test your app, and can explore development with additional BlackBerry Dynamics APIs. Advance to the next steps to continue.

 

Develop a BlackBerry Secured App for Android

The easiest way to get started with the BlackBerry Dynamics SDK for Android is to use the BlackBerry Dynamics sample apps from GitHub.

Go to the BlackBerry Dynamics Android Samples and download either of the following:

Perform the following steps to use the apps:

  1. Ensure the latest version of the BlackBerry Dynamics SDK is configured for dependency com.blackberry.blackberrydynamics:android_handheld_platform 
  2. Edit the GD Application ID to your own in file assets/settings.json 
    Note:  The general form is com.yourcompany.application_name (lowercase only, no spaces, and must not begin with com.good or com.blackberry). The same id can be used for multiple apps on different platforms, such as iOS and Android, so it is a best practice to avoid platform-specific information (example: com.yourcompany.android.application).
  3. Build, deploy, and run the app.

For more information, see the BlackBerry Dynamics SDK development guide.

In order to add the BlackBerry Dynamics SDK into an existing project, perform the actions described in the section "Install & Configure".

Once the BlackBerry Dynamics SDK has been added to the project it needs to be configured, perform the steps below to configure it.

  1. Create a file settings.json inside the assets folder for the app project 
  2. Set the BlackBerry Dynamics Application ID and BlackBerry Dynamics Version in the settings.json created before.

    GDApplicationID
    The general form is com.yourcompany.application_name (only lower case, no spaces, and must not begin with com.good or com.blackberry).
    The same id can be used for multiple apps on different platforms such as iOS and Android. It’s recommended to avoid including the platform-specific information (example: com.yourcompany.android.application).

    GDApplicationVersion
    A version number is four parts. Use 1.0.0.0 for the first version of the app with BlackBerry Dynamics SDK
    It is not recommended to change the version often unless it’s required to provide different access to specific users or to differentiate a new app from existing versions of the app due to newly added services.

    An example is
    {
        "GDApplicationID":"com.yourcompany.application_name",
        "GDApplicationVersion": "1.0.0.0"
    }
  3. If the app supports backup it needs to include the dependency com.blackberry.blackberrydynamics:android_handheld_backup_support and the below should be added in AndroidManifest.xml to the application tag 
    android:fullBackupContent="@xml/gd_backup_scheme"

Establishing a connection to the BlackBerry Dynamics platform requires the authorization of the end user and the app. There are 2 alternative ways of initiating both authorizations in a BlackBerry Dynamics app:

  • Indirect initiation
  • Direct initiation

An app can use only direct or indirect authorization initiation, not both. Both mechanisms each require different implementations in the app code. The mechanisms also place different restrictions on classes in the app user interface influencing how they interact with the BlackBerry Dynamics SDK.

Authorization generally includes establishing a data connection to the UEM server infrastructure and to the enterprise that provisioned the end user. In addition, authorization will also include any necessary registration of the device, at the BlackBerry Dynamics Network Operation Center (infrastructure activation), and at the enterprise (enterprise activation).

Authorization may include user interaction. All user interaction that is part of authorization takes place in a user interface that is part of the BlackBerry Dynamics Runtime library, not part of the app.

The authorization API is state-based and asynchronous. The initiation method generally returns immediately. Success or failure of authorization is then notified to the app code later, as a transition of the authorization state. The app should generally wait to be notified of the transition to the authorized state before attempting to utilize any other BlackBerry Dynamics APIs.

 

Indirect authorization initiation

When using indirect initiation of the authorization flow, each Activity in the app needs to invoke the activityInit API of GDAndroid class and provide an implementation of interface GDStateListener to listen to the events generated by the BlackBerry Dynamics SDK. 

The GDStateListener provides simple state transition notifications. At each state transition, the corresponding callback methods in the application code would be invoked by the runtime. When the user is authorized the method onAuthorized would be called, after that the app could make full use of all BlackBerry Dynamics APIs. There are no limitations on which class can implement the GDStateListener interface.

The activityInit must be called as early as possible in the Activity lifecycle therefore the onCreate method is the best candidate for it.  

The following snippet shows the indirect initiation of BlackBerry Dynamics authorization processing where the Activity is also implementing the GDStateListener; for more advanced scenarios please refer to the documentation of GDAndroid and GDStateAction classes.

public class MyActivity extends AppCompatActivity implements GDStateListener {

    public void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);

        // Initiate the BlackBerry Dynamics authorization process
        GDAndroid.getInstance().activityInit(this);

        // rest of Activity initialization
    }

    //GDStateListener method implementations
    public void onAuthorized() {
        // Fictional method calls that require BlackBerry Dynamics SDK APIs
        startSecureDBAccess();
        startSecureAppComms();
    }

    // Additional GDStateListener methods
}

class MainActivity : AppCompatActivity(), GDStateListener {

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        // Initiate the BlackBerry Dynamics authorization process
        GDAndroid.getInstance().activityInit(this)

        // rest of Activity initialization
    }

    //GDStateListener method implementations
    override fun onAuthorized() {
        // Fictional method calls that require BlackBerry Dynamics SDK APIs
        startSecureDBAccess()
        startAppComms()
    }

    // Additional GDStateListener methods
}

Direct authorization initiation

When using direct initiation of the authorization flow, the app must invoke the authorize API of GDAndroid class and provide an implementation of interface GDAppEventListener to listen to the events generated by the BlackBerry Dynamics SDK. 

The event handler would receive all GDAppEvent objects dispatched from the  BlackBerry Dynamics Runtime, which would include an event of type GDAppEventAuthorized when the end user is authorized. After receiving that event, the app could make full use of all BlackBerry Dynamics APIs. There are no limitations on which class can implement the GDAppEventListener interface.

In order to make sure that the app is only used after the user has been authorized, regardless of its state, the API authorize should be called in the onResume method only if the user wasn't already authorized.

The following snippet shows the direct initiation of BlackBerry Dynamics authorization processing where the Activity is also implementing the GDAppEventListener; for more advanced scenarios please refer to the documentation of GDAndroid and GDStateAction classes.

public class LaunchActivity extends Activity implements GDAppEventListener {

    private boolean authorizeCalled = false;

    public void onResume() {
        super.onResume();

        if (!authorizeCalled) {
            GDAndroid.getInstance.authorize(this);
            authorizeCalled = true;
        }

        // Rest of activity initialization here, no use of BlackBerry Dynamics APIs.
    }

    public void onGDEvent(GDAppEvent appEvent) {

        switch (appEvent.getEventType()) {
            case GDAppEventAuthorized:

                // start the app UI if user is authorized
                startMainActivity();
                break;

            case GDAppEventNotAuthorized:

                // reset the authorizeCalled flag so the authorization flow can be started
                // again when the onResume is called
                authorizeCalled = false;
                break;

            // handle other GDAppEventType
        }
    }

    // rest of class code here.
}

class LaunchActivity : Activity(), GDAppEventListener {

    private var authorizeCalled = false

    // Override annotation should go here
    override fun onResume() {
        super.onResume()
        if (!authorizeCalled) {
            GDAndroid.getInstance.authorize(this)
            authorizeCalled = true
        }

        // Rest of activity initialization here, no use of BlackBerry Dynamics APIs.
    }

    override fun onGDEvent(appEvent: GDAppEvent?) {
        when (appEvent?.eventType?.ordinal) {

            // start the app UI if user is authorized
            GDAppEventType.GDAppEventAuthorized.ordinal -> startMainActivity()

            // reset the authorizeCalled flag so the authorization flow can be started
            // again when the onResume is called
            GDAppEventType.GDAppEventNotAuthorized.ordinal -> authorizeCalled = false

            // handle other GDAppEventType
        }
    }

    // rest of class code here.
}

Develop a BlackBerry Secured App for iOS

The easiest way to get started with the BlackBerry Dynamics SDK for iOS is to use the BlackBerry Dynamics sample apps from GitHub.

Go to the BlackBerry Dynamics iOS Samples and download either of the following:

Perform the following steps to use the apps:

  1. Run pod install to install the project dependencies including BlackBerry Dynamics
  2. Launch Xcode and open the project.
  3. Edit the Bundle ID to your own.
  4. Edit the URL identifier and URL Schemes in the Info.plist.
  5. Edit the GD Application ID to your own in the Info.plist.
    Note:  The general form is com.yourcompany.application_name (lowercase only, no spaces, and must not begin with com.good or com.blackberry). The same id can be used for multiple apps on different platforms, such as iOS and Android, so it is a best practice to avoid platform-specific information (example: com.yourcompany.ios.application).
  6. Build, deploy, and run the app.

For more information, see the BlackBerry Dynamics SDK development guide.

In order to add the BlackBerry Dynamics SDK into an existing project, perform the actions described in the section "Install & Configure".

Once the BlackBerry Dynamics SDK has been added to the project, perform the steps below to configure it.

  1. Set the BlackBerry Dynamics Application ID and BlackBerry Dynamics Version in the app's Info.plist.

    GDApplicationID

    The general form is com.yourcompany.application_name (only lower case, no spaces, and must not begin with com.good or com.blackberry).
    The same id can be used for multiple apps on different platforms such as iOS and Android. It’s recommended to avoid including the platform-specific information (example: com.yourcompany.ios.application).

    GDApplicationVersion
    A version number is four parts. Use 1.0.0.0 for the first version of the app with BlackBerry Dynamics SDK
    It is not recommended to change the version often unless it’s required to provide different access to specific users or to differentiate a new app from existing versions of the app due to newly added services.

  2. Add a variable reference in the URL scheme and URL identifier specifiers. Add the following code into the info.plist.
    <key>CFBundleURLTypes</key>
    <array>
        <dict>
            <key>CFBundleURLName</key>
            <string>Bundle_Identifier_of_your_app</string>
            <key>CFBundleURLSchemes</key>
            <array>
                <string>Bundle_Identifier_of_your_app.sc2</string>
                <string>Bundle_Identifier_of_your_app.sc2.1.0.0.0</string>
                <string>Bundle_Identifier_of_your_app.sc3</string>
                <string>com.good.gd.discovery</string>
            </array>
        </dict>
    </array>
  3. The BlackBerry Dynamics SDK needs to use the device camera and might be configured to use FaceID authentication, therefore the keys NSFaceIDUsageDescription and NSCameraUsageDescription need to be added to the InfoPlist.strings file if the existing app doesn't do it already.
    "NSFaceIDUsageDescription" = "Enables authentication without a password.";
    "NSCameraUsageDescription" = "Allow camera usage to scan a QR code";

To work as a BlackBerry Dynamics app, the app must use the GDiOSDelegate protocol and the launch code execution must be delayed until the end user has been authorized.

Below are the main steps needed:

  1. Implement the GDiOSDelegate protocol to receive GDAppEvent objects from the BlackBerry Dynamics SDK
  2. Use GDAppEvent provided in the handler method of the GDiOSDelegate to process authorization events.
  3. Switch off the automatic loading of the main storyboard. Instead, load the main storyboard programmatically when the end user has been authorized.
  4. Kick off the authorization process handled by the BlackBerry Dynamics SDK in the app's didFinishLaunchingWithOptions, invoking the method GDiOS.sharedInstance().authorize()

Modify the UIApplicationDelegate to defer the loading of the main UI until the end user is authorized by the BlackBerry Dynamics SDK.

@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate {

    var window: UIWindow?

    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions:
        [UIApplication.LaunchOptionsKey: Any]?) -> Bool {

        // Set the AppDelegate in the GDiOSDelegate
        AppGDiOSDelegate.sharedInstance.appDelegate = self

        // Trigger end-user authorization process with BlackBerry Dynamics SDK
        GDiOS.sharedInstance().authorize(AppGDiOSDelegate.sharedInstance)

        return true
    }
}

Implement the GDiOSDelegate to handle events from the BlackBerry Dynamics SDK and load the main UI when the authorized event is received.

import BlackBerryDynamics.Runtime

class AppGDiOSDelegate : NSObject, GDiOSDelegate {

    static let sharedInstance = AppGDiOSDelegate()

    var hasAuthorized = false
    weak var appDelegate: AppDelegate?

    func handle(_ anEvent:GDAppEvent) {
        switch anEvent.type {
        case .authorized:
            self.onAuthorized(anEvent);
            break
        case .notAuthorized:
            self.onNotAuthorized(anEvent);
            break
        case .remoteSettingsUpdate:
            //A change to application-related configuration or policy settings.
            break
        case .servicesUpdate:
            //A change to services-related configuration.
            break
        case .policyUpdate:
            //A change to one or more application-specific policy settings has been received.
            break
        default:
            print("Event not handled: '\(anEvent.message)'")
            break
        }
    }

    func onAuthorized(_ anEvent: GDAppEvent) {
        // Handle the BlackBerry Dynamics SDK authorized event
        switch anEvent.code {
        case .errorNone :
            if (!hasAuthorized) {
                // Prepare main storyboard and root view controller
                let mainStoryboard: UIStoryboard = UIStoryboard(name: "Main", bundle: Bundle.main)
                let rootViewController = mainStoryboard.instantiateInitialViewController()

                self.appDelegate!.window?.rootViewController = rootViewController
                hasAuthorized = true
            }
        default:
            assert(false, "Authorized startup with an error")
            break
        }
    }
}

Deploy and Test a BlackBerry Dynamics Secured App

Deploy your BlackBerry Dynamics app to a smartphone, tablet, or emulator for testing purposes.

You require:

  • An Internet connection
  • A smartphone, tablet, or emulator supported by BlackBerry Dynamics
  • A BlackBerry UEM server or use the Enterprise Simulation Mode 

 

Note: It is possible to perform automated testing of the BlackBerry Dynamics SDK utilising the APIs provided in the optional library BlackBerry Dynamics Automated Test Support Library (ATSL), see below for more details on how to integrate and use it.

To run and test any BlackBerry Dynamics app, a BlackBerry UEM server is needed but, with considerable limitations, Enterprise Simulation Mode can be used to test an app without a connection to a BlackBerry UEM server

In Enterprise Simulation Mode, there is no user authentication at the enterprise level, so there will be no communication through the enterprise firewall. If the app requires a connection behind the firewall then a BlackBerry UEM server is needed.

Important: the Enterprise Simulation Mode is not intended for a production environment and it is limited to run on an iOS simulator only.

 

Although Enterprise Simulation Mode is not suitable for the production deployment of an app, it is useful during development, and for verifying proper execution and behavior when migrating existing apps to BlackBerry Dynamics.

In simulation mode, a valid activation key is not required to open the app because there is no direct communication with BlackBerry Dynamics servers. Communication with the BlackBerry Dynamics NOC, however, continues to take place.

 

To enable Enterprise Simulation Mode for a BlackBerry Dynamics app, add the following to the Info.plist file:

<key>GDLibraryMode</key>
<string>GDEnterpriseSimulation</string>

To disable it, change the value to GDEnterprise or remove the key altogether.

 

When a BlackBerry Dynamics app is running for the first time on a target, it needs to be activated with the BlackBerry Dynamics server. In Enterprise Simulation Mode, any email address and any 15-character access key are valid to complete the activation process. After the app is activated, the app will prompt the user to create a password.

The Password Requirements link at the bottom of the screen provides guidance on the required password complexity. When not running in Enterprise Simulation Mode the password complexity is controlled via policies managed by your IT admin through the UEM management console.

 

Enterprise Simulation Mode presents the following differences from standard enterprise execution:

  • [Simulated] will appear in the BlackBerry Dynamics Runtime user interface
  • Any email address and activation key will be accepted for enterprise activation
  • No information is actually sent to enterprise servers, including the email address and activation key
  • The provisioning and policy setup flow is simulated in the UI
  • A hard-coded set of security and compliance policies are in effect; authentication is not delegated
  • When run on a real device, not an emulator, the app will be wiped
  • Attempts to change the mode from GDEnterprise to GDEnterpriseSimulation for an app that is already installed on a device will result in the app being wiped
  • No lost-password recovery is available
  • Inter-container Communication (ICC) cannot be used, which means that the BlackBerry Dynamics Services API cannot be used

Otherwise, the secure storage, secure communication, and push channel APIs are all available in Enterprise Simulation Mode.

The communication APIs will not be able to connect to any enterprise app servers through the UEM server, although direct connections to enterprise app servers can still be made, if, for example, the iOS Simulator is running on a machine that is on the enterprise network or VPN.

BlackBerry UEM or BlackBerry UEM Cloud instance is required to perform testing on an actual smartphone or tablet.

Follow the required steps to configure a BlackBerry Secured app for testing in UEM. If you do not yet have a UEM instance in place, you can configure one with a free developer trial license. Click here to generate a trial license and start configuring your server.

Once the servers are in place, continue with the following steps.

The first thing to do is to define the app in the BlackBerry UEM 

  1. Log in to the BlackBerry UEM management console.
  2. Click Apps > New App > Internal BlackBerry Dynamics app entitlements > Next.
  3. Specify the BlackBerry Dynamics Entitlement ID and BlackBerry Dynamics Entitlement Version that was set in the Info.plist file. For example, com.mycompany.testApp and 1.0.0.0.
  4. Click Add.

Your application will be included in the list of available apps. If you need to provide additional configuration parameters for your app, such as whitelisting servers or configuring an app policy, select your app from the list and configure it as necessary.

Recommendation: Add the Bundle ID to the app’s configuration. This allows the use of Easy Activation, which avoids the requirement of entering an access key when first starting the app. This is also required if your app uses any BlackBerry AppKinetics services.

To add these values:

  1. Click the app.
  2. On the iOS tab, enter the appropriate value
  3. Click Save.

BlackBerry UEM has the capability to prevent debug versions of BlackBerry Dynamics apps from being run. To allow for app development, this must be disabled in the Compliance profile assigned to the user used for testing.

To disable the policy, follow the steps below:

  1. Log in to the UEM management console.
  2. On the left menu, click Policies and profiles > Compliance.
  3. Open the compliance profile assigned to the test user.
  4. On the iOS tab, if Jailbroken OS is checked, ensure that Enable anti-debugging for BlackBerry Dynamics apps is not selected.

After an app is registered in a BlackBerry UEM server, users must be entitled to install and use the app. Individual users or user groups can be entitled to an app. For production deployment, it’s recommended to use user groups. When developing or testing, individual users can be used.

To entitle an app to an individual user, follow the steps below:

  1. Log in to the UEM management console.
  2. Search for and select a user account.
  3. In the Apps section in the user profile, click +.
  4. Search for and select your app.
  5. Click Next.
  6. Leave the Disposition as optional (installation will not be forced) and click Assign.
  7. Depending on your authentication delegate configuration, you may need to generate an Activation Password that will be used when the app is run for the first time after installation.

To generate a new Activation Password:

  1. In the user's profile, under the Summary tab, click Set activation password.
  2. In the Activation option drop-down list, click Default device activation.
  3. In the Activation password drop-down list, click Set device activation password.
  4. In the Device activation password text field enter the password to be used when the app is run for the first time after installation.
  5. For development purposes, it can be useful to extend the Activation period expiration to the maximum allowed (30 days)
  6. Click Submit.
  7. The user receives an email with the credentials and a QR code that can be used to activate the app when it's first run after installation.
    The email sent to the user can be seen also from the UEM console by clicking on the link "View activation email"
  8. Install the app to the intended target using the preferred deployment method (including via Xcode).
  9. When prompted select an activation type between the ones available 
    • Use "enter credentials" to use email and activation password directly.
    • Use "Scan QR code" if the app is running on a device with a camera and the QR code from the activation email is available to scan even from a screen.

The BlackBerry Dynamics SDK includes the BlackBerry Dynamics Automated Test Support Library (ATSL) to support automated testing for your BlackBerry Dynamics apps.

The library includes helper functions for testing common user interactions in BlackBerry Dynamics apps, such as activation and authorization. The configuration and structure of the library are compatible with the tools offered by Apple for user interface testing.

It makes use of the following components:

  • XCTest framework
  • Accessibility identifiers

For more information about these components and iOS user interface testing, see Apple Documentation Archive: User Interface Testing.

You can use the BlackBerry Dynamics library and the native library components mentioned above to automate the building, execution, and reporting of your application tests.

Since the BlackBerry Dynamics ATSL is delivered as a framework, you cannot make your own changes to it. If you want to review the implementation and customize it, you can see the source on GitHub at https://github.com/blackberry/BlackBerry-Dynamics-iOS-Samples/tree/master/AutomatedTestSupportLibrary.

The BlackBerryDynamicsAutomatedTestSupportLibrary framework can be integrated into the test target of a project as any other framework in the BlackBerry Dynamics SDK.

Refer to the instructions in the section "Install & Configure" for detailed steps.

In the same directory as the test code, create a file credentials.json with content similar to below:

{
    "GD_TEST_PROVISION_EMAIL":"testUser@mydomain.com",
    "GD_TEST_PROVISION_ACCESS_KEY":"activationPassword",
    "GD_TEST_PROVISION_PASSWORD":"passwordForApplication"
}

Note: The fields GD_TEST_PROVISION_EMAIL and GD_TEST_PROVISION_PASSWORD could be hard-coded but if the test operates on a non-activated app then the GD_TEST_PROVISION_ACCESS_KEY must be regenerated before the tests start via the BlackBerry UEM REST APIs or it has to be set manually in the BlackBerry UEM server with an extended validity (set the Activation period expiration to 30 days for example).

If the test doesn't reinstall the app and the app is provisioned, the value of GD_TEST_PROVISION_ACCESS_KEY won't be used as the BlackBerry Dynamics SDK can be authorized simply using the password set during the initial provisioning of the app, taken from the field GD_TEST_PROVISION_PASSWORD.

 

To use BBDAutomatedTestSupport class in any test, follow these steps:

  1. Instantiate the main class BBDAutomatedTestSupport
    let ats = BBDAutomatedTestSupport.sharedInstance()
  2. Load the credentials with
    ats.fetchCredentials()
  3. Define the XCUIApplication object to use and set up the BBDAutomatedTestSupport to use it.
    let application = XCUIApplication()
    ats.setupBBDAutomatedTestSupport(with: application, for: self)
  4. Launch the authorization flow with
    XCTAssertTrue(ats.loginOrProvisionBBDApp(), "Could not authorize the app")
  5. Verify that the authorization process was successful and the app main UI is shown with something like
    XCTAssertTrue(ats.isScreenShown("AppRootControllerIdentifier", timeout: 120), "BlackBerry Dynamics SDK authorization was successful but the main app UI was not shown")

Notes:

  • The json file with credentials can have a different name and/or path, it can be loaded using variants of fetchCredentials() function.
  • Biometric authentication is only partially supported by the BlackBerryDynamicsAutomatedTestSupportLibrary because, by its own nature, it's limited to being tested automatically only on a simulator.

Deploy and Test a BlackBerry Dynamics Secured App

Deploy your BlackBerry Dynamics app to a smartphone, tablet, or emulator for testing purposes.

You require:

  • An Internet connection
  • A smartphone, tablet, or emulator supported by BlackBerry Dynamics
  • A BlackBerry UEM server or use the Enterprise Simulation Mode 

 

Note: It is possible to perform automated testing of the BlackBerry Dynamics SDK utilising the APIs provided in the optional library BlackBerry Dynamics Automated Test Support Library (ATSL), see below for more details on how to integrate and use it.

To run and test any BlackBerry Dynamics app, a BlackBerry UEM server is needed but, with considerable limitations, Enterprise Simulation Mode can be used to test an app without a connection to a BlackBerry UEM server

In Enterprise Simulation Mode, there is no user authentication at the enterprise level, so there will be no communication through the enterprise firewall. If the app requires a connection behind the firewall then a BlackBerry UEM server is needed.

Important: the Enterprise Simulation Mode is not intended for a production environment and it is limited to run on an iOS simulator only.

 

Although Enterprise Simulation Mode is not suitable for the production deployment of an app, it is useful during development, and for verifying proper execution and behavior when migrating existing apps to BlackBerry Dynamics.

In simulation mode, a valid activation key is not required to open the app because there is no direct communication with BlackBerry Dynamics servers. Communication with the BlackBerry Dynamics NOC, however, continues to take place.

 

To enable Enterprise Simulation Mode for a BlackBerry Dynamics app, add the following to the assets/settings.json file:

"GDLibraryMode": "GDEnterpriseSimulation"

To disable it, change the value to GDEnterprise or remove the key altogether.

 

When a BlackBerry Dynamics app is running for the first time on a target, it needs to be activated with the BlackBerry Dynamics server. In Enterprise Simulation Mode, any email address and any 15-character access key are valid to complete the activation process. After the app is activated, the app will prompt the user to create a password.

The Password Requirements link at the bottom of the screen provides guidance on the required password complexity. When not running in Enterprise Simulation Mode the password complexity is controlled via policies managed by your IT admin through the UEM management console.

 

Enterprise Simulation Mode presents the following differences from standard enterprise execution:

  • [Simulated] will appear in the BlackBerry Dynamics Runtime user interface
  • Any email address and activation key will be accepted for enterprise activation
  • No information is actually sent to enterprise servers, including the email address and activation key
  • The provisioning and policy setup flow is simulated in the UI
  • A hard-coded set of security and compliance policies are in effect; authentication is not delegated
  • When run on a real device, not an emulator, the app will be wiped
  • Attempts to change the mode from GDEnterprise to GDEnterpriseSimulation for an app that is already installed on a device will result in the app being wiped
  • No lost-password recovery is available
  • Inter-container Communication (ICC) cannot be used, which means that the BlackBerry Dynamics Services API cannot be used

Otherwise, the secure storage, secure communication, and push channel APIs are all available in Enterprise Simulation Mode.

The communication APIs will not be able to connect to any enterprise app servers through the UEM server, although direct connections to enterprise app servers can still be made, if, for example, the iOS Simulator is running on a machine that is on the enterprise network or VPN.

BlackBerry UEM or BlackBerry UEM Cloud instance is required to perform testing on an actual smartphone or tablet.

Follow the required steps to configure a BlackBerry Secured app for testing in UEM. If you do not yet have a UEM instance in place, you can configure one with a free developer trial license. Click here to generate a trial license and start configuring your server.

Once the servers are in place, continue with the following steps.

The first thing to do is to define the app in the BlackBerry UEM 

  1. Log in to the BlackBerry UEM management console.
  2. Click Apps > New App > Internal BlackBerry Dynamics app entitlements > Next.
  3. Specify the BlackBerry Dynamics Entitlement ID and BlackBerry Dynamics Entitlement Version that was set in the assets/settings.json file. For example, com.mycompany.testApp and 1.0.0.0.
  4. Click Add.

Your application will be included in the list of available apps. If you need to provide additional configuration parameters for your app, such as whitelisting servers or configuring an app policy, select your app from the list and configure it as necessary.

Recommendation: Add the package name to the app’s configuration. This allows the use of Easy Activation, which avoids the requirement of entering an access key when first starting the app. This is also required if your app uses any BlackBerry AppKinetics services.

To add these values:

  1. Click the app.
  2. On the Android tab, enter the appropriate value.
  3. Click Save.

BlackBerry UEM has the capability to prevent debug versions of BlackBerry Dynamics apps from being run. To allow for app development, this must be disabled in the Compliance profile assigned to the user used for testing.

To disable the policy, follow the steps below:

  1. Log in to the UEM management console.
  2. On the left menu, click Policies and profiles > Compliance.
  3. Open the compliance profile assigned to the test user.
  4. On the Android tab, if Rooted OS is checked, ensure that Enable anti-debugging for BlackBerry Dynamics apps is not selected.

After an app is registered in a BlackBerry UEM server, users must be entitled to install and use the app. Individual users or user groups can be entitled to an app. For production deployment, it’s recommended to use user groups. When developing or testing, individual users can be used.

To entitle an app to an individual user, follow the steps below:

  1. Log in to the UEM management console.
  2. Search for and select a user account.
  3. In the Apps section in the user profile, click +.
  4. Search for and select your app.
  5. Click Next.
  6. Leave the Disposition as optional (installation will not be forced) and click Assign.
  7. Depending on your authentication delegate configuration, you may need to generate an Activation Password that will be used when the app is run for the first time after installation.

To generate a new Activation Password:

  1. In the user's profile, under the Summary tab, click Set activation password.
  2. In the Activation option drop-down list, click Default device activation.
  3. In the Activation password drop-down list, click Set device activation password.
  4. In the Device activation password text field enter the password to be used when the app is run for the first time after installation.
  5. For development purposes, it can be useful to extend the Activation period expiration to the maximum allowed (30 days)
  6. Click Submit.
  7. The user receives an email with the credentials and a QR code that can be used to activate the app when it's first run after installation.
    The email sent to the user can be seen also from the UEM console by clicking on the link "View activation email"
  8. Install the app to the intended target using the preferred deployment method (including via Xcode).
  9. When prompted select an activation type between the ones available 
    • Use "enter credentials" to use email and activation password directly.
    • Use "Scan QR code" if the app is running on a device with a camera and the QR code from the activation email is available to scan even from a screen.

The BlackBerry Dynamics SDK includes the BlackBerry Dynamics Automated Test Support Library (ATSL) to support automated testing for your BlackBerry Dynamics apps.

The library includes helper functions for testing common user interactions in BlackBerry Dynamics apps, such as activation and authorization. The configuration and structure of the library are compatible with the native Android Testing Support Library.

It makes use of the following components:

  • com.android.support.test:rules
  • com.android.support.test.uiautomator:uiautomator-v18

For more information about these components and the Android Testing Support Library, see Android Studio: Test your app.

You can use the BlackBerry Dynamics library, the native library components mentioned above, and Gradle and JUnit tools to automate the building, execution, and reporting of your application tests.

Since the BlackBerry Dynamics ATSL is delivered as binary libraries, you cannot make your own changes to it. If you want to review the implementation and customize it, you can see the source on GitHub at https://github.com/blackberry/BlackBerry-Dynamics-Android-Samples/tree/master/AutomatedTestSupportLibrary.

The BlackBerryDynamicsAutomatedTestSupportLibrary can be integrated into the test target of a project as any other library in the BlackBerry Dynamics SDK.

Simply add this line to the build.gradle:

testImplementation "com.blackberry.blackberrydynamics:atsl:${dynamicsVersion}"

In the assets directory of the test target, create a file com.good.gd.test.json with content similar to below

{
    "GD_TEST_PROVISION_EMAIL":"testUser@mydomain.com",
    "GD_TEST_PROVISION_ACCESS_KEY":"activationPassword",
    "GD_TEST_PROVISION_PASSWORD":"passwordForApplication"
}

Note: The fields GD_TEST_PROVISION_EMAIL and GD_TEST_PROVISION_PASSWORD could be hard-coded but if the test operates on a non-activated app then the GD_TEST_PROVISION_ACCESS_KEY must be regenerated before the tests start via the BlackBerry UEM REST APIs or it has to be set manually in the BlackBerry UEM server with an extended validity (set the Activation period expiration to 30 days for example)

If the test doesn't reinstall the app the value of GD_TEST_PROVISION_ACCESS_KEY won't be used as the BlackBerry Dynamics SDK can be authorized simply using the password set during the initial provisioning of the app, taken from the field GD_TEST_PROVISION_PASSWORD.

 

To use BBDAutomatedTestSupport class in any test, follow these steps:

  1. Instantiate the main class AbstractUIAutomatorUtils. This will also load the credentials defined in com.good.gd.test.json
    AbstractUIAutomatorUtils uiAutomatorUtils = UIAutomatorUtilsFactory.getUIAutomatorUtils();
  2. Launch the authorization flow with
    assertTrue("Failed to login or provision app", BBDActivationHelper.loginOrActivateApp());
  3. Verify that the authorization process was successful and the app main UI is shown with something like
    assertTrue("Dynamics Authorization failed", uiAutomatorUtils.checkGDAuthorized());
    assertTrue("Main UI for app not shown", uiAutomatorUtils.isScreenShown(
                "com.myorg.myapp",
                "MainActivityIdentifier",
                Duration.of(PROVISIONING)));

Notes:

  • The json file with credentials must be inside the assets folder of the test target and can only be called either com.good.gd.test.json or com.myorg.myapp.json
  • Biometric authentication is only partially supported by the BlackBerryDynamicsAutomatedTestSupportLibrary because, by its own nature, it's limited to being tested automatically only on a simulator.

Deploy and Test a BlackBerry Dynamics Secured App

Deploy your BlackBerry Dynamics app to a smartphone, tablet, or emulator for testing purposes.

You require:

  • An Internet connection
  • A smartphone, tablet, or emulator supported by BlackBerry Dynamics
  • A BlackBerry UEM server or use the Enterprise Simulation Mode

To run and test any BlackBerry Dynamics app, a BlackBerry UEM server is needed but, with considerable limitations, Enterprise Simulation Mode can be used to test an app without a connection to a BlackBerry UEM server

In Enterprise Simulation Mode, there is no user authentication at the enterprise level, so there will be no communication through the enterprise firewall. If the app requires a connection behind the firewall then a BlackBerry UEM server is needed.

Important: the Enterprise Simulation Mode is not intended for a production environment and it is limited to run on an iOS simulator only.

 

Although Enterprise Simulation Mode is not suitable for the production deployment of an app, it is useful during development, and for verifying proper execution and behavior when migrating existing apps to BlackBerry Dynamics.

In simulation mode, a valid activation key is not required to open the app because there is no direct communication with BlackBerry Dynamics servers. Communication with the BlackBerry Dynamics NOC, however, continues to take place.

 

To enable Enterprise Simulation Mode for a BlackBerry Dynamics app, add the following to the root config.xml file and rebuild the project:
 

<preference name=“GDEnterpriseSimulationMode” value=“true” />

To disable it, change the value to false or remove the preference altogether.

 

When a BlackBerry Dynamics app is running for the first time on a target, it needs to be activated with the BlackBerry Dynamics server. In Enterprise Simulation Mode, any email address and any 15-character access key are valid to complete the activation process. After the app is activated, the app will prompt the user to create a password.

The Password Requirements link at the bottom of the screen provides guidance on the required password complexity. When not running in Enterprise Simulation Mode the password complexity is controlled via policies managed by your IT admin through the UEM management console.

 

Enterprise Simulation Mode presents the following differences from standard enterprise execution:

  • [Simulated] will appear in the BlackBerry Dynamics Runtime user interface
  • Any email address and activation key will be accepted for enterprise activation
  • No information is actually sent to enterprise servers, including the email address and activation key
  • The provisioning and policy setup flow is simulated in the UI
  • A hard-coded set of security and compliance policies are in effect; authentication is not delegated
  • When run on a real device, not an emulator, the app will be wiped
  • Attempts to change the mode from GDEnterprise to GDEnterpriseSimulation for an app that is already installed on a device will result in the app being wiped
  • No lost-password recovery is available
  • Inter-container Communication (ICC) cannot be used, which means that the BlackBerry Dynamics Services API cannot be used

Otherwise, the secure storage, secure communication, and push channel APIs are all available in Enterprise Simulation Mode.

The communication APIs will not be able to connect to any enterprise app servers through the UEM server, although direct connections to enterprise app servers can still be made, if, for example, the iOS Simulator is running on a machine that is on the enterprise network or VPN.

A BlackBerry UEM or BlackBerry UEM Cloud instance is required to perform testing on an actual smartphone or tablet.

Follow the required steps to configure a BlackBerry Secured app for testing in UEM. If you do not yet have a UEM instance in place, you can configure one with a free developer trial license. Click here to generate a trial license and start configuring your server.

Once the servers are in place, continue with the following steps.

The first thing to do is to define the app in the BlackBerry UEM 

  1. Log in to the BlackBerry UEM management console.
  2. Click Apps > New App > Internal BlackBerry Dynamics app entitlements > Next.
  3. Specify the BlackBerry Dynamics Entitlement ID and BlackBerry Dynamics Entitlement Version that was set in the Info.plist file. For example, com.mycompany.testApp and 1.0.0.0.
  4. Click Add.

Your application will be included in the list of available apps. If you need to provide additional configuration parameters for your app, such as whitelisting servers or configuring an app policy, select your app from the list and configure it as necessary.

Recommendation: Add the Bundle ID to the app’s configuration. This allows the use of Easy Activation, which avoids the requirement of entering an access key when first starting the app. This is also required if your app uses any BlackBerry AppKinetics services.

To add these values:

  1. Click the app.
  2. On the iOS tab, enter the appropriate value
  3. Click Save.

BlackBerry UEM has the capability to prevent debug versions of BlackBerry Dynamics apps from being run. To allow for app development, this must be disabled in the Compliance profile assigned to the user used for testing.

To disable the policy, follow the steps below:

  1. Log in to the UEM management console.
  2. On the left menu, click Policies and profiles > Compliance.
  3. Open the compliance profile assigned to the test user.
  4. On the iOS tab, if Jailbroken OS is checked, ensure that Enable anti-debugging for BlackBerry Dynamics apps is not selected.

After an app is registered in a BlackBerry UEM server, users must be entitled to install and use the app. Individual users or user groups can be entitled to an app. For production deployment, it’s recommended to use user groups. When developing or testing, individual users can be used.

To entitle an app to an individual user, follow the steps below:

  1. Log in to the UEM management console.
  2. Search for and select a user account.
  3. In the Apps section in the user profile, click +.
  4. Search for and select your app.
  5. Click Next.
  6. Leave the Disposition as optional (installation will not be forced) and click Assign.
  7. Depending on your authentication delegate configuration, you may need to generate an Activation Password that will be used when the app is run for the first time after installation.

To generate a new Activation Password:

  1. In the user's profile, under the Summary tab, click Set activation password.
  2. In the Activation option drop-down list, click Default device activation.
  3. In the Activation password drop-down list, click Set device activation password.
  4. In the Device activation password text field enter the password to be used when the app is run for the first time after installation.
  5. For development purposes, it can be useful to extend the Activation period expiration to the maximum allowed (30 days)
  6. Click Submit.
  7. The user receives an email with the credentials and a QR code that can be used to activate the app when it's first run after installation.
    The email sent to the user can be seen also from the UEM console by clicking on the link "View activation email"
  8. Install the app to the intended target using the preferred deployment method (including via Xcode).
  9. When prompted select an activation type between the ones available 
    • Use "enter credentials" to use email and activation password directly.
    • Use "Scan QR code" if the app is running on a device with a camera and the QR code from the activation email is available to scan even from a screen.

Deploy and Test a BlackBerry Dynamics Secured App

Deploy your BlackBerry Dynamics app to a smartphone, tablet, or emulator for testing purposes.

You require:

  • An Internet connection
  • A smartphone, tablet, or emulator supported by BlackBerry Dynamics
  • A BlackBerry UEM server or use the Enterprise Simulation Mode 

To run and test any BlackBerry Dynamics app, a BlackBerry UEM server is needed but, with considerable limitations, Enterprise Simulation Mode can be used to test an app without a connection to a BlackBerry UEM server

In Enterprise Simulation Mode, there is no user authentication at the enterprise level, so there will be no communication through the enterprise firewall. If the app requires a connection behind the firewall then a BlackBerry UEM server is needed.

Important: the Enterprise Simulation Mode is not intended for a production environment and it is limited to run on an Android emulator only.

 

Although Enterprise Simulation Mode is not suitable for the production deployment of an app, it is useful during development, and for verifying proper execution and behavior when migrating existing apps to BlackBerry Dynamics.

In simulation mode, a valid activation key is not required to open the app because there is no direct communication with BlackBerry Dynamics servers. Communication with the BlackBerry Dynamics NOC, however, continues to take place.

 

To enable Enterprise Simulation Mode for a BlackBerry Dynamics app, add the following to the root config.xml file and rebuild the project:

<preference name=“GDEnterpriseSimulationMode” value=“true” />

To disable it, change the value to false or remove the preference altogether.

 

When a BlackBerry Dynamics app is running for the first time on a target, it needs to be activated with the BlackBerry Dynamics server. In Enterprise Simulation Mode, any email address and any 15-character access key are valid to complete the activation process. After the app is activated, the app will prompt the user to create a password.

The Password Requirements link at the bottom of the screen provides guidance on the required password complexity. When not running in Enterprise Simulation Mode the password complexity is controlled via policies managed by your IT admin through the UEM management console.

 

Enterprise Simulation Mode presents the following differences from standard enterprise execution:

  • [Simulated] will appear in the BlackBerry Dynamics Runtime user interface
  • Any email address and activation key will be accepted for enterprise activation
  • No information is actually sent to enterprise servers, including the email address and activation key
  • The provisioning and policy setup flow is simulated in the UI
  • A hard-coded set of security and compliance policies are in effect; authentication is not delegated
  • When run on a real device, not an emulator, the app will be wiped
  • Attempts to change the mode from GDEnterprise to GDEnterpriseSimulation for an app that is already installed on a device will result in the app being wiped
  • No lost-password recovery is available
  • Inter-container Communication (ICC) cannot be used, which means that the BlackBerry Dynamics Services API cannot be used

Otherwise, the secure storage, secure communication, and push channel APIs are all available in Enterprise Simulation Mode.

The communication APIs will not be able to connect to any enterprise app servers through the UEM server, although direct connections to enterprise app servers can still be made, if, for example, the iOS Simulator is running on a machine that is on the enterprise network or VPN.

A BlackBerry UEM or BlackBerry UEM Cloud instance is required to perform testing on an actual smartphone or tablet.

Follow the required steps to configure a BlackBerry Secured app for testing in UEM. If you do not yet have a UEM instance in place, you can configure one with a free developer trial license. Click here to generate a trial license and start configuring your server.

Once the servers are in place, continue with the following steps.

The first thing to do is to define the app in the BlackBerry UEM 

  1. Log in to the BlackBerry UEM management console.
  2. Click Apps > New App > Internal BlackBerry Dynamics app entitlements > Next.
  3. Specify the BlackBerry Dynamics Entitlement ID and BlackBerry Dynamics Entitlement Version that was set in the assets/settings.json file. For example, com.mycompany.testApp and 1.0.0.0.
  4. Click Add.

Your application will be included in the list of available apps. If you need to provide additional configuration parameters for your app, such as whitelisting servers or configuring an app policy, select your app from the list and configure it as necessary.

Recommendation: Add the package name to the app’s configuration. This allows the use of Easy Activation, which avoids the requirement of entering an access key when first starting the app. This is also required if your app uses any BlackBerry AppKinetics services.

To add these values:

  1. Click the app.
  2. On the Android tab, enter the appropriate value.
  3. Click Save.

BlackBerry UEM has the capability to prevent debug versions of BlackBerry Dynamics apps from being run. To allow for app development, this must be disabled in the Compliance profile assigned to the user used for testing.

To disable the policy, follow the steps below:

  1. Log in to the UEM management console.
  2. On the left menu, click Policies and profiles > Compliance.
  3. Open the compliance profile assigned to the test user.
  4. On the Android tab, if Rooted OS is checked, ensure that Enable anti-debugging for BlackBerry Dynamics apps is not selected.

After an app is registered in a BlackBerry UEM server, users must be entitled to install and use the app. Individual users or user groups can be entitled to an app. For production deployment, it’s recommended to use user groups. When developing or testing, individual users can be used.

To entitle an app to an individual user, follow the steps below:

  1. Log in to the UEM management console.
  2. Search for and select a user account.
  3. In the Apps section in the user profile, click +.
  4. Search for and select your app.
  5. Click Next.
  6. Leave the Disposition as optional (installation will not be forced) and click Assign.
  7. Depending on your authentication delegate configuration, you may need to generate an Activation Password that will be used when the app is run for the first time after installation.

To generate a new Activation Password:

  1. In the user's profile, under the Summary tab, click Set activation password.
  2. In the Activation option drop-down list, click Default device activation.
  3. In the Activation password drop-down list, click Set device activation password.
  4. In the Device activation password text field enter the password to be used when the app is run for the first time after installation.
  5. For development purposes, it can be useful to extend the Activation period expiration to the maximum allowed (30 days)
  6. Click Submit.
  7. The user receives an email with the credentials and a QR code that can be used to activate the app when it's first run after installation.
    The email sent to the user can be seen also from the UEM console by clicking on the link "View activation email"
  8. Install the app to the intended target using the preferred deployment method (including via Xcode).
  9. When prompted select an activation type between the ones available 
    • Use "enter credentials" to use email and activation password directly.
    • Use "Scan QR code" if the app is running on a device with a camera and the QR code from the activation email is available to scan even from a screen.

Congratulations on developing your first BlackBerry Dynamics secured Cordova app! You can continue to explore the available plugins that expose different APIs and read developer resources. Learn about some of the common plugins below.

You may want to learn more about the BlackBerry DynamicsCordova  Plugins and how they work with your project. If you’ve built projects with Cordova plugins in the past, using the BlackBerry Dynamics plugins will be familiar to you.

Some features will automatically be available to your project after adding the cordova-plugin-bbd-base plugin such as XMLHttpRequest, fetch etc.

To see the full details of BlackBerry Dynamics Cordova APIs, see the  BlackBerry Dynamics SDK for Cordova API Reference.

On the BlackBerry GitHub page, there are sample applications which show best practices when using the BlackBerry Dynamics Cordova Plugins. To use them simply download the dependencies, add the required platforms and then run them using the methods covered on the Deploy & Test tab.



Generally, it’s recommended to use the cordova-plugin-bbd-all plugin to enable access to all BlackBerry Dynamics APIs. If more granular control is required, you can also install only the bare minimum of required plugins for your app.

cordova-plugin-bbd-file plugin enables you to manage the FileSystem residing within the BlackBerry Dynamics secure container using a similar JavaScript API to the original File plugin.

cordova-plugin-bbd-file-transfer plugin enables you to securely upload and download files within the BlackBerry Dynamics secure container using a similar JavaScript API to the original FileTransfer plugin.

cordova-plugin-bbd-media-capture plugin enables you to capture audio, video and images using the device's microphone or camera and store them within the BlackBerry Dynamics secure container using a similar JavaScript API to the original MediaCapture plugin.

cordova-plugin-bbd-storage plugin is an interface representing a secure localStorage.

When making HTTPS requests through an HTTP proxy, SSL/TLS certificate verification must be disabled. Certificate verification while using an HTTP proxy is not supported. BlackBerry Dynamics HTTP data communication does not go via the proxy specified in the device's native settings, if any.

The BlackBerry Dynamics Runtime supports Basic Access, Digest Access, NTLM, and Kerberos for authentication with HTTP servers. Except for Kerberos, all these mechanisms are also supported for authentication with HTTP proxies. The BD Runtime supports Kerberos version 5 authentication.

By default, HTTP cookies received through Good Dynamics secure communication are handled automatically.
 

Default networking

This plugin overrides the default APIs XMLHttpRequest and fetch() to retrieve the necessary objects automatically upon installation of the cordova-plugin-bbd-base plugin. Calls made via XHR or fetch will automatically route through the BlackBerry Dynamics Proxy.
 

HttpRequest

cordova-plugin-bbd-httprequest plugin is used to send HTTP requests over the internet. It also encapsulates the HTTP response returned from an HttpRequest's send function.
 

WebSocket

cordova-plugin-bbd-websocket plugin implements the secure WebSocket APIs based on standard WebSocket specification (see https://developer.mozilla.org/en-US/docs/Web/API/WebSocket).
 

InAppBrowser

cordova-plugin-bbd-inappbrowser plugin enables you to securely load helpful articles, videos, and web resources inside of your app without leaving your app. It is a fork of cordova-plugin-inappbrowser.
 

TokenHelper

cordova-plugin-bbd-tokenhelper plugin is used to request token from server side and process callback on the response.
 

Socket

cordova-plugin-bbd-socket plugin provides access to the secure Socket communications API.

cordova-plugin-bbd-sqlite-storage plugin enables you to securely create and manage an SQLite database within the BlackBerry Dynamics secure container using a similar JavaScript SQLite API to the original plugin. It is a fork of cordova-plugin-sqlite-storage@4.0.0.

cordova-plugin-bbd-appkinetics plugin provides the functionality of AppKinetics - the ability to securely communicate between Dynamics applications.

cordova-plugin-bbd-interappcommunication plugin is used to return information about a service provider application(s) of app-based services.

cordova-plugin-bbd-mailto plugin provides functionality to securely compose emails with attachments.

cordova-plugin-bbd-launcher plugin is used to show the BlackBerry Dynamics Launcher in your application.

cordova-plugin-bbd-application plugin provides access to information that is globally available to any BlackBerry Dynamics Application.

cordova-plugin-bbd-push plugin encapsulates the response returned from the GDPush class.

cordova-plugin-bbd-specificpolicies plugin is used to read application-specific policy from UEM console and return it in JSON format.

cordova-plugin-bbd-serversideservices plugin provides the ability to use BBD Server Based Services. It returns all the needed information about the service in JSON format.

The BlackBerry Dynamics runtime may secure or block text in transit to or from the clipboard, depending on the policies for data leakage prevention (DLP) policy configured in BlackBerry UEM.

The runtime secures text by encrypting it when it is cut or copied to the device clipboard, and then decrypting it when it is pasted from the clipboard.

These operations are handled automatically by the BlackBerry Dynamics Runtime. No coding changes are required to support this feature.

Congratulations on developing your first BlackBerry Dynamics secured Cordova app! You can continue to explore the available plugins that expose different APIs and read developer resources. Learn about some of the common plugins below.

You may want to learn more about the BlackBerry DynamicsCordova  Plugins and how they work with your project. If you’ve built projects with Cordova plugins in the past, using the BlackBerry Dynamics plugins will be familiar to you.

Some features will automatically be available to your project after adding the cordova-plugin-bbd-base plugin such as XMLHttpRequest, fetch etc.

To see the full details of BlackBerry Dynamics Cordova APIs, see the  BlackBerry Dynamics SDK for Cordova API Reference.

On the BlackBerry GitHub page, there are sample applications which show best practices when using the BlackBerry Dynamics Cordova Plugins. To use them simply download the dependencies, add the required platforms and then run them using the methods covered on the Deploy & Test tab.



Generally, it’s recommended to use the cordova-plugin-bbd-all plugin to enable access to all BlackBerry Dynamics APIs. If more granular control is required, you can also install only the bare minimum of required plugins for your app.

cordova-plugin-bbd-file plugin enables you to manage the FileSystem residing within the BlackBerry Dynamics secure container using a similar JavaScript API to the original File plugin.

cordova-plugin-bbd-file-transfer plugin enables you to securely upload and download files within the BlackBerry Dynamics secure container using a similar JavaScript API to the original FileTransfer plugin.

cordova-plugin-bbd-media-capture plugin enables you to capture audio, video and images using the device's microphone or camera and store them within the BlackBerry Dynamics secure container using a similar JavaScript API to the original MediaCapture plugin.

cordova-plugin-bbd-storage plugin is an interface representing a secure localStorage.

When making HTTPS requests through an HTTP proxy, SSL/TLS certificate verification must be disabled. Certificate verification while using an HTTP proxy is not supported. BlackBerry Dynamics HTTP data communication does not go via the proxy specified in the device's native settings, if any.

The BlackBerry Dynamics Runtime supports Basic Access, Digest Access, NTLM, and Kerberos for authentication with HTTP servers. Except for Kerberos, all these mechanisms are also supported for authentication with HTTP proxies. The BD Runtime supports Kerberos version 5 authentication.

By default, HTTP cookies received through Good Dynamics secure communication are handled automatically.

Default networking

This plugin overrides the default APIs XMLHttpRequest and fetch() to retrieve the necessary objects automatically upon installation of the cordova-plugin-bbd-base plugin. Calls made via XHR or fetch will automatically route through the BlackBerry Dynamics Proxy.

HttpRequest

cordova-plugin-bbd-httprequest plugin is used to send HTTP requests over the internet. It also encapsulates the HTTP response returned from an HttpRequest's send function.

WebSocket

cordova-plugin-bbd-websocket plugin implements the secure WebSocket APIs based on standard WebSocket specification (see https://developer.mozilla.org/en-US/docs/Web/API/WebSocket).

InAppBrowser

cordova-plugin-bbd-inappbrowser plugin enables you to securely load helpful articles, videos, and web resources inside of your app without leaving your app. It is a fork of cordova-plugin-inappbrowser.

TokenHelper

cordova-plugin-bbd-tokenhelper plugin is used to request token from server side and process callback on the response.

Socket

cordova-plugin-bbd-socket plugin provides access to the secure Socket communications API.

cordova-plugin-bbd-sqlite-storage plugin enables you to securely create and manage an SQLite database within the BlackBerry Dynamics secure container using a similar JavaScript SQLite API to the original plugin. It is a fork of cordova-plugin-sqlite-storage@4.0.0.

cordova-plugin-bbd-appkinetics plugin provides the functionality of AppKinetics - the ability to securely communicate between Dynamics applications.

cordova-plugin-bbd-interappcommunication plugin is used to return information about a service provider application(s) of app-based services.

cordova-plugin-bbd-mailto plugin provides functionality to securely compose emails with attachments.

cordova-plugin-bbd-launcher plugin is used to show the BlackBerry Dynamics Launcher in your application.

cordova-plugin-bbd-application plugin provides access to information that is globally available to any BlackBerry Dynamics Application.

cordova-plugin-bbd-push plugin encapsulates the response returned from the GDPush class.

cordova-plugin-bbd-specificpolicies plugin is used to read application-specific policy from UEM console and return it in JSON format.

cordova-plugin-bbd-serversideservices plugin provides the ability to use BBD Server Based Services. It returns all the needed information about the service in JSON format.

The BlackBerry Dynamics runtime may secure or block text in transit to or from the clipboard, depending on the policies for data leakage prevention (DLP) policy configured in BlackBerry UEM.

The runtime secures text by encrypting it when it is cut or copied to the device clipboard, and then decrypting it when it is pasted from the clipboard.

These operations are handled automatically by the BlackBerry Dynamics Runtime. No coding changes are required to support this feature.

Congratulations on developing your first BlackBerry Dynamics secured app! You can continue to explore the available APIs and developer resources. Learn about some of the common APIs below.

The code snippets used in this section are from two Android projects available for download from GitHub. 

Java Samples: Getting Started and Getting Started BD

Kotlin Samples: GettingStartedKotlin and GettingStartedKotlinBD.

Each pair of projects demonstrate the differences between a native Android app and its equivalent app secured with the BlackBerry Dynamics SDK

To see the full details of BlackBerry Dynamics APIs, see the BlackBerry Dynamics SDK API Reference.

The secure file system is part of the BlackBerry Dynamics Secure Storage feature. For apps, the BlackBerry Dynamics secure file system behaves like the default file system, with the following differences:

  • All data within the secure file system is stored on the device in an encrypted form.
  • Directory and file names are also encrypted.
  • There is no current working directory in the secure file system. Paths should always be specified as absolute paths, beginning with a / character.
  • The secure file system cannot be accessed until the BlackBerry Dynamics authorization processing is complete. For more information, see  authorize  in the GDAndroid class reference.

Encryption and decryption are transparent to the app code:

  • File-writing interfaces accept raw data. The BlackBerry Dynamics Runtime encrypts the data and stores it on the device.
  • When a file-reading interface is utilized, the BlackBerry Dynamics Runtime decrypts what was stored and returns plain data.
  • Path access interfaces accept plain parameters for directory and file names. The BlackBerry Dynamics Runtime encrypts the parameter values in order to create paths in the secure store.
  • Directories and file names provided as return values are plain. The BlackBerry Dynamics Runtime decrypts paths in the secure store in order to generate the return values.

The encryption method used by the BlackBerry Dynamics Runtime generally requires that the user has entered a security password, from which an encryption key is derived. For more information, refer to the File I/O package documentation.

From a coding perspective, the BlackBerry Dynamics file system APIs are very similar to the standard Android file system APIs. The changes required are minimal and only involve changing some of the class names used. Comparing the before FileFragment.java  and after FileFragment.java or the before FileFragment.kt  and after FileFragment.kt  files, you’ll observe the following changes:

Update Import Statements

Original

import java.io.FileOutputStream;
import java.io.InputStream;

BlackBerry Dynamics

import com.good.gd.file.FileInputStream;
import com.good.gd.file.FileOutputStream;
import com.good.gd.file.GDFileSystem;

 

Use GDFileSystem to Open the File for Writing

Original

outputStream = getContext().openFileOutput(FILENAME, Context.MODE_PRIVATE);

BlackBerry Dynamics

outputStream = GDFileSystem.openFileOutput(FILENAME, Context.MODE_PRIVATE);

 

Use GDFileSystem to Open the File for Reading

Original

InputStream inputStream = getContext().openFileInput(FILENAME);

BlackBerry Dynamics

FileInputStream inputStream = GDFileSystem.openFileInput(FILENAME);

After making these minor changes, the app is now able to securely read and write encrypted files.

Update Import Statements

Original

import java.io.FileOutputStream
import java.io.InputStream

BlackBerry Dynamics

import com.good.gd.file.FileInputStream
import com.good.gd.file.FileOutputStream
import com.good.gd.file.GDFileSystem

 

Use GDFileSystem to Open the File for Writing

Original

val outputStream: FileOutputStream = context!!.openFileOutput(FILENAME, Context.MODE_PRIVATE)

BlackBerry Dynamics

val outputStream: FileOutputStream = GDFileSystem.openFileOutput(FILENAME, Context.MODE_PRIVATE)

 

Use GDFileSystem to Open the File for Reading

Original

val inputStream: FileInputStream? = context!!.openFileInput(FILENAME)

BlackBerry Dynamics

val inputStream: FileInputStream? = GDFileSystem.openFileInput(FILENAME)

After making these minor changes, the app is now able to securely read and write encrypted files.

The secure SQL database is part of the BlackBerry Dynamics Secure Storage feature. Data stored in the secure SQL database will be encrypted on the device by the BlackBerry Dynamics Runtime. The BlackBerry Dynamics secure SQL database is based on the SQLite library. Encryption is added by BlackBerry Dynamics transparently to the app. A secure SQL database cannot be accessed until BlackBerry Dynamics authorization processing is complete.

BlackBerry Dynamics apps access the secure database using replacements for the native android.database and android.database.sqlite packages. To access the replacement classes instead of the native classes, change android.database to com.good.gd.database wherever it occurs in the app code.

The replacement packages support the same APIs as the native packages, with the following exceptions:

  • The LOCALIZED and UNICODE collators provided by the native android.database.sqlite package are not supported.
  • There is an additional function, importDatabase. See below for more information.
  • Paths of database files are interpreted relative to the root of the BlackBerry Dynamics secure file system of the app. The root of the secure file system is within the app's data directory. There is no need to utilize functions such as the native getFilesDir to generate database file paths.

For more on using SQLite databases refer to the SQLite package documentation.

If you compare the modifications required for SQLite in the Java before and after samples or the Kotlin before and after samples, you’ll notice that the only changes required are for the import statements. The rest of the SQLite in the app can remain as is. Here are the changes that were made:

Modify Import Statements in ColorDbHelp.java

Original

import android.database.sqlite.SQLiteDatabase;
import android.database.sqlite.SQLiteOpenHelper;

BlackBerry Dynamics

import com.good.gd.database.sqlite.SQLiteDatabase;
import com.good.gd.database.sqlite.SQLiteOpenHelper;

 

Modify Import in SqlFragment.java

Original

import android.database.sqlite.SQLiteDatabase;

BlackBerry Dynamics

import com.good.gd.database.sqlite.SQLiteDatabase;

Modify Import Statements in ColorDbHelp.java

Original

import android.database.sqlite.SQLiteDatabase
import android.database.sqlite.SQLiteOpenHelper

BlackBerry Dynamics

import com.good.gd.database.sqlite.SQLiteDatabase
import com.good.gd.database.sqlite.SQLiteOpenHelper

 

Modify Import in SqlFragment.java

Original

import android.database.sqlite.SQLiteDatabase

BlackBerry Dynamics

import com.good.gd.database.sqlite.SQLiteDatabase

This class is an extension of the Apache HttpClient for utilizing BlackBerry Dynamics secure communication. See the BlackBerry Dynamics Communication Package for an introduction to the BlackBerry Dynamics secure communication feature. This class is a subclass of the native com.good.gd.apache.http.impl.client.DefaultHttpClient class and has the same API, with the following exceptions:

  • Some SSL certificate validation checking can be disabled for development purposes. This should not be done for production deployments.
  • The connection manager associated with a BlackBerry Dynamics HTTP Client instance should always be closed by calling its shutdown() method before the client instance is released or goes out of scope. This ensures that SSL verification can be re-enabled.
  • This class is not thread-safe. Use of ThreadSafeClientConnManager is not supported. This class only supports SingleClientConnManager.
  • Data communication does not go via the proxy specified in the mobile device's native settings, if any.
  • Kerberos authentication is supported.

If the BlackBerry UEM  server has disallowed connections to any server, the address of the destination app server must be registered in the UEM management console.

The HTTP networking section of these samples is based on the Android HTTP network connection sample included with Android Studio. If you have also based your networking classes on this example, the changes to HttpFragment.java are concentrated within a single method. Refer to the before HttpFragment.java and after HttpFragment.java or the before HttpFragment.kt and after HttpFragment.kt for complete code samples.

Update Import Statements

Original

import java.net.HttpURLConnection;
import java.net.URL;

BlackBerry Dynamics

import com.good.gd.apache.http.HttpResponse;
import com.good.gd.apache.http.client.methods.HttpGet;
import com.good.gd.net.GDHttpClient;

 

Modify the downloadUrl Method

Original

private InputStream downloadUrl(String urlString) throws IOException {
    URL url = new URL(urlString);
    HttpURLConnection conn = (HttpURLConnection) url.openConnection();
    conn.setReadTimeout(10000 /* milliseconds */);
    conn.setConnectTimeout(15000 /* milliseconds */);
    conn.setRequestMethod("GET");
    conn.setDoInput(true);
    // Start the query conn.connect();
    InputStream stream = conn.getInputStream();
    return stream;
}

BlackBerry Dynamics

private InputStream downloadUrl(String urlString) throws IOException {
    GDHttpClient httpclient = new GDHttpClient();
    final HttpGet request = new HttpGet(urlString);

    HttpResponse response = httpclient.execute(request);
    InputStream stream = response.getEntity().getContent();

    return stream;
}

Update Import Statements

Original

import java.net.HttpURLConnection
import java.net.URL

BlackBerry Dynamics

import com.good.gd.apache.http.HttpResponse
import com.good.gd.apache.http.client.methods.HttpGet
import com.good.gd.net.GDHttpClient

 

Modify the downloadUrl Method

Original

@Throws(IOException::class)
 private fun downloadUrl(urlString: String): InputStream {    
    val url = URL(urlString) url.openConnection();
    val conn = url.openConnection() as HttpURLConnection
    conn.readTimeout = 10000
    conn.connectTimeout = 15000
    conn.requestMethod = "GET"
    conn.doInput = true    
    // Start the queryInputStream stream = conn.getInputStream();
    conn.connect()
return conn.inputStream

}

BlackBerry Dynamics

@Throws(IOException::class)
private fun downloadUrl(urlString: String): InputStream {   

    val httpclient = GDHttpClient()
    val request = HttpGet(urlString)
    val response = httpclient.execute(request)
    return response.entity.content
}

This class is an extension of the native java.net.Socket class, for utilizing BlackBerry Dynamics secure communication. See the BlackBerry Dynamics Communication Package for an introduction to the BlackBerry Dynamics secure communication feature.

This class offers the same API as the java.net.Socket class, with the exception of the following features that are not supported:

  • Out of band data
  • Urgent messages feature
  • Traffic class
  • Server socket methods (such as accept())
  • bind() method
  • connect (SocketAddress) method

If the app attempts to use an unsupported feature, a java.lang.UnsupportedOperationException is thrown. Only the default constructor is supported. Other constructors, for example those with parameters for proxy or host address, are not supported.

A GDSocket must always be closed by calling the close() method to prevent resource contention. This applies even if the socket was never connected or used. An unused java.net.Socket object can be safely abandoned without the need for an explicit close.

Data communication does not go via the proxy specified in the mobile device's native settings, if any. The getInetAddress() method does not return the address of the connected remote host.

If your BlackBerry UEM server has disallowed connections to any server, the address of the destination app server must be registered in the enterprise's UEM management console.

For more information, see the GDSocket class reference.

Looking at the modifications required for socket connections in the samples, the required changes are almost limited to changing the import statement and class name. There is one other minor modification because the constructor for Socket and GDSocket differ slightly. Refer to the before Socketfragment.java  and after Socketfragment.java or before SocketFragment.kt and after SocketFragment.kt files for complete code samples.

Update Import Statements

Original

import java.net.Socket;

BlackBerry Dynamics

import com.good.gd.net.GDSocket;

 

Update Class Name and Constructor to use connect Method

Original

Socket socket = null;
socket = new Socket("developer.blackberry.com", 80);

BlackBerry Dynamics

GDSocket socket = null;
socket = new GDSocket();
socket.connect("developer.blackberry.com", 80, 1000);

Update Import Statements

Original

import java.net.Socket

BlackBerry Dynamics

import com.good.gd.net.GDSocket

 

Update Class Name and Constructor to use connect Method

Original

var socket: Socket? = null
socket = Socket("developers.blackberry.com", 80)

BlackBerry Dynamics

var socket: GDSocket? = null
socket = GDSocket()
socket.connect("developers.blackberry.com", 80, 1000)

Secure Widgets

The BlackBerry Dynamics runtime may secure or block text in transit to or from the clipboard, depending on the policies for data leakage prevention (DLP) policy configured in BlackBerry UEM. The runtime secures text by encrypting it when it is cut or copied to the device clipboard, and then decrypting it when it is pasted from the clipboard.

The BlackBerry Dynamics SDK provides replacement widgets that implement this functionality. Other functions of these widgets remain the same. For an example of their use, refer to the SecureCopyPaste sample project in the BlackBerry Dynamics Android Samples.
 

Basic Widgets
 

The classes from BlackBerry Dynamics SDK can be used simply by changing their package from android .widget to com.good.gd.widget
 

AppCompat Widgets

Replacement classes for AppCompat widgets are available, that are subclassed from the AppCompat view classes. These are as follows:

These classes should be used in any app that uses AppCompatActivity.
 

Automatic Widget Substitution in AppCompat apps
 

Apps using a theme derived from AppCompat can install the provided GDAppCompatViewInflater in their theme as follows:

<style name="AppTheme" parent="Theme.AppCompat">
  <item name="viewInflaterClass">com.good.gd.app.GDAppCompatViewInflater</item>
</style>

This will automatically substitute the following classes in layout files:

Specified Widget Class Name

Replacement Class

TextView or
androidx.appcompat.widget.TextView or
GDAppCompatTextView

GDAppCompatTextView

 

CheckedTextView or
androidx.appcompat.widget.CheckedTextView or
GDAppCompatCheckedTextView

GDAppCompatCheckedTextView

 

AutoCompleteTextView or
androidx.appcompat.widget.AutoCompleteTextView or
GDAppCompatAutoCompleteTextView

GDAppCompatAutoCompleteTextView

 

MultiAutoCompleteTextView or
androidx.appcompat.widget.MultiAutoCompleteTextView or
GDAppCompatMultiAutoCompleteTextView

GDAppCompatMultiAutoCompleteTextView

 

EditText or
androidx.appcompat.widget.EditText or
GDAppCompatEditText

GDAppCompatEditText

 

androidx.appcompat.widget.SearchView or
GDAppCompatSearchView

GDAppCompatSearchView


Note, however:

  • This does not apply to the programmatic creation of widgets, or to JetPack Compose
  • SearchView is included in this scheme, but only when the full class name of the AppCompat class is given. The reason for this is that the AppCompat Searchview widget is not a subclass of the base Android class, so the Activity/Fragment code would have to be updated in any case.
     

Use BlackBerry Dynamics ClipboardManager

Copy and paste as well as drag and drop operations can be supported in the original android.widget classes or in other custom fields by making use of  com.good.gd.content.ClipboardManager, which is a replacement for  android.content.ClipboardManager.

For an example of its use, refer to the SecureClipboardView class in the SecureCopyPaste sample project in the BlackBerry Dynamics Android Samples
 

Disable AutoFill

Some apps, such as password managers or keyboards, can learn from and fill out views in other apps. This is a form of data leakage that should be disabled. This functionality is disabled in the com.good.gd.widget.* classes.  It should be disabled in other widgets by overriding the  getAutofillType()  method as shown below.

@Override
public int getAutofillType() {
   return AUTOFILL_TYPE_NONE;
}

override fun getAutofillType(): Int {
  return AUTOFILL_TYPE_NONE
}

Congratulations on developing your first BlackBerry Dynamics secured app! You can continue to explore the available APIs and developer resources. Learn about some of the common APIs below.

The code snippets referenced in this section are available in the iOS sample apps from the BlackBerry GitHub site. Download the BlackBerry Dynamics iOS Samples repository and see these projects:

  • Basic-iOS-Objective-C
  • Basic-iOS-Swift
  • Dynamics-iOS-Objective-C
  • Dynamics-iOS–Swift
  • Dynamics-SwiftUI-Sample

To see the full details of BlackBerry Dynamics APIs, see the BlackBerry Dynamics SDK API Reference.

The secure file system is part of the BlackBerry Dynamics Secure Storage feature. For apps, the BlackBerry Dynamics secure file system behaves like the default file manager system, with the following differences:

  • All data within the secure file system is stored on the device in an encrypted form.
  • Directory and file names are also encrypted.
  • There is no current working directory in the secure file system. Paths should always be specified as absolute paths, beginning with a / character.
  • The secure file system cannot be accessed until BlackBerry Dynamics authorization processing is complete. For more information, see authorize in the GDiOS class reference.

Encryption and decryption are transparent to the app code:

  • File-writing interfaces accept plain data. The BlackBerry Dynamics Runtime encrypts the data and stores it on the device.
  • When a file-reading interface is utilized, the BlackBerry Dynamics Runtime decrypts what was stored and returns plain data.
  • Path access interfaces accept plain parameters for directory and file names. The BlackBerry Dynamics Runtime encrypts the parameter values to create paths in the secure store.
  • The directory and file names provided as return values are plain. The BlackBerry Dynamics Runtime decrypts paths in the secure store to generate the return values.

The encryption method used by the BlackBerry Dynamics Runtime generally requires that the user has entered a security password from which an encryption key is derived.

Since the GDFileManager class is a subclass of the native NSFileManager class, minimal changes are required. Simply replace references to NSFileManager with references to GDFileManager.

Comparing before and after code snippets from the two sample apps, you’ll observe the following changes:

Native

import Foundation
...

func writeToNativeFile() -> Bool {
    let text = "Text not protected."
    let fileData = text?.data(using: .utf8)
    let filePath = documentsFolderPathForNamed(name: "NativeFileTest.txt")

    //Create a plain file using FileManager
    let fileCreated = FileManager.default()
        .createFile(atPath: filePath,
            contents: fileData,
            attributes: nil)
    return fileCreated
}

Dynamics

import BlackBerryDynamics.SecureStore.File

...

func writeToGDFile() -> Bool {
    let text = "Text to be protected by BlackBerry Dynamics."
    let fileData = text?.data(using: .utf8)
    let filePath = documentsFolderPathForNamed(name: "EncryptedFileTest.txt")

    //Create an encrypted file using GDFileManager
    let fileCreated = GDFileManager.default()
        .createFile(atPath: filePath,
                contents: fileData,
                attributes: nil)
    return fileCreated
}

 

The secure SQL database is part of the BlackBerry Dynamics Secure Storage feature. Data stored in the secure SQL database is encrypted on the device by the BlackBerry Dynamics Runtime. The BlackBerry Dynamics secure SQL database is based on the SQLite library. Encryption is added by BlackBerry Dynamics transparently to the app. A secure SQL database cannot be accessed until BlackBerry Dynamics authorization processing is complete.

BlackBerry Dynamics apps access the secure database using replacements for the native SQLite. To access the replacement classes instead of the native classes, change the import statement sqlite3.h to GD_C.SecureStore.SQLite (for Swift sources) or BlackBerryDynamics/GD_C/sqlite3enc.h (for Objective-C sources)

For more information about using SQLite databases, refer to the Secure SQL Database API.

If you compare the modifications required for SQLite between the native samples and the BlackBerry Dynamics sample, you’ll notice that the changes are minimal. Updates are required to the import statements and opening and importing of an encrypted database. The rest of the SQLite in the app can remain as is. Here are the changes that were made:

Native

import SQLite

...

func openDatabase() -> Bool {
    let fileUrl = try! FileManager.default
            .url(for: .documentDirectory,
                in: .userDomainMask,
                appropriateFor:nil,
                create: false)
        .appendingPathComponent("plain_database.db")
    var db:OpaquePointer? = nil
    let result = sqlite3_open(fileUrl.path, &db)

    return result == SQLITE_OK
}

Dynamics

import GD_C.SecureStore.SQLite

...

func openDatabase() -> Bool {
    let fileUrl = try! FileManager.default
                .url(for: .documentDirectory,
                    in: .userDomainMask,
                    appropriateFor:nil,
                    create: false)
                .appendingPathComponent("encrypted_database.db")
    var db:OpaquePointer? = nil
    let result = sqlite3enc_open(fileUrl.path, &db)

    return result == SQLITE_OK
}

GDURLLoadingSystem

BlackBerry Dynamics applications can use the native URL Loading System. The native URL Loading System classes can be used to communicate with app servers that are residing behind an enterprise firewall or on the Internet. Once a connectivity profile is configured in BlackBerry UEM for secure communication, the native class NSURLSession or NSURLConnection should work as is.

See the BlackBerry Dynamics SDK API Reference and review the GDURLLoadingSystem class and NSURLSession support.

GDHttpRequest API as an alternative approach

In addition to the GDURLLoadingSystem, you can use the GD HTTP Request API to send HTTP requests, such as GET and POST, from the device to an app server. The app server can be on the Internet or behind the enterprise firewall as well. The GD HTTP Request API is based on the XML Http Request (XHR) standard.

BlackBerry Dynamics secure communications support HTTPS, using a Secure Socket Layer connection or SSL/TLS to send the HTTP request and receive the response. HTTP and HTTPS requests can be relayed by an HTTP or HTTPS proxy that resides on the Internet or behind the enterprise firewall. Authentication with the proxy is supported.

When making HTTPS requests through an HTTP proxy, SSL/TLS certificate verification must be disabled. Certificate verification while using an HTTP proxy is not supported. BlackBerry Dynamics HTTP data communication does not go via the proxy specified in the device's native settings, if any.

The BlackBerry Dynamics Runtime supports Basic Access, Digest Access, NTLM, and Kerberos for authentication with HTTP servers. Except for Kerberos, all of these mechanisms are also supported for authentication with HTTP proxies. The BlackBerry Dynamics Runtime supports Kerberos version 5 authentication.

By default, HTTP cookies received through BlackBerry Dynamics secure communication are handled automatically.

For more information, see the GDHTTPRequest class reference. The changes required for the GD HttpRequest class are listed below:

// Open a requested URL using URLSession
func requestData(url : String) {
    let nsUrl = URL(string: url)
    let urlRequest = URLRequest(url: nsUrl!)
    let session = URLSession.init(configuration: URLSessionConfiguration.default, delegate: self,
                delegateQueue: OperationQueue.init())


    let task = session.dataTask(with: urlRequest,
                completionHandler: { (data, response, error) in
                    DispatchQueue.main.async {
                        print(response ?? "res")
                    }
                })
    task.resume()
}

The GDSocket API is asynchronous and state-based. The app attaches its own event-handler callbacks to the GD Socket object. The callback functions are invoked when socket events occur, or when the socket changes state. The API functions that can be called by the app depend on the socket's state.

Sending data through a GDSocket is a two-stage operation. The first stage is to add the data to the socket's outbound buffer. The socket's outbound buffer is represented by the writeStream property and is accessed using the GDDirectByteBuffer API. The second stage is to send the contents of the buffer through the socket connection. To send the buffer, call the write function.

Reading data from a GDSocket is asynchronous. When data is received at the device, the data is stored in the socket's inbound buffer. The app is then notified that data is available to read, by invocation of the delegate onRead callback. In the callback, the app consumes the received data from the inbound buffer. The inbound buffer is represented by the readStream property and is accessed using the GDDirectByteBuffer API.

The GDSocket API supports the use of SSL/TLS to send and receive data. By default, the BlackBerry Dynamics runtime does not offer the TLSv1.1 or TLSv1.2 protocols for SSL/TLS connections with an app server.

These protocols can be enabled, as follows:

  1. Add a new row to the application's Info.plist file:
    • Key:  GDControlTLSVersions
    • Type:  String  (the default)
  2. Set the value to:
    • GDEnableTLS1.1  to enable the TLSv1.1 protocol.
    • GDEnableTLS1.2  to enable both TLSv1.1 and TLSv1.2 protocols.
    As an alternative, the value can instead be an array containing one or both of the above strings as separate items.

The GDSocket connections and HTTP requests can be used to connect to servers that are behind the enterprise firewall. The address of the destination app server must be registered in the BlackBerry UEM management console.

  • The address could be registered as the app's server or as an additional server.
  • The app server configuration in the UEM server can be obtained in the app code by using the getApplicationConfig(GDiOS) function.

The connection to the app server will be made through the BlackBerry Dynamics proxy infrastructure. Verify the status of the mobile app's connection to the proxy infrastructure before attempting to open the socket or sending the HTTP request.

The changes required for the GDSocket class are listed below:

Native

import CoreFoundation


...


class SocketHelper: StreamDelegate {

    func connectToServer() {
        var readStream: Unmanaged<CFReadStream>?
        var writeStream: Unmanaged<CFWriteStream>?

        var inputStream: InputStream
        var outputStream: OutputStream

        let port = UInt32(80)
        let host = "developer.blackberry.com" as CFString
                    CFStreamCreatePairWithSocketToHost(nil, host, port, &readStream, &writeStream)

        inputStream = readStream!.takeRetainedValue()
        outputStream = writeStream!.takeRetainedValue()

        inputStream.delegate = self
        outputStream.delegate = self

        inputStream.schedule(in: RunLoop.current, forMode: RunLoop.Mode.default)
        outputStream.schedule(in: RunLoop.current, forMode: RunLoop.Mode.default)

        inputStream.open()
        outputStream.open()

    }

    func stream(_ aStream: Stream, handle eventCode: Stream.Event) {
        ....
    }

}

Dynamics

import BlackBerryDynamics.SecureCommunication

...

class GDSocketHelper: GDSocketDelegate {

    func connectToServer() {
        let port = Int32(80)
        let host = NSString(string: "developer.blackberry.com")
        let gdSocket = GDSocket(host.utf8String!, onPort: port, andUseSSL: false)

        gdSocket.delegate = self
        gdSocket.connect()
    }

    func onOpen(_ socket: Any) {
        let gdSocket = socket as! GDSocket;
        let httpString = NSString(string:
                "GET http://developer.blackberry.com/ HTTP/1.1\r\n" +
                "Host:developer.blackberry.com:80\r\n" +
                "Connection:close\r\n" +
                "\r\n")

        gdSocket.writeStream?.write(httpString.utf8String!)
        gdSocket.write()
    }

    func onRead(_ socket: Any) {
        let gdSocket = socket as! GDSocket;
        let str = gdSocket.readStream?.unreadDataAsString()
        DispatchQueue.main.async {
            print(String(describing: str))
        }
        gdSocket.disconnect()
    }

    func onClose(_ socket: Any) {
        let gdSocket = socket as! GDSocket;
            // do something if necessary
    }
}

Copy and Paste

The BlackBerry Dynamics runtime may secure or block text in transit to or from the clipboard, depending on the policies for data leakage prevention (DLP) policy configured in BlackBerry UEM. The runtime secures text by encrypting it when it is cut or copied to the device clipboard, and then decrypting it when it is pasted from the clipboard. On iOS, these operations are handled automatically by the BlackBerry Dynamics Runtime.  No coding changes are required to support this on iOS.

Disable AutoFill

To block password AutoFill, make the TextField an implementation of BBDAutoFillBlockerField. The BBDAutoFillBlockerField class is open source and demonstrated in the AutoFillBlockingSample.

      

Get Started with Other Platforms

BlackBerry also supports Microsoft .NET and React Native


Use these manuals to get started: Microsoft.iOSMicrosoft.Android | React Native