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, and Cordova. 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 BlackBerry Dynamics platform supports common business operating systems, mobile, and desktop, including iOS, Android, macOS and Windows.

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 a Network Operations Center (NOC). 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 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 target platform (iOS, Android, Windows, macOS). BlackBerry also offers plug-in support for cross platform technologies such as Apache Cordova, HTML5, and Xamarin.

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

The BlackBerry NOC enables secure communication between your BD Runtime app and the BlackBerry Proxy. The NOC 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, Good Control (GC), and BlackBerry Proxy servers are included in 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 Lync, 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 all major platforms and development technologies including:

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:

The BlackBerry Dynamics SDK is now ready to use in your Android projects.

Note: In the BlackBerry Dynamics SDK version 4.0 and later, there is a change to the extracted folder structure in the extras/blackberry/dynamics_sdk folder. At this level there is now an m2repository/ folder for .aar distribution, and an sdk/ folder that contains the original .jar distribution and resources. If you are updating the SDK to version 4.0 or later, you must edit your settings.gradle files as necessary to account for the extra sdk/ folder at this level.

Open your Android home directory in a file manager app or change to the directory in a terminal window. This is the directory named sdk and should be in the following locations, which may be hidden by default.

Windows: C:\Users\[username]\AppData\Local\Android

Mac: /Users/[username]/Library/Android/sdk

Navigate from this directory to the extras sub-directory.

Navigate to the blackberry sub-directory. If there isn’t already a sub-directory named blackberry, create it and navigate to it.

If there is already a directory named dynamics_sdk here, then you may already have an installation of the BD SDK for Android. You can move or delete the current directory, or use a different name for the new directory.

Copy the BD SDK for Android zip file into the blackberry directory and extract its files, or extract the files here directly. This will create a directory structure with a directory named sdk as its root.

Rename the new sdk directory to dynamics_sdk.

The BlackBerry Dynamics SDK is now ready to use in your Android projects.

Compatibility

Xcode 9.2

Apache Cordova version 8.0.0

Node.js version 10.14.2+ LTS

macOS Sierra

Set up the BlackBerry Dynamics SDK for iOS

Before continuing, you must set up your environment for iOS development. Please select the iOS platform above to view the setup requirements and instructions for an iOS environment.

Note: The cordova-plugin-bbd-configure plugin will try to generate paths to the SDKs for Android and iOS. If you have trouble with the auto-discovery feature, or have multiple BBD SDK versions installed, you may wish to manually specify the paths to the applicable SDK(s). Please see the README.md file in the cordova-plugin-bbd-base plugin folder for advanced usage. If you are only developing for iOS, use the --variable ignoreFailure="true" flag with the command.

7. 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

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

$ cordova build ios

You have now successfully built a BlackBerry Dynamics enabled app for iOS!

Note: If using iOS 12 and XCode 10:

Cordova 8.0.0 does not currently support Xcode 10.

Workaround: The following workarounds require Cordova iOS 4.5.5 or later. New projects will use this version by default. You can modify existing projects to use this version by updating the Cordova iOS platform (for example, by running cordova platform update ios).

Note: The cordova-plugin-bbd-configure plugin will try to generate paths to the SDKs for Android and iOS. If you have trouble with the auto-discovery feature, or have multiple BBD SDK versions installed, you may wish to manually specify the paths to the applicable SDK(s). Please see the README.md file in the cordova-plugin-bbd-base plugin folder for advanced usage. If you are only developing for iOS, use the --variable ignoreFailure="true"flag with the above command.

4. 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.

Workaround: The following workarounds require Cordova iOS 4.5.5 or later. New projects will use this version by default. You can modify existing projects to use this version by updating the Cordova iOS platform (for example, by running cordova platform update ios).

Note:There is a known issue that affects the configure plugins ability to automatically locate the Android Native SDK in some cases. If auto discovery is failing for you, as a temporary workaround, provide the path explicitly as described.

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

Note: There is a known issue which affects the configure plugins ability to automatically locate the Android Native SDK in some cases. If auto discovery is failing for you, as a temporary workaround, provide the path explicitly as described.

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

The BlackBerry Dynamics SDK contains a skeleton template project that you can use to create a new Android app. Create a copy of the Skeleton directory that you will use for your app. The Skeleton project is located in a sub-directory of your Android home directory with the following path: sdk/extras/blackberry/dynamics_sdk/sdk/samples/Skeleton/

The settings.json file is located within the assets folder of your project. It is used by the BlackBerry Dynamics (BD) Runtime to read configuration information about your app, such as the GD library mode, GD entitlement app ID and BD app version. Open the settings.json file and update the GDLibraryMode, GDApplicationID and GDApplicationVersion using the guidelines below:

GDLibraryMode: Can be set to either GDEnterpriseSimulation or GDEnterprise.

Use GDEnterpriseSimulation if you do not have a BlackBerry UEM Server, Good Control server, or a Good Control Cloud account and you are using an Android emulator.

Use GDEnterprise to test with a BlackBerry UEM Server, Good Control server, or Good Control Cloud for production deployments.

A connection to the BlackBerry Dynamics Network Operation Center (NOC) is required for both options.

GDApplicationID: A unique identifier for your app, which should be the same across all platforms (i.e. Android, iOS, etc.). This value is similar to the app package name. No capital letters or spaces are allowed. This value is also registered in the UEM or Good Control server.

GDApplicationVersion: This is a compatibility version for your BD enabled app. It should not match your app version, which can change more frequently. This should only be updated when compatibility related to BlackBerry Dynamics integration changes, such as when you add or remove BlackBerry Dynamics services in your app. Needlessly updating this to match your app version will result in additional work for both you and all administrators who have deployed your app.

The Skeleton project is called Skeleton. Skeleton is also used in the package and class names. It is recommended that you modify these names to something appropriate for your app. To modify, from the Project tab of Android Studio, right-click on the object to rename and choose Refactor > Rename.

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

It is recommended that you build your app after each section in this process. This will allow you to confirm each step and will make debugging problems easier.

The settings.json file is created within your project. It is used by the BlackBerry Dynamics (BD) Runtime to read configuration information about your app, such as the GD library mode, GD entitlement app ID and BD app version.

If you already have an assets folder in your project, skip to step #5. If not, proceed to step 2.

In Android Studio, right-click the top-level Application package and New > Folder > Assets Folder. This opens a dialog that provides a confirmation for where to create a source root for assets.

Leave the default options selected and click Finish.

Expand the package in which you just created the folder. The assets folder should appear under the package.

Right-click the assets folder and click New > File.

Enter settings.json as the file name and click OK.

Use one of the following examples to build your own settings.json file. Modify the examples to include your own GDApplicationID and GDApplicationVersion.

GDLibraryMode: Can be set to either GDEnterpriseSimulation or GDEnterprise. Use GDEnterpriseSimulation if you do not have a BlackBerry UEM Server, Good Control server, or a Good Control Cloud account and are using an Android emulator. Use GDEnterprise to test with a BlackBerry UEM Server, Good Control server or Good Control Cloud for production deployments. A connection to the BlackBerry Dynamics Network Operation Center (NOC) is required for both options.

GDApplicationID – A unique identifier for your app, which should be the same across all platforms (i.e. Android, iOS, etc.). This value is similar to the app’s package name. No capital letters or spaces are allowed. This value is also registered in the UEM or Good Control server.

GDApplicationVersion – This is a compatibility version for your BD enabled app. It should not match your app version, which can change more frequently. This should only be updated when compatibility related to BlackBerry Dynamics integration changes, such as when you add or remove BlackBerry Dynamics services in your app. Needlessly updating this to match your app version will result in additional work for both you and the administrators who have deployed your app.

BlackBerry Dynamics does not support right-to-left (RTL) layouts. This may require a change to your manifest file. Open AndroidManifest.xml in Android Studio and ensure supportsRtl is set to false as shown below.

android:supportsRtl="false"

If your application supports Android back-up, add the following line within the application tag of your AndroidManifest.xml. We recommend adding this line under the “allowBackup” parameter, which is set to true if your application supports back up.

The allprojects section should now look similar to the code below. Note that this sample assumes the BD SDK was installed to the default location. If you installed to a different location you will need to update the path in the url.

Note: Depending on your application’s needs, you may need to add further dependencies here. For example, if your application supports wearables, you will need to specify the appropriate BlackBerry Dynamics dependencies. For a full list of refer to the BlackBerry Dynamics Development Guide.

Press “Sync Now”, shown in the upper right of Android Studio.

The BD Runtime is now linked to the handheld app and you are ready to start making code changes to your app to integrate with the BD Runtime.

Establishing a connection to the BlackBerry Dynamics (BD) platform requires authorization of the end user and the app. Either of the following method calls can be used to initiate both authorizations:

Call authorize, which is direct initiation.

Call activityInit, which is indirect 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.

Authorization generally includes establishing a data connection to the UEM or BD proxy 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 BD 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 transition to the authorized state before attempting to utilize any other BlackBerry Dynamics APIs.

The MyActivity instance is implicitly its own authorization state transition observer. This is implemented by the declaration that the MyActivity class extends the GDStateListener interface.

Connection to the GD platform is initiated by calling activityInit in the onCreate method. This code would also be present in all the other activity classes in the app.

The principal processing of the activity, represented by the startSecureDBAccess and startAppComms calls, only proceeds when authorization processing is complete. This is implemented by placing the calls in the onAuthorized callback.

The private variable_authorizeCalled is used to ensure that authorize() is called only once.

The singleton MyGDAppEventListener object is set as the GD event handler.

The event handler would receive all GDAppEvent objects dispatched from the BD Runtime, which would include an event with type GDAppEventAuthorized when the end user is first authorized. After receiving that event, the app could make full use of all BlackBerry Dynamics APIs.

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 iOS

After installing the BlackBerry Dynamics SDK for iOS, use the BlackBerry Dynamics template to create a new app. This template includes a single view controller, a storyboard (or nib) file, and all of the necessary frameworks and compile time directives.

1. Start Xcode.

2. Select New > Project.

3. On the splash screen, select BlackBerry Dynamics.

4. Enter project information and set the language to Objective-C or Swift.

5. All necessary frameworks and artifacts have been included.

6. Open Info.plist file in the project and change GDApplicationID to your own:

GDApplicationID

The general form is com.yourcompany.application_name (only lower case, no spaces, and must not begin with com.good).

The same id can be used for multiple apps on different platforms, such as iOS and Android, therefore it is recommended to avoid including the platform specific information (example: com.yourcompany.good_application_for_ios).

GDApplicationVersion

A version number is four parts. Use 1.0.0.0 for the first BlackBerry Dynamics-enabled app.

It is not recommended to change the version often, unless 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.

7. On the General tab, remove the static setting for Main Interface.

8. Launch the main UI after the app is authorized.

All BD apps must be successfully authorized prior to launching the app’s main interface. Creating a BD skeleton app using the Xcode BlackBerry Dynamics template includes the required BD authorization functions, as well as BD event handling functions.

Check out the AppDelegate.h and AppDelegate.m files for those functions. You will notice that the app authorization functions are called first in the didFinishLaunchingWithOptions.

Once the app is authorized successfully, then you should programmatically load the app’s main interface in the code below.

In order to run and test your BD app, you will need to set up the BlackBerry Dynamics servers. Alternatively, if you don’t have the BlackBerry Dynamics environment set up, Enterprise Simulation Mode can be used to test your BD app, as it enables you test without connecting to the BlackBerry Dynamics servers.

In Enterprise Simulation Mode, there is no user authentication at the enterprise level, so there will be no communication through the enterprise firewall. If your app requires a connection behind the firewall, using the Enterprise Simulation Mode to test your BD app is not recommended. You will need to set up BlackBerry UEM or Good Control to test the app on a device.

Important: Enterprise Simulation Mode is not intended for a production environment.

To enable the Enterprise Simulation Mode for your BD app, add the following to your app's Info.plist file:

When your app is running for the first time on the iOS Simulator, you will be prompted to activate the app. In Enterprise Simulation Mode, you can enter any email address and any 15-character access key to complete the activation process. The app will go through the enterprise activation process. Once the app has been activated, you’ll be prompted to create a password to access the app.

The Password Requirements link at the bottom of the screen provides guidance on the required password complexity. Password complexity is controlled via policies managed by your IT admin through the BlackBerry UEM or Good Control administration console.

If you installed the BlackBerry Dynamics SDK for iOS in a location other than the default, change the initial part of the LDPLUSPLUS and LD settings in the file to your install path.

In your project build settings Configurations, make sure the Debug or other build configs point to the default.xcconfig file.

Ensure that the target is set to iOS 10 or higher.

Under Build Settings make sure you have -lz in Other Linker Flags field for the target.

5. Add GDAssets.bundle to the project.

Right-click on the GD.framework and select GD.framework > Resources > Show in Finder.

Drag and drop the GDAssets.bundle to the project.

Choose Create folder references when prompted for options for adding the files.

6. Set the BlackBerry Dynamics Application ID and 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).

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.good_application_for_ios).

GDApplicationVersion

A version number is four parts. Use 1.0.0.0 for the first BD-enabled app.

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.

7. Add a variable reference in the URL scheme and URL identifier specifiers. Add the following code into the info.plist.

14. Add a new private method didAuthorize that checks whether the end user has been authorized, checks that properties for the view controller and app delegate have been set, and then calls the app delegate didAuthorize function if all those conditions are met:

Make a note of the value of the key UIMainStoryboardFile and delete the key and value. You can also do this on the General tab. This value will be programmatically added after a successful BD authorization.

2. Open the AppGDiOSDelegate.m file. To handle the BD authorization events, add the following functions:

handleEvent

onNotAuthorized

onAuthorized

Note the code under the case GDErrorNone: in the onAuthorized function. When there is no error during the authorization process, you will need to add the code to load the main storyboard, which you deleted from the property file. Add code to instantiate and launch the initial view controller. Add a call to the new didAuthorize function that was just added. See the code below:

Make a note of the value of the key UIMainStoryboardFile and delete the key and value. You can also do this on the General tab. This value will be programmatically added after a successful BD authorization.

To run and test your BD app, you will need to set up the BlackBerry Dynamics servers. If you don’t have the BlackBerry Dynamics environment set up, Enterprise Simulation Mode can be used to test your BD app, as it allows you test without connecting to the BlackBerry Dynamics servers.

In Enterprise Simulation Mode, there is no user authentication at the enterprise level, so there will be no communication through the enterprise firewall. If your app requires a connection behind the firewall, using the Enterprise Simulation Mode to test your BD app is not recommended. You will need to set up the BlackBerry UEM or Good Control servers to test the app on a device.

Important: Enterprise Simulation Mode is not intended for a production environment.

To enable Enterprise Simulation Mode for your BD app, add the following to the app's Info.plist file:

When your app is running for the first time on the iOS simulator, you’ll be prompted to activate the app. In Enterprise Simulation Mode, you can enter any email address and any 15-character access key to complete the activation process. Once the app has been activated, you’ll be prompted to create a password to access the app.

The “Password Requirements” link at the bottom of the screen provides guidance on the required password complexity. Password complexity is controlled via policies managed by the IT admin through the BlackBerry UEM or Good Control administration console.

Although Enterprise Simulation Mode is not suitable for production deployment of your 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. In Enterprise Simulation Mode your BD apps are run on a device emulator.

To enable Enterprise Simulation Mode, whether you use an IDE or an outside text editor, you must change the following line in your app’s settings.json (Android) or or info.plist (iOS) file from:

"GDLibraryMode":"GDEnterprise"

to:

"GDLibraryMode":"GDEnterpriseSimulation"

Be sure to change it back when you are ready test the app with your BlackBerry UEM or BD enterprise servers or deploy it on a real device. When GDLibraryMode is set to GDEnterprise, default enterprise authentication is invoked to open the app.

On Android, the settings.json file is located in the ../assets/ folder of the app and must remain there. Communication with the BD Network Operations Center (NOC) still takes place during initial activation of the app, even in Enterprise Simulation mode. This means that the NOC must be accessible from the environment in which the app is running.

You will find that the app behaves differently than during standard enterprise execution in the following ways:

[Simulated] will appear in the BD Runtime user interface

Any email address and activation key (PIN) will be accepted for enterprise activation

No information is actually sent to BD enterprise servers, including the email address and activation key

The provisioning and policy setup flow is merely simulated in the UI

A hard-coded set of security and compliance policies will be 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 BD 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 or BD proxy infrastructure, although direct connections to enterprise app servers can still be made, if, for example, the AVD is running on a machine that is on the enterprise LAN or VPN.

A BlackBerry UEM server 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 BlackBerry UEM. If you do not yet have a BlackBerry UEM server or BlackBerry UEM Cloud instance in place, you can configure one with a free developer trail license. Click here to generate a trail license and start configuring your server.

Specify the BlackBerry Dynamics Entitlement ID and BlackBerry Dynamics Entitlement Version that was set in the app’s settings.json (Android) or info.plist (iOS) file. For example, com.blackberry. testApp and 1.0.0.0.

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 as necessary.

Recommendation: We recommend that you add the Android Package ID and Apple Bundle ID to your 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:

After an app is registered in UEM, you can entitle users to install and use the app. You can entitle individual users or user groups. For production deployment, it’s recommended to use user groups. When developing or testing, you may wish to entitle an app to just one or two users.

Log in to the UEM management console.

Search for and select a user account.

In the Apps section in the user profile, click +.

Search for and select your app. Click Next.

Leave the Disposition as optional (installation will not be forced) and select Assign. Now the application is assigned to the account you’ve selected.

Depending on your authentication delegation configuration, you may need to generate an Access Key that will be used when the app is run for the first time after a fresh install.

To generate a new Access Key:

In the user's profile, under Activation details, click Set Activation Password.

The access key is emailed to the user. To view the access key, click on the key link above the Set activation password button.

Install the app from your IDE to your device using the standard method you use when testing an app. Then enter your email address and newly created access key when prompted after running your app for the first time.

A Good Control and Good Proxy server is required to perform testing on an actual smartphone or tablet. If you do not yet have a Good Control and Good Proxy server in place, refer to the downloads section of this site for downloads and documentation. Alternatively, you can test using a Good Control Cloud account which is also described on that page.

By adding the BD app ID and Version only, you are not required to submit the binary app file (APK or IPA). Using this method also allows the app to be installed directly onto the device (from your IDE or side loaded).

Specify the GDapplicationID and GDapplicationVersion that was set in the app’s settings.json (Android) or info.plist (iOS) file. For example, com.blackberry. testApp and 1.0.0.0.

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

Recommendation: We recommend you add the Android Package ID and Apple Bundle ID to your app’s configuration. This allows the use of easy activation, which avoids the requirement of entering an access key when first starting the app. To add these values:

After an app is registered in Good Control, you can entitle users to install and use the app. This can be done using individual users or with user groups. For production deployment, it’s recommended to use user groups. When developing or testing, you may wish to entitle an app to just one or two users.

Log in to the Good Control management console.

Click Users and Groups.

Select a user account.

Click User Actions > Edit User.

On the APPS tab, click Add More.

Select the app and click OK.

Depending on your authentication delegation configuration, you may need to generate an Access Key that will be used when the app is run for the first time after a fresh install.

To generate a new Access Key, on the ACCESS KEYS tab, click New Access Key. After it is created, the access key is shown in the list of provisioned access keys.

Install the app from your IDE on your device using the standard method you use when testing an app. Then enter your email address and newly created access key when prompted after running your app for the first time.

You may want to learn more about the BlackBerry Dynamics 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 FileSystem, XMLHttpRequest.

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.

A few items of note:

File System

This plugin overrides the default Cordova FileSystem object and provides access to the secure file system automatically upon installation of the cordova-plugin-bbd-base plugin.

HTTP

This plugin overrides the default XMLHttpRequest object automatically upon installation of the cordova-plugin-bbd-base plugin. Calls made via XHR will automatically route through the BlackBerry Dynamics Proxy.

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.

SQLite

Provides access to the Secure Database by adding the cordova-plugin-bbd-storage plugin to your project.

Sockets

Provides access to the secure Socket communications API by adding the cordova-plugin-bbd-socket plugin to your project.

Cordova Sample Applications

We have provided several Sample Applications which show best practices when using the BlackBerry Dynamics Plugins. These samples are shipped with the SDK and is great resource for anyone looking to develop apps that deeply integrate with the SDK.

Configure the Sample Applications

Open your favorite Terminal program

Change the directory to the BBD-SDK-FOLDER/folder:

$ cd …/BBD-SDK-FOLDER

Add Configure plug-in to application:

$ cordova plugin add ../../plugins/cordova-plugin-bbd-configure

Add Platform to application:

For iOS: $ cordova platfrom add ios

For Android: $ cordova platform add android

Build desired sample app:

$ cordova build

You can deploy and test the sample applications using the methods covered on the Deploy & Test tab.

You may want to learn more about the BlackBerry Dynamics 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 FileSystem, XMLHttpRequest.

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.

A few items of note:

File System

This plugin overrides the default Cordova FileSystem object and provides access to the secure file system automatically upon installation of the cordova-plugin-bbd-base plugin.

HTTP

This plugin overrides the default XMLHttpRequest object automatically upon installation of the cordova-plugin-bbd-base plugin. Calls made via XHR will automatically route through the BlackBerry Dynamics Proxy.

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.

SQLite

Provides access to the Secure Database by adding the cordova-plugin-bbd-storage plugin to your project.

Sockets

Provides access to the secure Socket communications API by adding the cordova-plugin-bbd-socket plugin to your project.

Cordova Sample Applications

We have provided several Sample Applications which show best practices when using the BlackBerry Dynamics Plugins. These samples are shipped with the SDK and is great resource for anyone looking to develop apps that deeply integrate with the SDK.

Configure the Sample Applications

Open your favorite Terminal program

Change the directory to the BBD-SDK-FOLDER/folder:

$ cd …/BBD-SDK-FOLDER

Add Configure plug-in to application:

$ cordova plugin add ../../plugins/cordova-plugin-bbd-configure

Add Platform to application:

For iOS: $ cordova platform add ios

For Android: $ cordova platform add android

Build desired sample app:

$ cordova build

You can deploy and test the sample applications using the methods covered on the Deploy & Test tab.

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

The secure file system is part of the BlackBerry Dynamics Secure Storage feature. For apps, the BlackBerry Dynamics (BD) 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 BlackBerry Dynamics authorization processing is complete. For more information, see authorize in the GDAndroid class reference.

Encryption and decryption is transparent to the app code:

File-writing interfaces accept raw data. The BD Runtime encrypts the data and stores it on the device.

When a file-reading interface is utilized, the BD Runtime decrypts what was stored and returns plain data.

Path access interfaces accept plain parameters for directory and file names. The BD Runtime encrypts the parameter values in order to create paths in the secure store.

Directory and file names provided as return values are plain. The BD Runtime decrypts paths in the secure store in order to generate the return values.

The encryption method used by the BD Runtime generally requires that the user has entered a security password, from which an encryption key is derived. For more information, refer to the BD 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 files, you’ll observe the following changes:

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 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 in SqlFragment.java

This class is an extension of the Apache HttpClient for utilizing BlackBerry Dynamics secure communication. See the BD 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 BD 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 your BlackBerry UEM or Good Control server has disallowed connections to any server, the address of the destination app server must be registered in the UEM or GC management console.

The HTTP networking section of these samples are 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 for complete code samples.

This class is an extension of the native java.net.Socket class, for utilizing BlackBerry Dynamics secure communication. See the BD 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 or Good Control server has disallowed connections to any server, the address of the destination app server must be registered in the enterprise's UEM or GC management console.

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 files for complete code samples.

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 is transparent to the app code:

File-writing interfaces accept plain data. The BD Runtime encrypts the data and stores it on the device.

When a file-reading interface is utilized, the BD Runtime decrypts what was stored and returns plain data.

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 BD 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/sqlite3enc.h.

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 GD 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:

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 or in standalone Good Control for secure communication, the native class NSURLSession or NSURLConnection should work as is.

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 BD Runtime supports Kerberos version 5 authentication.

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

The GD Socket 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 GD Socket 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 GD Direct Byte Buffer 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 GD Socket 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 GD Direct Byte Buffer API.

The GD Socket API supports use of SSL/TLS to send and receive data. By default, the BD 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 app's Info.plist file as follows:

Key: GDControlTLSVersions

Type: String (the default)

2. Set the value to:

GDEnableTLS1.1 to enable the TLSv1.1 protocol

GDEnableTLS1.2 to enable the TLSv1.1 and TLSv1.2 protocols

Alternatively, the value can be an array containing one or both of the above strings as separate items.

The GD socket 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 or standalone Good Control (GC) management console.

The address could be registered as the app's server or as an additional server.

The app server configuration in the GC 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.

Corporate

legal Info

BlackBerry uses cookies to help make our website better. Some of the cookies are necessary for proper functioning of the site, while others are to help us understand how you use it. Read more here about our cookies, and how you can opt out.