BlackBerry Dynamics SDK forAndroidDevelopment Guide

4.2

2018-10-06Z

 |  | 2

Contents

About this guide................................................................................................5

BlackBerry Dynamics background..................................................................... 6BlackBerry Dynamics API reference..................................................................................................................... 6FIPS 140-2 compliance..........................................................................................................................................6Easy Activation....................................................................................................................................................... 7Securing cut-copy-paste on devices (Data Leakage Prevention, or DLP).......................................................... 7Shared Services Framework..................................................................................................................................7Support for fingerprint authentication.................................................................................................................. 7Support for client certificates................................................................................................................................8Support for the "Do not require password" setting............................................................................................. 8Bypassing the App Lock screen........................................................................................................................... 9BlackBerry Dynamics contributor code on GitHub.............................................................................................. 9Supported languages............................................................................................................................................. 9

BlackBerry Dynamics software versions..........................................................10

Requirements.................................................................................................. 11Compatibility with earlier releases......................................................................................................................11Software requirements.........................................................................................................................................11

Character encoding for build files: UTF-8...............................................................................................11BlackBerry Dynamics entitlement ID and version..............................................................................................12

Distinction from and use with native language identifiers....................................................................13Set the entitlement ID and entitlement version in settings.json........................................................... 14Including BlackBerry Dynamics entitlement version metadata for the Shared Service Framework....14

Supported launchModes......................................................................................................................................15Compatibility with the BlackBerry Dynamics Launcher Library........................................................................ 15Supported CPU architectures..............................................................................................................................15Supported and unsupported Android and third-party features.........................................................................16

Support for Samsung Pass......................................................................................................................16Android for Work and Samsung KNOX: supported, no programming................................................. 16Support for spannable text...................................................................................................................... 16

FIPS-linking on Android: automatic.................................................................................................................... 17FIPS compliance not supported for x86 emulators...............................................................................17

Restricted key prefix............................................................................................................................................ 17

Steps to get started with the BlackBerry Dynamics SDK..................................18Installing the BlackBerry Dynamics SDK for Android........................................................................................18

Installing and verifying the Android SDK from Google using Android Studio.......................................18Install the BlackBerry Dynamics SDK with Google's Android SDK manager........................................ 18Manually install the BlackBerry Dynamics SDK for Android..................................................................18High-level directory structure of the BlackBerry Dynamics SDK for Android....................................... 19

 |  | iii

Integrating the BlackBerry Dynamics SDK in .aar format................................................................................. 19Add .aar files if you installed the SDK using the Android SDK Manager.............................................. 19Add .aar files if you installed the SDK manually....................................................................................20Add .aar files as plain resources.............................................................................................................21

Using the branding API to add a custom logo and colors............................................................................... 21Info: Add Samsung Pass to your BlackBerry Dynamics app............................................................................21Info: APIs for secure clipboard management....................................................................................................22Info: Preventing autobackup to Google Drive....................................................................................................22Info: APIs for network status.............................................................................................................................. 22

BlackBerry Dynamics SDK for Android: Wearable Framework..........................24Wearable Framework video tutorials..................................................................................................................24Relation of Wearable Framework to the BlackBerry Dynamics SDK for Android............................................ 24Requirements: Handheld app and wearable app must use the same library version..................................... 25Distributing a wearable app built with the Wearable Framework.....................................................................25

Programming with the BlackBerry Dynamics SDK and BlackBerry EnterpriseMobility Server services.............................................................................. 26

Sample apps................................................................................................... 28

Testing and troubleshooting........................................................................... 30Automated test support library for Android.......................................................................................................30Emulators and the rooted OS compliance policy.............................................................................................. 30Using enterprise simulation mode......................................................................................................................30Logging and diagnostics..................................................................................................................................... 31

Log message categories..........................................................................................................................31Configure logging in Good Control..........................................................................................................32GDLogManager class for log uploading................................................................................................. 32GDDiagnostic API......................................................................................................................................32Configure the adb console.......................................................................................................................32Configure the container log..................................................................................................................... 33

Readying your app for deployment: server setup.............................................35Configuring library version compliance..............................................................................................................35Setting allowBackup=false for production apps, use BackupHelper............................................................... 36Build with ProGuard in production......................................................................................................................36

Details of support for client certificates..........................................................38BlackBerry Dynamics SDK support for personal certificates (PKCS12 or PKI certs)......................................38

Certificate requirements and troubleshooting........................................................................................39Client certificate sharing among BlackBerry Dynamics-based applications................................................... 39Kerberos PKINIT: User authentication with PKI certificates.............................................................................40

Legal notice.................................................................................................... 43

 |  | iv

About this guideThis guide is an introduction to the BlackBerry Dynamics SDK for Android. It focuses on how to install the SDK,how to use the project template in the BlackBerry Developers for Enterprise Apps portal, and introduces thesample apps that are packaged with the SDK.

This guide is intended for software developers who already have an understanding of developing software for theAndroid platform. It is not a basic tutorial.

For information about programming on Android, see the Android Developer Guides.

 | About this guide | 5

BlackBerry Dynamics backgroundThe following sections provide some background information that can help you understand the features of theBlackBerry Dynamics SDK.

The way that these features are implemented in your environment will depend on how your administrator hasconfigured your organization's servers, your network, and other infrastructure.

BlackBerry Dynamics API referenceThe BlackBerry Dynamics SDK API reference describes the available interfaces, classes, methods, and muchmore.

You can access the Android API reference:

• Online at https://developers.blackberry.com/us/en/resources/api-reference.html.• In the installed directories for the BlackBerry Dynamics SDK for Android.

FIPS 140-2 complianceBlackBerry Dynamics apps must comply with U.S. Federal Information Processing Standards (FIPS) 140-2.The BlackBerry Dynamics SDK distribution contains FIPS canisters and tools and, by default, enforces FIPScompliance.

On Android, FIPS compliance is automatic. No special build steps are required.

There are two components involved in enabling FIPS:

Component Description

BlackBerry Dynamics app The app must start in FIPS-compliant mode. The BlackBerry DynamicsSDK determines whether a service is running in FIPS mode when theapp communicates with the server to receive policies. All apps must bewritten for FIPS compliance.

Policy server (either standaloneGood Control or BlackBerry UEM)

For more details on FIPS policies, see Readying your app for deployment:server setup.

FIPS compliance enforces the following constraints:

• MD4 and MD5 are prohibited. As a result, access to NTLM-protected or NTLM2-protected web pages and filesis blocked.

• Wrapped apps are blocked.• In secure socket key exchanges with ephemeral keys, with servers that are not configured to use Diffie-

Hellman keys of sufficient length, BlackBerry Dynamics retries with static RSA cipher suites.

Note: When you enable FIPS compliance, user certificates must use encryption that meets FIPS standards.If a user tries to import a certificate with encryption that is not compliant, the user receives an error messageindicating that the certificate is not allowed and cannot be imported.

 | BlackBerry Dynamics background | 6

Easy ActivationThe Easy Activation feature simplifies the provisioning process by allowing a BlackBerry Dynamics app to handoff activation to an app that is already installed on the device and can act as the activation delegate. The user hasto retrieve and manually enter an access key only the first time they install a BlackBerry Dynamics app.

Securing cut-copy-paste on devices (Data Leakage Prevention, orDLP)You can use the BlackBerry Dynamics SDK to protect certain data copied and pasted between apps on your users'devices.

Server administrators must enable the Data Leakage Prevention policies in the management console.

To enable sharing among a group of apps, the apps must be provisioned from the same BlackBerry Controlservice for each user.

If the Data Leakage Prevention settings are enabled in your environment, you can work around them when youneed to debug your app. For more information, see the BlackBerry Dynamics SDK API Reference.

Shared Services FrameworkBlackBerry Dynamics-enabled apps can communicate with each other using the Shared Services Framework.There are two kinds of shared services:

• Server-side services• Client-side services

The BlackBerry Dynamics SDK contains sample apps that show how these services work.

For a conceptual background, see BlackBerry Dynamics Services Framework.

Support for fingerprint authenticationSupport for fingerprint recognition is a supplement to standard BlackBerry Dynamics secure user authentication,not a replacement for it. BlackBerry Dynamics includes the following policies related to fingerprint authentication.These settings are configured using policies in the management console:

• Allow or disallow fingerprint authentication for BlackBerry Dynamics-based apps in general.• If fingerprint authentication is allowed, you can also allow or disallow it for BlackBerry Dynamics apps

immediately after app coldstart. If you do not allow it after app coldstart, the user must enter the password forthe app.

• Require the end user to enter a password after a specified interval.

Note: For app developers, no additional programming work is necessary for fingerprint authentication. If the appsupports Samsung Pass, some linking directives are required. See Info: Add Samsung Pass to your BlackBerryDynamics app.

For more information, see BlackBerry Dynamics and Fingerprint Authentication.

 | BlackBerry Dynamics background | 7

Support for client certificatesBlackBerry Dynamics supports many popular uses of client-side Public Key Infrastructure (PKI) certificates tosecure apps and communications:

• General requirements for working with PKI certs• Description of client certificate sharing among BlackBerry Dynamics apps on a device• Kerberos PKINIT: client certificates in the Kerberos authentication model. (This is not Kerberos Constrained

Delegation, or KCD).

Support for the "Do not require password" settingThe BlackBerry Dynamics Runtime supports the "Do not require password" setting in a BlackBerry Dynamicsprofile in UEM or in a security policy in standalone Good Control. When this setting is enabled by an administrator,users cannot set a password for a BlackBerry Dynamics app or BlackBerry Dynamics container. Note that thissetting does not apply to the device password.

This setting is available in BlackBerry UEM 12.7 or later and standalone Good Control 3.0.50.70 or later.

Security considerations

• Consider the security impact to your organization's environment before an administrator enables this setting.If enabling this feature does not meet security standards, consider other options, including authenticationdelegation or assigning the profile to specific users or groups that are already assigned device managementprofiles or other controls.

• Do not enable the "Do not require password" setting and authentication delegation in the same policy set.• When the "Do not require password" setting is enabled, authentication can be accomplished only through user

interaction or autonomously. For more information, see "canAuthorizeAutonomously" in the SDK programmingreference for iOS or Android.

User experience when the rule is enabled or disabled

If a BlackBerry Dynamics app requires a password and the administrator enables the "Do not require password"setting, the next time the user opens the app, the app displays a message that a password is no longer required.As long as the feature is enabled, the user is not prompted for a password.

If the administrator disables the "Do not require password" setting, the next time the user opens the app, the appdisplays a message that a password is required. The user is prompted to specify a password.

Android: Optional APIs for the "Do not require password" policy rule

You can call the GDAndroid.getInstance().canAuthorizeAutonomously() method to determinewhether this feature is enabled for a BlackBerry Dynamics app.

Call GDAndroid.serviceInit() to start the authorization process when the app has received a GCM messageor background broadcast/explicit intent.

The GDInteraction sample app illustrates the use of these methods.

For syntax and details, see the SDK programming reference.

 | BlackBerry Dynamics background | 8

Bypassing the App Lock screenBlackBerry Dynamics supports the ability of an app to bypass the BlackBerry Dynamics user authentication/lockscreen. Some organizations want this feature, particularly in VoIP apps where the user needs to respond quicklyto an incoming call.

Note: Enabling this policy weakens the security inherent to BlackBerry Dynamics.

For information about requesting this feature, the necessary programming for bypassing the lock screen, thesetup of a required app policy, and other details, see Bypass Unlock: BlackBerry Dynamics app Developer Guide.

BlackBerry Dynamics contributor code on GitHubYou can access contributed code samples for the BlackBerry Dynamics SDK on GitHub at https://github.com/jhawkinsatgood/gdcontributor. BlackBerry encourages you to take advantage of contributed code for theBlackBerry Dynamics SDK and to contribute your own code to share. The contributor code includes a number ofcomplete BlackBerry Dynamics apps.

Supported languagesThe BlackBerry Dynamics SDK supports the following languages. No SDK calls are required to use a particularlanguage; the interface selects the appropriate language based on the language setting the user has configuredon their device.

• English (US)• Chinese (Simplified)• Danish• Dutch• French• German• Italian• Japanese• Korean• Portuguese (Brazil)• Portuguese (Portugal)• Spanish• Swedish

 | BlackBerry Dynamics background | 9

BlackBerry Dynamics software versions• BlackBerry Dynamics SDK for Android 4.2.x• BlackBerry Dynamics Launcher Library for Android 2.8.x

 | BlackBerry Dynamics software versions | 10

Requirements

Compatibility with earlier releasesThe latest release of the BlackBerry Dynamics SDK is compatible with the previous two releases.

Note: You should always build with and test against the most recent release. The most recent release has bugfixes and new features that you should test and deploy regularly.

Software requirementsAndroid development

Item Requirement

Supported Android OS Android 5.0 or later

BlackBerry Dynamics HandheldLibrary

Minimum API level: 21

BlackBerry Dynamics WearableLibrary

Minimum API level: 21

Supported CPU architectures • ARMv7• ARMv8• x86

Android Wear dependencies • Google Play Services 11.0.1• Android Wear Emulator API level 22

Suggested versions of platformand tools

• Android Studio 3 or later• The following values specified in sdk/libs/handheld/gd/

build.gradle. Other versions of tools will work, however,BlackBerry Dynamics library gradle files might need to be updatedaccordingly.

• com.android.tools.build:gradle: 2.3.2• compileSdkVersion 28• buildToolsVersion "28.0.0"

Character encoding for build files: UTF-8The BlackBerry Dynamics SDK for Android needs your build files (such as settings.json) to be in UTF-8 characterencoding.

Beware of inadvertently using an editor that adds non-UTF-8 characters or headers.

In general, Java does not work with UTF-8-BOM (byte order mark).

 | Requirements | 11

BlackBerry Dynamics entitlement ID and versionBlackBerry Dynamics apps are uniquely identified by a BlackBerry Dynamics entitlement ID (GDApplicationID)and entitlement version (GDApplicationVersion). The entitlement ID and entitlement version are used tomanage end-user entitlement for your apps, as well as for publishing and service provider registration. TheBlackBerry Dynamics entitlement ID was formerly known as the app ID or GD App ID.

The entitlement ID is used in the app, in the BlackBerry UEM or standalone Good Control management console forapp management, and in some administrative user interfaces on the application developer portal.

Note: The entitlement ID and entitlement version are different from the native application ID and nativeapplication version. The native application ID is a unique identifier for the app that is used by the OS andassociated platforms (for example, the package name for Android or bundle identifier for iOS). The nativeapplication version is the app version number that you must change if you want to distribute a new version of anapp (see Android Studio: Version Your App). You only need to change the entitlement version if the app starts toprovide a new shared service or shared service version, or if the app stops providing a shared service or sharedservice version. For more information about when to change the entitlement ID and entitlement version, see theBlackBerry Dynamics API reference.

Requirements for the entitlement ID and entitlement version

Requirement Description

Required for apps You must define both the entitlement ID and the entitlement version for allyour BlackBerry Dynamics apps, regardless of whether you use the BlackBerryDynamics Shared Services Framework. Developers and administrators shouldensure that the value specified for the GDApplicationVersion key in theapp configuration files is the same as the value the administrator specifies inBlackBerry UEM or in standalone Good Control.

The entitlement version is independent of any native version identifier.For more information, see Distinction from and use with native languageidentifiers.

Represent the same appacross all platforms

The same entitlement ID must be used to represent the app across allplatforms. By default, access to apps varies by the type of app:

• By default, all versions of partner or ISV apps are available to all authorizedusers in any organization that the app has been published to.

• By default, each version of a BlackBerry Dynamics app requires that theadministrator grant access in BlackBerry UEM or in standalone GoodControl before users can run the app on users' devices.

Naming scheme Develop a naming scheme to meet your needs. For example:

• Entitlement ID: com.manufacturingco.gd• Entitlement version: 1.0.0.0• Native application version: 2.0

 | Requirements | 12

Requirement Description

Entitlement ID format • The general form of an entitlement ID is <company_name>.<app_name>.• The ID must use reverse domain name form, for example,

com.company.example. Use a domain name owned by your organization.• The ID must not begin with com.blackberry, com.good, com.rim, or net.rim.• The ID can contain only lower-case letters, numeric digits, hyphens, and

periods.• The string must follow the <subdomain> format defined in section 2.3.1 of

RFC 1035, as amended by Section 2.1 of RFC RFC 1123.

Entitlement version value • The value must use one to four segments of digits, separate by periods(x.x.x.x).

• Each segment can be up to three digits and must not use a leading zero(for example, 01.02 is not valid). A segment can use a single 0.

• The first release of an app should use the entitlement version 1.0.0.0.

Distinction from and use with native language identifiersThe Entitlement ID and Entitlement Version are BlackBerry Dynamics specific metadata and are independent ofthe identifiers needed by the app platforms themselves. The key point is that the values and the native languageidentifiers' values can be the same but they do not necessarily have to be. Listed below by platform are theequivalent native identifiers, which are where the values of Entitlement ID and version are stored.

• AndroidManifest.xml

• packageName

• packageVersion

Unique native identifiers for enterprise apps

If you are developing a private app for use in your enterprise, make sure that the value you choose for the app'snative identifiers (Bundle ID and others constructs used on other platforms) is unique, especially with respect toapps that are available through the public app stores.

Duplicate native identifiers can prevent the proper installation or upgrade of your own app.

For all your native identifiers, devise a naming scheme that you can be relatively certain is unique.

Mapping BlackBerry Dynamics entitlement ID to native identifiers

To take advantage of many features, such as Easy Activation, multi-authentication delegation, and the sharedservices framework, developers need to set up a map in the server between your defined Entitlement ID and thenative identifiers on the platforms for which your app is distributed. The native platforms have no knowledge ofthe Entitlement ID; thus the mapping is needed for the operating systems to take over the actual function of theapp.

Native version identifiers: * wildcard allowed for blocking app

The SDK supports use of native version identifiers in keeping with the conventions described by the majorvendors. These same conventions apply to the use of the * wildcard in the server to deny apps by native version.

• Platform: AndroidpackageVersion

 | Requirements | 13

• A string of the format major.minor.point with no explicit requirement to use integers, although this is impliedand followed by convention.

• More information from Google

The * character can be used in native version identifiers, but must always be preceded by a period (.) and must bethe last character in the native version string. Examples:

• Allowed: 2.3.*• Not allowed: 2.*.3• 2.* includes 2.*.*

Set the entitlement ID and entitlement version in settings.jsonYou must create the file assets/settings.json and add to it the correct configuration information foryour app. You can copy the file from one of the sample apps and edit it. The GDApplicationID andGDApplicationVersion settings described here enable Inter Container Communication (ICC), among otherfeatures. For more background, see BlackBerry Dynamics entitlement ID and version. The content needs to looklike this, substituting your own GDApplicationID and GDApplicationVersion values:

{"GDLibraryMode": "GDEnterprise","GDApplicationID": "com.yourcompany.appname","GDApplicationVersion": "1.2.3.0","GDConsoleLogger": [ "GDFilterErrors_", "GDFilterWarnings_", "GDFilterInfo_", "GDFilterDetailed_" ]}

Including BlackBerry Dynamics entitlement version metadata for the Shared Service FrameworkFor apps that provide a service used by other apps, which is based on the Shared Services Framework, you shouldinclude the BlackBerry Dynamics Entitlement Version number directly in the app's AndroidManifest.xmlso that the SDK routines that work with services can identify the required version of the service provider. Forbackground information, see BlackBerry Dynamics entitlement ID and entitlement version.

The AppKinetics and AppKinetics Save Edit Service sample apps include example files that illustrate thenecessary entry.

In AndroidManifest.xml for an app that provides a service, the BlackBerry Dynamics entitlement version iscalled out in a <meta-data> tag in the <app> block, as shown in the following snippet.

Note: For backward compatibility, the name of the key is GDApplicationVersion, not "entitlement version".The value is defined by you, as discussed in BlackBerry Dynamics entitlement ID and entitlement version.

<manifest xmlns:android="http://schemas.android.com/apk/res/android" package="com.good.gd.example.appkinetics [...] <app [...] <meta-data android:name="GDApplicationVersion" android:value ="your_value_here"/> </app></manifest>

 | Requirements | 14

Important: In settings.json, the name/value pair required is: GDApplicationVersion. Be sure that thevalues are the same in both settings.json and AndroidManifest.xml files.

Supported launchModesApplications built with BlackBerry Dynamics SDK for Android can include (or not include) the following setting inAndroidManifest.xml:

launchMode value Supported

android:launchMode="standard" Yes

android:launchMode="SingleTop" Yes

android:launchMode="singleTask" Yes

android:launchMode="singleInstance" Yes

Compatibility with the BlackBerry Dynamics Launcher LibraryThe BlackBerry Dynamics SDK and the BlackBerry Dynamics Launcher Library are mutually dependent. If you usethe BlackBerry Dynamics Launcher as a front-end for your apps, verify that you are using the latest compatibleversions of the BlackBerry Dynamics SDK and the BlackBerry Dynamics Launcher Library. See BlackBerryDynamics software versions for the required versions.

Note: Your apps may not run as expected if you do not use compatible versions of the BlackBerry Dynamics SDKand the BlackBerry Dynamics Launcher Library.

Supported CPU architecturesThe BlackBerry Dynamics SDK includes the native libraries built for the ARMv7, ARMv8, and x86 CPUarchitectures. If you include the library project in your app, all of the ARMv7, ARMv8, and x86 libraries are includedwhen your app is built.

Consider the following:

• Including multiple CPU architectures can increase the size of the app.• x86 is primarily supported for Android emulators, as a faster option compared to ARM architectures. As a

result, you may only want to include the x86 library in test versions of your app that you want to run on anemulator.

• Ensure that your app build includes the native library for each CPU architecture that it uses. It is a best practiceto exclude native libraries for architectures that the app does not use. If the included libraries do not match thearchitecture used by the app, you may experience issues when running the app. For example, if your app usesa native library helloWorld_armv8.so, the app build must include the BlackBerry Dynamics ARMv8 library, anddoes not need to include the ARMv7 or x86 libraries.

You can specify the required CPU architectures using abiFilters in the build.gradle file. For example, to includeonly ARMv7 libraries in your project:

defaultConfig {

 | Requirements | 15

ndk { abiFilters "armeabi-v7a" }}

Supported and unsupported Android and third-party features

Support for Samsung Pass

The BlackBerry Dynamics SDK for Android fully supports Samsung Pass, the biometric authentication appdeveloped by Samsung.

For more information see Support for fingerprint authentication and Info: Add Samsung Pass to your BlackBerryDynamics app.

Known limitation in Samsung Pass

Samsung Pass does not have an API to detect newly added fingerprints and therefore does not invalidateprevious fingerprints.

This means that users are not prompted to reactivate apps when a new fingerprint is added.

This limitation also applies to Samsung Galaxy Note 4 and S5 devices running Android 5.0.

Android for Work and Samsung KNOX: supported, no programmingThe SDK supports the Android APIs that were formerly part of Android for Work (AfW) and Samsung KNOX.

No extra programming work is required for Android for Work to interoperate with the BlackBerry Dynamics SDK forAndroid or for Samsung KNOX to interoperate with BlackBerry Dynamics SDK for Android.

Support for spannable textThe BlackBerry Dynamics SDK for Android supports copying and pasting Spannable text. The following Spanobjects are supported:

• AbsoluteSizeSpan• AlignmentSpan• Annotation• BackgroundColorSpan• BulletSpan• EasyEditSpan• ForegroundColorSpan• LeadingMarginSpan• LocaleSpan• QuoteSpan• RelativeSizeSpan• ScaleXSpan• StrikethroughSpan• StyleSpan• SubscriptSpan• SuggestionSpan

 | Requirements | 16

• SuperscriptSpan• TextAppearanceSpan• TypefaceSpan• UnderlineSpan• URLSpan

FIPS-linking on Android: automaticWhen you build an app for production and run it, the app links for FIPS compliance automatically. No specialdirectives are required.

To verify that FIPS has been included, check that the following line is in the log output. This same line is printed atthe very start of the app launch:

IDeviceBase::initInstance: FIPS MODE REQUESTED

For information about logs, see Logging and diagnostics.

For more information about FIPS compliance, see FIPS 140-2 compliance and FIPS compliance not supported forx86 emulators.

FIPS compliance not supported for x86 emulators

FIPS compliance is not supported on x86 emulators. If you want to test on x86 emulators, you must not enableFIPS compliance.

Restricted key prefixNote that the key prefix "blackberry" is reserved by BlackBerry and should not be used for key values, keyattributes, or key elements. For more information and examples, see the "Application Policies Definition" page inthe appendix of the BlackBerry Dynamics SDK API Reference for Android or iOS.

 | Requirements | 17

Steps to get started with the BlackBerry Dynamics SDKFollow the steps below to start working with the BlackBerry Dynamics SDK. You can also see Getting Started withthe BlackBerry Dynamics SDK for a step-by-step walkthrough of the stages of developing a BlackBerry Dynamicsapp.

1. Download and install the BlackBerry Dynamics SDK. For information, see Installing the BlackBerry DynamicsSDK for Android.

2. Familiarize yourself with the features of the BlackBerry Dynamics SDK.

• For general information, see BlackBerry Dynamics background.• To view code samples, see Sample apps.

3. Understand the Requirements and possible constraints on your programming.4. Become familiar with available classes and methods in the BlackBerry Dynamics SDK API reference.5. If you are interested in Android wearables, see BlackBerry Dynamics SDK for Android: Wearable Framework.6. Add your own code. See Getting Started with the BlackBerry Dynamics SDK.7. Build your app. For some important considerations, see:

• Supported CPU architectures• Setting allowBackup=false for production apps, use BackupHelper

8. Test with enterprise simulation mode or your own testing methods.9. If necessary, troubleshoot your app. To help you troubleshoot issues, you can set up logging and diagnostics.

For more information, see Logging and diagnostics.10.Build with ProGuard in production11.Deploy your app. For options, see Ready your application for deployment.

Installing the BlackBerry Dynamics SDK for Android

Installing and verifying the Android SDK from Google using Android StudioBefore you install the BlackBerry Dynamics SDK, you must install the Android SDK. Complete download and setupinstructions are available from Google at https://developer.android.com/studio/index.html.

Verify that your installation is properly set up by writing and running a small "Hello, World!" program that is notbased on the BlackBerry Dynamics SDK.

Install the BlackBerry Dynamics SDK with Google's Android SDK managerStart the Android SDK Manager, then follow the steps detailed in the Getting Started with the BlackBerry DynamicsSDK on Android flow.

Note: In the BlackBerry Dynamics SDK version 4.0 and later, there is a change to the extracted folder structure inthe 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 version4.0 or later, you must edit your settings.gradle files as necessary to account for the extra sdk/ folder at this level.

Manually install the BlackBerry Dynamics SDK for Android1. Go to BlackBerry Developer Downloads and download the BlackBerry Dynamics SDK for Android2. Open your Android home directory in a file manager application, or change to the directory in a terminal

window. This is the sdk/ directory.3. From the sdk/ directory, navigate to the extras/ sub-directory.

 | Steps to get started with the BlackBerry Dynamics SDK | 18

4. If there isn’t already a directory named blackberry/ here, create it now. You can create the directory usingthe file manager or by running the mkdir command.

5. Change to the blackberry/ sub-directory.6. If there is already a directory named dynamics_sdk/ here, it might already contain an installation of the

BlackBerry Dynamics SDK for Android. You can move or delete the current directory, or use a different namefor the new directory. If there is no dynamics_sdk/ directory, go to the next step.

7. Copy the zip file that you downloaded to the blackberry/ directory and extract its files, or extract the fileshere directly. This creates a directory structure with a directory named sdk/ as its root.

8. Rename the new sdk/ directory dynamics_sdk/. You can rename the directory using the file manager or byrunning the mv or ren command.

High-level directory structure of the BlackBerry Dynamics SDK for AndroidThe BlackBerry Dynamics SDK for Android includes the following artifacts:

• A Library project that contains the resources needed for the UI to run in each BlackBerry Dynamics-enabledapp

• A .jar file that contains all BlackBerry Dynamics APIs and implementations• The BlackBerry Dynamics native library containing the native code• .aar files• An automated test support library

Handhelds vs. Wearables subdirectory naming convention

The BlackBerry Dynamics SDK for Android has a major division between support for handheld devices andsupport for wearable devices with the BlackBerry Dynamics Wearable Framework. The pertinent directorystructure looks like the following. Nested in these directories are the appropriate .so and .jar files you need toinclude in your project, along with other support files.

• Handheld libraries: sdk_installation_directory/sdk/libs/handheld/gd• Wearable libraries: sdk_installation_directory/sdk/libs/wearable/gd_wearable_framework

This same naming convention is also used elsewhere in the SDK package, such as for the sample applications.

Integrating the BlackBerry Dynamics SDK in .aar formatThe BlackBerry Dynamics SDK libraries are available in the SDK package as .aar files that can be published to aninternal repository. The files are found in m2repository/com/blackberry/blackberrydynamics.

Use one of the following methods to incorporate the .aar files into your BlackBerry Dynamics app projects. Theappropriate method depends on how you installed the SDK.

Add .aar files if you installed the SDK using the Android SDK ManagerIf you installed the SDK using the Android SDK Manager, the .aar files are added to the following path:ANDROID_HOME/extras/BlackBerry/dynamics_sdk/m2repository.

1. Define the path to the .aar files in the build.gradle repositories block.

Example: Hard-coded path

allprojects { repositories {

 | Steps to get started with the BlackBerry Dynamics SDK | 19

maven { url android.sdkDirectory.path+'/extras/blackberry/dynamics_sdk/m2repository' } //other maven URLs ... }}

Example: Path from local properties

allprojects { repositories { def localProperties = new File(rootDir, "local.properties") Properties properties = new Properties() localProperties.withInputStream { instr -> properties.load(instr) } def sdkDir = properties.getProperty('sdk.dir') maven { url sdkDir+'/extras/blackberry/dynamics_sdk/m2repository' } //other maven URLs ... }}

2. Add Gradle compile dependencies in the format <group_ID>:<artefact_ID>:<version>. For example:

dependencies { compile 'com.blackberry.blackberrydynamics:android_handheld_platform:4.0.0.3515' compile 'com.blackberry.blackberrydynamics:android_handheld_backup_support:4.0.0.3515' compile 'com.blackberry.blackberrydynamics:android_handheld_samsung_pass_support:4.0.0.3515' compile 'com.blackberry.blackberrydynamics:android_handheld_wearable_support:4.0.0.3515' compile 'com.blackberry.blackberrydynamics:android_wearable_platform:4.0.0.3515'}

Add .aar files if you installed the SDK manuallyIf you installed the BlackBerry Dynamics SDK manually, note the location of the m2repository directory andcomplete the following steps:

1. Define the path to the .aar files in the build.gradle repositories block. For example:

allprojects { repositories { maven { url '/path/to/m2repository' } //other maven URLs ... }}

Note: You can define the URL in the local.properties file to avoid VCS conflicts.2. Add Gradle compile dependencies in the format <group_ID>:<artefact_ID>:<version>. For example:

dependencies { compile 'com.blackberry.blackberrydynamics:android_handheld_platform:4.0.0.3515' compile 'com.blackberry.blackberrydynamics:android_handheld_backup_support:4.0.0.3515'

 | Steps to get started with the BlackBerry Dynamics SDK | 20

compile 'com.blackberry.blackberrydynamics:android_handheld_samsung_pass_support:4.0.0.3515' compile 'com.blackberry.blackberrydynamics:android_handheld_wearable_support:4.0.0.3515' compile 'com.blackberry.blackberrydynamics:android_wearable_platform:4.0.0.3515'}

Add .aar files as plain resources1. Add the .aar files to an appropriate folder, for example, libs.2. Define the path to the folder in the build.gradle file. For example:

allprojects { repositories { flatDir { dirs '<path_to_libs_folder>' } //other maven URLs ... }}

3. Add the Gradle dependencies. For example:

compile ( name : 'android_handheld_platform-4.0.0.5004' , ext : 'aar' )

Using the branding API to add a custom logo and colorsYou can use the branding API to add a custom logo and colors to the app UI. Make the following call beforeinitializing your activity with activityInit():

GDAndroid.configureUI(Drawable small_logo, Drawable big_logo, Integer color)

For more information see void configureUI in the BlackBerry Dynamics SDK for Android API Reference.

Info: Add Samsung Pass to your BlackBerry Dynamics appComplete the following steps to support Samsung Pass in your app. For background information, see Support forfingerprint authentication.

1. Download and unzip the Samsung Pass SDK v1.2.1 at http://developer.samsung.com/.2. Copy the following .jar files to the directory blackberry_dynamics_sdk_installation_directory/

libs/handheld/gd_samsungpass_support/libs:

• samsung_pass_unzipped_directory/Libs/pass-version.jar

• samsung_pass_unzipped_directory/Libs/sdk-version.jar

3. In your BlackBerry Dynamics SDK project, add the following example lines to settings.gradle. Be sure tocheck the relative path to the libraries:

include 'GDLibrary_SamsungPassSupport'project(':GDLibrary_SamsungPassSupport').projectDir = \

 | Steps to get started with the BlackBerry Dynamics SDK | 21

new File('../../libs/handheld/gd_samsungpass_support')

4. Add the following dependency to build.gradle:

dependencies { compile project(':GDLibrary_SamsungPassSupport')}

You can now build your app.

After you finish: ProGuard configuration: All the names of the classes in the Support Library and Samsung PassSDK must be retained to ensure their functionality. Add the following lines to your ProGuard configuration files:

-keep public class com.good.gd.support.samsungpass.** { *; }

-dontwarn com.good.gd.support.samsungpass.**

-keep class com.samsung.android.** { *; }

-dontwarn com.samsung.android.**

Info: APIs for secure clipboard managementThe BlackBerry Dynamics SDK includes APIs for managing the secure clipboard. On devices, you must use theBlackBerry Dynamics SDK secure-text-container-related classes:

• GDTextView

• GDEditText

• GDAutocompleteTextView

• GDSearchView

For details, see the API Reference section on Clipboard Manager.

For more information about secure cut and paste, see Securing cut-copy-paste on devices (Data LeakagePrevention, or DLP).

The Secure Copy-Paste sample app delivered with the SDK illustrates the use of these APIs.

Info: Preventing autobackup to Google DriveBy default, Android 5.0 and later devices automatically back up app data to Google Drive. To protect your appdata, you must prevent your app from backing up its data to Google Drive. You can find the instructions to specifypaths that can be excluded from autobackup, and other steps to prevent it, in the BlackBerry Dynamics APIreference.

For more information about autobackup see, http://developer.android.com/training/backup/autosyncapi.html.

Info: APIs for network statusThe BlackBerry Dynamics SDK for Android contains several APIs to manage network connections. For semanticsof parameters and other details, see the API Reference.

 | Steps to get started with the BlackBerry Dynamics SDK | 22

For examples of how to use the APIs, see the ApacheHttp sample app.

GDConnectivityManager

You can use the following class to control the connection from your app to the infrastructure.

GDNetworkInfo

This class represents the status of the connection from the app to the BlackBerry Dynamics infrastructure.Every BlackBerry Dynamics app connects to the BlackBerry Dynamics infrastructure whenever possible. Theconnection is maintained by the BlackBerry Dynamics Runtime in the mobile application. The BlackBerryDynamics infrastructure includes the BlackBerry Dynamics Network Operation Center (NOC) as well as a numberof other components that can be installed by the enterprise. The current status can be obtained synchronously. Itis also possible to receive notifications whenever the status changes.

void registerReceiver(BroadcastReceiver receiver, IntentFilter filter)

Call this method to register for specific notifications sent by local broadcast. There is only one notification sentby local broadcast: the change of network connection status. See the GDNetworkInfo class reference for detailsof this notification, and sample code. The receiver will be run on the main thread of the application. Long-runningprocessing generally shouldn't be run on the main thread. If the receiver processing is long-running then thereceiver should spawn a new thread, or use some other mechanism to cause the processing to take place on athread other than the main thread.

void unregisterReceiver(BroadcastReceiver receiver)

Call this method to remove a previously registered receiver of local broadcasts. The receiver is specified as aparameter. The specified receiver will not receive any more local broadcasts from the BlackBerry DynamicsRuntime, for any type of notification.

 | Steps to get started with the BlackBerry Dynamics SDK | 23

BlackBerry Dynamics SDK for Android: WearableFrameworkBlackBerry Dynamics's support for wearable devices includes a server-side policy to allow or disallow themwith BlackBerry Dynamics-enabled apps and the BlackBerry Dynamics Wearable Framework packaged with theBlackBerry Dynamics SDK for Android.

With the BlackBerry Dynamics Wearable Framework, you can create secure enterprise-grade solutions forwearable devices based on the Android OS. Developers can use the framework to add the following features/functionality into their apps:

• A secure way to pair the wearable device and handheld device (smartphone or tablet) apps, to ensure that yourhandheld app is securely communicating with the desired wearable app

• A secure, encrypted communication system between individual apps on wearable devices and handhelddevices

• Secure storage for wearable apps• A set of policies to manage the following:

• Allow usage of wearable devices• Timeout period: When a wearable device has been disconnected from the handheld device, the wearable

application is locked after a specific period of time, either immediately or up to an hour.• Auto-reconnect: A wearable application can be allowed to auto-authenticate with its paired handheld

application, after the wearable device is reconnected to the handheld device.

BlackBerry Dynamics Wearable Framework supports only Android Wear devices, which are described at http://www.android.com/wear/. Android Wear is a specific OS distribution officially released by Google.

The BlackBerry Dynamics SDK includes a sample wearable app that you can use as a starting point. For moreinformation, see Sample apps.

Wearable Framework video tutorialsThe following tutorials introduce the Wearable Framework and demonstrate various development aspects:

• Introducing the Wearable Framework• Wearable Framework Demo• Wearable Framework SDK Structure• Building and Debugging with Android Studio• Wearable APIs• Building your own Wearable app

Relation of Wearable Framework to the BlackBerry Dynamics SDK forAndroidThe BlackBerry Dynamics Wearable Framework is packaged and distributed with the BlackBerry Dynamics SDKfor Android.

• The BlackBerry Dynamics handheld app must be built using the BlackBerry Dynamics SDK for Android.• The corresponding BlackBerry Dynamics wearable application must be built using the BlackBerry Dynamics

Wearable Framework. In addition, to ensure the correct portions of the Wearable Framework are included in

 | BlackBerry Dynamics SDK for Android: Wearable Framework | 24

BlackBerry Dynamics handheld application, it must also built using the BlackBerry Dynamics Handheld WearSupport Library libs/handheld/gd_wear_support. The BlackBerry Dynamics Secure Store sample appshows the necessary build configuration.

All SDK programming reference information for the Wearable Framework is included in the SDK programmingreference for the BlackBerry Dynamics SDK for Android, both in the SDK package itself and also online as detailedin the BlackBerry Dynamics SDK API reference.

The API distribution explains which specific BlackBerry Dynamics APIs are applicable to handheld apps built withthe BlackBerry Dynamics SDK or wearable application built with BlackBerry Dynamics Wearable Framework orboth. The majority of APIs are common to both the handheld and the wearable app.

Requirements: Handheld app and wearable app must use the samelibrary versionMake sure that your handheld app and its corresponding wearable app have been compiled with the same versionof the BlackBerry Dynamics SDK libraries. Otherwise, one of the apps might crash and raise an exception similarto the following:

410KPVH0025159 02-20 18:29:43.878 2380 2380 E AndroidRuntime: FATAL EXCEPTION: main...410KPVH0025159 02-20 18:29:43.878 2380 2380 E AndroidRuntime: com.good.gd.error.GDError:Error BlackBerry Dynamics Android Wearable Framework App & BlackBerry Dynamics Android SDK Appmust be based on the same version of BlackBerry Dynamics,Ensure that both applications are built on libraries from the same SDK release

Distributing a wearable app built with the Wearable FrameworkBlackBerry Dynamics Wearable Framework is for apps that are installed and run directly on the device.

All Android Wear apps are components of handheld apps; they aren't deployed on their own. When a user installsthe handheld app on a phone or tablet that is connected to a wearable device, the Android Wear app is installed onthe wearable device. This is the standard behaviour for any Android Wear app, including apps developed using theBlackBerry Dynamics Wearable Framework.

 | BlackBerry Dynamics SDK for Android: Wearable Framework | 25

Programming with the BlackBerry Dynamics SDK andBlackBerry Enterprise Mobility Server servicesThis section covers the general approach for programming with the BlackBerry Dynamics SDK and the BlackBerryEnterprise Mobility Server services. The approach consists of two parts:

• Programming an app to interact with the desired BEMS services.• Entitling users to the necessary applications.

BEMS services conform to the BlackBerry Dynamics shared services framework. A service consists of twoapplications: A program that provides the service, and an app that consumes the service. BEMS is the serviceprovider that must be configured for use in BlackBerry UEM or in standalone Good Control. You create the appthat consumes this service.

BEMS services APIs

The BEMS services are described in the BEMS API Reference Guides.

Programming your service consumer app

You must define a unique BlackBerry Dynamics app ID for your application (for complete details, see BlackBerryDynamics entitlement ID and version). The BlackBerry Dynamics SDK has functions to discover services, and eachBEMS service has specific programming interfaces.

To discover the BEMS services, use GDServiceType. This API and other APIs for shared services are describedin other sections of this guide and in the BlackBerry Dynamics API reference.

After your consumer app discovers the service, the way the app communicates with the service depends on theservice definition.

Note: Most BEMS services run over SSL (HTTPS) on port 8443. Be sure your consumer application connects tothe correct server and port.

Discovering the BlackBerry Enterprise Mobility Server doc services

Described here is a general approach to using the BlackBerry Dynamics SDK and Server-based ServicesFramework to programmatically discover the Docs services offered by your BEMS installation.

Item Description

Service identifier First you need to know the service identifier and version. For more informationabout the available services, see Mobile Services.

Service discovery Next, code a service discovery query in your application program. The API for thatis GDServiceType in the GDAndroid, GDiOS, and GDMac classes.

 | Programming with the BlackBerry Dynamics SDK and BlackBerry Enterprise Mobility Server services | 26

Item Description

Server cluster The result of the service discovery query is an array of GDServiceProvider objects.Each object corresponds to a BlackBerry Dynamics entitlement identifier that isregistered as a provider of the service. Your best result is that the array has oneelement.

If the array is empty, it means that the current end user isn't entitled to any App IDthat provides the service. In that case, your app shouldn’t use the service.

If the array has more than one element, it means that the end user is entitled tomore than one GD App ID that provides the service (likely a configuration error bythe enterprise). Your app would have to pick one of the GD App Ids, or try all ofthem, or prompt the user to select.

In the GDServiceProvider object, there is a serverCluster attribute. Itcontains an array of GDAppServer objects, each of which tells you the addressand port number of a server, and the priority of that instance within the cluster.

Server selection If the serverCluster array has only one element, then server selection is trivial.Use the server address and port number of the first element.

If the serverCluster array is empty, that indicates an enterprise configurationerror.

If the serverCluster array has more than one element, then you mustimplement a server selection algorithm. A sample algorithm is given on theGDAndroid, GDiOS, and GDMac pages in the BlackBerry Dynamics API reference,in the getApplicationConfig section. The algorithm is the same forBlackBerry Dynamics SDK for Android and for BlackBerry Dynamics SDK for iOS.The recommended selection algorithm is as follows.

For each priority value in the list, starting with the highest:

• Select a server that has that priority, at random.• Attempt to connect to the server.• If connection succeeds, use that server.• If connection fails, try another server at the same priority, at random.• If there are no more untried servers at that priority, try the servers at the next

lower priority.

 | Programming with the BlackBerry Dynamics SDK and BlackBerry Enterprise Mobility Server services | 27

Sample appsYou can use the sample apps available in the BlackBerry Dynamics SDK for Android to help youplan the development of your apps. The source code samples demonstrate how to apply BlackBerryDynamics functionality. The most basic is the skeleton app, which can be used as a starting point forimplementing your own projects with BlackBerry Dynamics using Enterprise Simulation Mode.

The samples are located in <sdk_install_directory>/samples/, or you can download them from the BlackBerryDevelopers for Enterprise Apps site.

All sample apps have Android Gradle configurations. You can load any of the apps in Android Studio. Whenyou troubleshoot a BlackBerry Dynamics app, you should enable detailed logging from theconsole or buildconfiguration.

Note: It is recommended to make a copy of the source code in another location before making any changes.Reinstalling or upgrading will overwrite or even remove the sample apps in the default location.

Sample app Description

Apache HTTP client Provides an example of how to use BlackBerry Dynamics SecureCommunication APIs to access resources behind the enterprise firewall.These secure communication APIs can be used to exchange databetween the mobile app on the device and an application server using thesecure BlackBerry Dynamics proxy infrastructure.

In 4.0.0 and later, this sample supports HTTP PATCH requests.

AppBasedCertImport Demonstrates how to create an app that can import a user's PKI credentialsusing the BlackBerry Dynamics Certificate Credential Import API.

For more information, see Package com.good.gd.pki and "Creating usercredential profiles for app-based certifiactes" in the UEM AdministrationGuide.

AppKinetics Shared Services Provides three examples of how to use the BlackBerry Dynamics SharedServices Framework.

App policy Provides an example of how to use application-specific policy APIs. Apppolicies control specific features of a single app, compared to built-in policiesthat apply to all apps.

Bypass Unlock Illustrates how to program for the Bypass Idle Unlock feature.

Interaction Provides an example of how to interact with the BlackBerry Dynamics Libraryand use the Remote Settings API. Displays which BlackBerry Dynamics eventsare happening. This can be helpful when using BlackBerry Dynamics for thefirst time.

Greetings client/server Demonstrates how to write a client and server that use the BlackBerryDynamics Inter Container Communications (ICC) API. The ICC systemexchanges data securely between two BlackBerry Dynamics applicationsrunning on the same mobile device so that data is not compromised duringthe exchange.

 | Sample apps | 28

Sample app Description

Push channel Demonstrates how to use the BlackBerry Dynamics Push infrastructure,including how to control the connection, create channels, and send messagesin a loopback manner to the client. The Push Channel framework isa BlackBerry Dynamics feature used to receive real-time notifications from anapplication server.

Secure copy-cut-paste Compares the use of secured BlackBerry Dynamics UI text controls(GDTextView, GDEditText, GDAutoCompleteTextView, GDSearchView, GDWebView)and the corresponding default UI text controls. Text data is encrypted ordecrypted before copy or paste operations are performed.

For more information, see Securing cut-copy-paste on devices (Data LeakagePrevention, or DLP).

Secure SQL Demonstrates how to use the secure SQL database, showing how to add,edit, delete, and list contacts. All data stored in the secure SQL database isencrypted on the device by the BlackBerry Dynamics Runtime.

Skeleton Provides a basic skeleton application that you can use as a starting point forapplication development.

Wearable framework securestore

Demonstrates how to use the BlackBerry Dynamics SDK to create, manage,and access files stored in an app’s secure container. Both the file names andfile contents are encrypted, stored on the device, and can only be accessedwhen the BlackBerry Dynamics app is unlocked.

The secure store app consists of three sub-projects, and is best loadedinto Android Studio IDE:

• /handheld_app: Code specific to a BlackBerry Dynamics handheldapplication.

• /common: Code built into both the BlackBerry Dynamics handheldand BlackBerry Dynamics wearable applications.

• /wearable_app: Code specific to a BlackBerry Dynamics wearableapplication.

Note: Importing this sample app into Android Studio causes an errormessage that can be ignored. The application builds correctly despite theerror.

 | Sample apps | 29

Testing and troubleshooting

Automated test support library for AndroidThe BlackBerry Dynamics SDK for Android comes with an automated test support library. It's composed of sourcecode and documentation on its use.

See the installed directory libs/common/gd_automated_test_support. In addition use of the automatedtest support library is illustrated in the Sample apps.

Emulators and the rooted OS compliance policyIf the BlackBerry Dynamics compliance policy to check for a rooted OS is applied to a BlackBerry Dynamics appthat is running on a vanilla Android emulator, the emulator will wipe the BlackBerry Dynamics app. The defaultbehaviour for the compliance policy in BlackBerry UEM and in standalone Good Control is to wipe an app on arooted device, and the emulator is considered a rooted device.

This default behaviour is best for production service but interferes with development testing.

Recommendations for a development environment

• Use Enterprise Simulation mode for basic operations on the emulator. This requires no setup in themanagement console. For more information, see Using enterprise simulation mode.

• Use a new Android emulator configuration with minimum API Level 26 that includes a Google Play systemimage. This configuration is not considered a rooted device.

• In the management console, configure and assign a new policy set for development purposes with the rootdetection policy disabled.

Using enterprise simulation modeAlthough Enterprise Simulation mode isn't suitable for production deployment of your app, it is ideal duringdevelopment and for verifying proper execution and behavior when you migrate or convert existing Android appsto BlackBerry Dynamics.

In simulation mode, a valid activation key is not required to open the app because there is no directcommunication with BlackBerry Dynamics servers in your organization.

Important: Communication with the BlackBerry Dynamics 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 whichthe application is running.

In simulation mode your BlackBerry Dynamics apps are run on an Android virtual device or AVD that comes withthe Android SDK.

The Secure Storage, Secure Communication, and Push Channel APIs are all available in Enterprise Simulationmode. However, the communication APIs will not be able to connect to your organization's application serversthrough the BlackBerry Dynamics proxy infrastructure. You can make connections to your organization'sapplication servers if, for example, the AVD is running on a computer on your organization's LAN or VPN.

To enable simulation mode, whether you use an IDE or a text editor, you must change the following line in yourapplication’s settings.json file. The settings.json file is located in the ../assets/ folder of the appand must remain there

 | Testing and troubleshooting | 30

Change this... …to this

"GDLibraryMode":"GDEnterprise" "GDLibraryMode":"GDEnterpriseSimulation"

When GDLibraryMode is set to "GDLibraryMode":"GDEnterpriseSimulation", default enterpriseauthentication is invoked to open the application.

Note: Be sure to change the value of GDLibraryMode back when done testing the app before compiling it forproduction.

Behavioral effects of enterprise simulation

In Enterprise Simulation mode, the app behaves differently than during standard enterprise execution in thefollowing ways:

• The word [Simulated] appears in the BlackBerry Dynamics Runtime user interface.• Any email address and activation key (PIN) is accepted for enterprise activation.• No information is actually sent to BlackBerry Dynamics servers, including the email address and activation key.• The provisioning and policy setup flow is only simulated in the UI.• A hard-coded set of security and compliance policies is enforced operation. Authentication delegation policy is

not supported.• If you run an app built for enterprise simulation mode on a device and not an emulator, the app will be wiped.• If you try to change the mode from GDEnterprise to GDEnterpriseSimulation for an app that is already

installed on a device, it will be wiped.• Lost password recovery is not available.• Inter-container Communication (ICC) cannot be used, which means that the Shared Services Framework

cannot be used

Logging and diagnosticsThe processing activity of the BlackBerry Dynamics Runtime is logged by the runtime itself. The activity log iswritten to the BlackBerry Dynamics secure container on the device after deployment. You might be asked toprovide the log file to the BlackBerry Dynamics technical support team, but this is typically only necessary forcomplex support issues.

Log message categoriesMessages in the activity log are assigned to one of four categories:

• Errors: critical failures• Warnings: failures that arise but from which the BlackBerry Dynamics Runtime has recovered• Info: normal operational activity• Detailed: additional diagnostic information used for troubleshooting complex problems

You can configure the logging system to filter some or all messages. By default, only messages that belong to theErrors, Warnings, and Info categories are printed.

The logging locations on the IDE console and device container are configured differently and independently. Inprinciple, you control the console log and the BlackBerry UEM administrator controls the container log.

 | Testing and troubleshooting | 31

Configure logging in Good ControlYou can specify the message categories that are recorded in the container log file in the Good Controlmanagement console. To configure logging, you must be a Good Control administrator. Container logging can beset for a particular installation of the app provisioned for a specific user. Selective logging for the container is notsupported.

Changes that you make to container logging are effective immediately if the app is running and connected to theBlackBerry Dynamics infrastructure. Otherwise, changes are effective as soon as app does connect.

The app can export or upload the container log file using the BlackBerry Dynamics API. For more information,see the function definitions in the GDFileSystem class reference in the BlackBerry Dynamics SDK for iOS APIReference.

GDLogManager class for log uploadingYou can use the GDLogManager class that is included with the BlackBerry Dynamics SDK to monitor app logfile uploads that are initiated by end users. This class does not manage or display information about log uploadsinitiated by the BlackBerry UEM administrator's policies or explicit actions.

GDLogManager's displayed information and functions include the following:

• Size of whole upload• Amount of data uploaded so far• Events that indicate the following states:

• Upload completed• Upload abandoned or canceled• Upload suspended• Upload resumed after suspension

• Actions for managing a log upload:

• Cancel upload• Suspend upload• Resume upload

For more information, see GDLogManager in the BlackBerry Dynamics API reference.

When detailed logging is disabled by policy, calling any API in the GDLogManager class has no effect. It is a bestpractice to check the setting of this policy in the app configuration using the getApplicationConfig API. Ifdetailed logging is enabled, present the log upload progress UI or any other related UI.

GDDiagnostic APIThe BlackBerry Dynamics SDK includes an API that you can use to test connectivity to application servers andother diagnostic functions. See the discussion of the GDDiagnostic class in the BlackBerry Dynamics APIreference.

The GreetingsClient sample is delivered with the SDK to illustrate how to use GDDiagnostic.

Configure the adb consoleThe message categories printed to the adb console are configured in the settings object of the app. You can setlogging to be detailed or selective. Changes to the console logging configuration will be applied the next time thetarget is built and run. Changes made to console logging do not affect the container log.

 | Testing and troubleshooting | 32

Set detailed logging

To set a target’s activity logging configuration to print all messages, including those that belong to the Detailedcategory, complete the following steps:

1. Open the assets/settings.json file of the app.2. Add a GDConsoleLogger array attribute to the settings object, or change the existing attribute to a single

string element with a value of “GDFilterNone” as shown in context in the following snippet:

...{ "GDLibraryMode": "GDEnterprise", "GDApplicationID": "com.example.browser", "GDApplicationVersion": "1.0.0.0", "GDConsoleLogger": [ "GDFilterNone" ]}….

The console will now include all log messages the next time the target is built and run.

Set selective logging

1. Open the assets/settings.json file of the app.2. Add a GDConsoleLogger array attribute to the settings object, or change the existing attribute to one or more

of the categories defined in Log message categories as shown in context in the following snippet:

...{ "GDLibraryMode": "GDEnterprise", "GDApplicationID": "com.example.browser", "GDApplicationVersion": "1.0.0.0", "GDConsoleLogger": [ "GDFilterErrors_", "GDFilterWarnings_", "GDFilterInfo", "GDFilterDetailed" ]}...

Next time the target is built and run, the console will include all messages of the activities configured. Forexample, in the snippet above, warnings and errors are filtered out because an underscore character appendedto a category string omits it as a category. Thus, in the example, only log messages in the Info and Detailedcategories will be included.

Configure the container logContainer logging is enabled or disabled in the console. To configure logging, you must have administratorpermissions in the consoles. Container logging can be set for a particular installation of the app provisioned for aspecific user. Selective logging for the container is not supported.

Changes to container logging are applied immediately if the app is running and connected to the BlackBerryDynamics proxy infrastructure. Otherwise, changes are applied as soon as app does connect. Changes tocontainer logging have no effect on the adb console log.

 | Testing and troubleshooting | 33

An app can export or upload the container log using the BlackBerry Dynamics API. See theexportLogFileToDocumentsFolder() and uploadLogs() function definitions in the GDFileSystem classin the BlackBerry Dynamics API reference.

 | Testing and troubleshooting | 34

Readying your app for deployment: server setupYou want to test your app on a BlackBerry server before you deploy it into production. You need to becomefamiliar with how to setup and configure such a server. You have options available: either BlackBerry UEM or theolder Good Control.

Check with your IT or other department to see what test servers might already be available in your organization.

BlackBerry UEM preferred

BlackBerry UEM is the primary server configuration to test and deploy your app. 

If you upgrade from Good Control to BlackBerry UEM, you not only get to use the great feature set that GoodControl provides but you also get to take advantage of an enhanced feature set such as:

• Support for more policies for operating systems• Better app management• More container types• Improved administration and provisioning• Advanced connectivity and networking• Expanded compliance and integrity checking• Additional email, content, location, and certificate features• Access to BlackBerry Web Services APIs

For information on how to use BlackBerry UEM to manage BlackBerry Dynamics apps, see the BlackBerryUEM Administration Guide.

Standalone Good Control

The standalone Good Control server is also available, but BlackBerry encourages you to use BlackBerryUEM for your tests and deployment. For information about getting started with Good Control, see DeveloperBootstrap: Good Control Essentials.

Configuring library version complianceIn a compliance profile or compliance policy, an administrator can enable the BlackBerry Dynamics library versionverification compliance rule to specify an enforcement action if a BlackBerry Dynamics app is using a versionof the BlackBerry Dynamics library that is not permitted. The available enforcement actions are "Do not allowBlackBerry Dynamics apps to run" and "Delete BlackBerry Dynamics app data."

In previous releases of UEM, standalone Good Control, and the SDK, BlackBerry Dynamics apps could be blockedor deleted unintentionally if an app used a version of the library that was not available in the version list (forexample, a pre-release version of the SDK).

In UEM, by default the BlackBerry Dynamics library version verification compliance rule is not selected and allversions are permitted. An administrator can enable this option and select specific versions to disallow.

In standalone Good Control 5.0, the following options have been added to this compliance rule:

• Allow all BlackBerry Dynamics library versions: Apps that use any version of the SDK library are allowed. If thisoption is enabled, the administrator cannot select specific versions to allow or disallow. By default, this optionis disabled.

 | Readying your app for deployment: server setup | 35

• Allow unlisted BlackBerry Dynamics library versions: Apps that use versions of the SDK library that are newerthan the latest version listed in the compliance rule are allowed. The administrator can still allow or disallowspecific versions of the library from the version list. By default, this option is enabled.

Consult with the UEM or Good Control administrator to ensure that the compliance rule is configuredappropriately.

Setting allowBackup=false for production apps, use BackupHelperYou can back up your BlackBerry Dynamics-based apps while you are developing them, but for the productionbuild of your apps, you should set allowBackup=false in AndroidManifest.xml to prevent backups. This is tokeep your data secure. For example, after restoring a backup made to another device, your app containers mightbe in an unlocked state, which exposes the data to risk, or the app data might not be available at all.

BlackBerry Dynamics backup and restore uses the Android BackupHelper model to backup data into the cloud.Our SecureStore sample app (see Sample apps) demonstrates the code and AndroidManifest.xml changesrequired in the app to make this happen. You should use the BackupHelper because it is potentially more securethan other mechanisms.

Build with ProGuard in productionIn accordance with industry guidelines, after your app is fully tested and ready to deploy, you should use anobfuscation tool as part of your formal build and release process.

Multiple obfuscation tools are currently available. To ensure correct BlackBerry Dynamics operation andperformance, however, they need to be configured so as not to obfuscate key parts of the BlackBerry DynamicsSDK library. Below is a configuration that can be used as the basis for any application. Using ProGuard isrecommended because it is the default obfuscation tool for Android. If you are using an alternative tool, the rulesin the appendix should be adapted for that tool.

The BlackBerry Dynamics SDK uses Platform APIs, some of which rely on versions of above the minimumsupported API Level. A target SDK below the latest API level might throw warnings about the newer APIs, because</li> cannot find them in the underlying Platform JAR. The BlackBerry Dynamics SDK now ensures the appropriateruntime checks are made before it attempts to use any such API. You can ignore warnings about APIs that aren'tfound in BlackBerry Dynamics SDK classes with -dontwarn com.good.gd as shown on the final line in theexample below.

The snippet below is an </li>.cfg file that works for any BlackBerry Dynamics SDK app.

... #### General -optimizationpasses 5 -dontusemixedcaseclassnames -dontskipnonpubliclibraryclasses -dontpreverify -verbose -optimizations !code/simplification/arithmetic,!field/*,!class/merging/* -keepattributes Exceptions -keepclassmembers enum * { public static **[] values(); public static ** valueOf(java.lang.String); } ## Rules for BlackBerry Dynamics and its included library components -keep class com.good.gd.** {

 | Readying your app for deployment: server setup | 36

<methods>; <fields>; } -keep class com.good.gt.** { <methods>; <fields>; } -keep class org.apache.http.** { <methods>; <fields>; }-dontwarn com.good.gd.**-dontwarn com.good.gt.** ...

 | Readying your app for deployment: server setup | 37

Details of support for client certificates

BlackBerry Dynamics SDK support for personal certificates (PKCS12or PKI certs)The BlackBerry Dynamics SDK has been enhanced to support personal certificates for authentication ofapplications at runtime.

No programming is required by the BlackBerry developer on any of the client BlackBerry Dynamics SDK platformsto take advantage of this feature. All operations are carried about by the BlackBerry Dynamics Runtime. Theapp must use the BlackBerry Dynamics Secure Communication Networking APIs provided in prior releases, theemployee’s account must be correctly configured, and the GC must be the 2.0.xx.yy release later.

An enterprise can deploy corporate services requiring two-way SSL/TLS mutual authentication in order toauthenticate their employees. Through the enterprise, the employee may be issued or otherwise obtain apassword protected Personal Information Exchange file (PKCS12/p12/pfx) containing a SSL/TLS client certificateand private key required by such services for authentication purposes. This file may be installed on variousmachines and devices, including BlackBerry Dynamics apps, so that access can be granted to these services.

Setup in Good Control

Requirements of the certificates themselves are described in Certificate requirements and troubleshooting.

To deploy Personal Information Exchange files with BlackBerry Dynamics apps, the following steps must be takento configure the GC and employee’s account. For more information, see the Good Control and Good Proxy AdminHelp.

• After the GC is installed, an administrator may choose to extend the default 24-hour period that an employee’sprotected Personal Information Exchange file shall be cached by the GC server.

• An administrator must add all BlackBerry Dynamics apps that access services requiring client authenticationto the Certificates -> App Usage tab,

• An administrator must enable Use PKCS12 Certificate Management in the employee's security policy,• An administrator or employee must upload their Personal Information Exchange files to the Certificates tab.

Behavior of personal certificates in the app

After the employee activates a BlackBerry Dynamics app enabled for access to server resources requiring clientauthentication, it receives their Personal Information Exchange files, provided they are still cached on the GC. Foreach file, the employee is asked to enter their password protecting the file contents, so the identification materialcan be installed. Once installed, provided the identification is correct, the BlackBerry Dynamics app is grantedaccess to server resources requiring two-way SSL/TLS mutual authentication when connecting.

If there is more than one Personal Information Exchange file required per employee, the BlackBerry DynamicsRuntime ensures that the certificate chosen to send to the server meets all of the following criteria:

1. Only client certificates suitable for SSL/TLS client authentication are eligible for sending to the server. That is,certificates that have no Key Usage and Extended Key Usage, or Key Usage contains “Digital Signature" or "KeyAgreement”, or Extended Key Usage contain "TLS Web Client Authentication”, and those whose Key Usagesand Extended Key Usages do not contradict allowances for SSL/TLS client auth.

2. If the server advertises the client certificate authority in the SSL/TLS handshake, only client certificates issuedby these authorities will be considered

3. Only current client certificates will be considered (that is, certificates that have not expired or are not yet valid)

 | Details of support for client certificates | 38

Usually this is sufficient to identify the correct client certificate, but if there is still more than one certificatemeeting all of the above criteria then the first one is used. If the certificate chosen is not the desired one, theadministrator or employee can manage this by removing the undesired client certificate from Good Control. Theadministrator can also increase the chance of success by ensuring the server is configured to advertise the clientcertificate authority in the SSL/TLS handshake.

Certificate requirements and troubleshootingMake sure your certificates conform to these requirements:

• Certificates must be in PKCS 12 format: Certificate Authority (CA), public key, and private key, all in the samefile.

• The PKCS12 file must end with the extension .p12 or .pfx.• The PKCS 12 file must be password-protected.

There are many sources of certificates:

• Your own internal certification authority (CA)• A well-known public CA• Tools from the Internet, such as OpenSSL's keytool command. For example, the following is sufficient to

generate a PKCS 12 certificate that is usable with Good Control; substitute your own values for alias thekeystore name and the keystore password. If in doubt consult information on the Internet about all thepossible options on the keytool command:

keytool -genkeypair -alias good123 -keystore good123.pfx -storepass good123 -validity 365 -keyalg RSA -keysize 2048 -storetype pkcs12

Beware of weak ciphers from export

Personal Information Exchange files are encrypted, and therefore must be encrypted with FIPS-strength ciphers ifto be used when FIPS is enabled on the employee’s security policy.

For their own maximum interoperability with other systems, it is common for third-party applications, for examplethe macOS keychain, to export identity material (credentials) using weak ciphers.

The administrator or employee can use a tool such as the OpenSSL command line to re-encrypt the file with aFIPS-strength cipher like so, which re-encrypts with the AES-128-CBC cipher:

openssl pkcs12 -in weak.p12 -nodes -out decrypted.pem <enter password> openssl pkcs12 -export -in decrypted.pem -keypbe AES-128-CBC -certpbe AES-128-CBC -out strong.p12 <enter password> rm decrypted.pem

Client certificate sharing among BlackBerry Dynamics-basedapplicationsThe BlackBerry Dynamics SDK supports the "sharing" of a single client certificate among all BlackBerry Dynamics-based applications for an end-user.

If the security policy for authentication via client certificates is enabled in Good Control or UEM and one or moreclient certificates have been uploaded to the server, those certificates are used for user authentication by allBlackBerry Dynamics-based applications on the user's device.

 | Details of support for client certificates | 39

• No programming is required.• Client certificates must be enabled in Good Control or UEM and at least one PKCS 12 certificate for a user

must be uploaded to server.

Kerberos PKINIT: User authentication with PKI certificatesThe BlackBerry Dynamics SDK supports Kerberos PKINIT for user authentication using PKI certificates.

No programming is required to use Kerberos PKINIT.

Important: Kerberos PKINIT is distinct from Kerberos Constrained Delegation (KCD). PKINIT relies on the KeyDistribution Center (KDC), which should not be confused with "KCD".

Kerberos PKINIT Kerberos Constrained Delegation

Kerberos PKINIT authentication is between theBlackBerry Dynamics app and the Windows KeyDistribution Center (KDC), which communicatedirectly, and user authentication is based oncertificates issued by Microsoft Active DirectoryCertificate Services.

Note: For PKINIT, Kerberos Constrained Delegationmust not be enabled.

If Kerberos Constrained Delegation has beenconfigured, a BlackBerry Dynamics app does not useKerberos PKINIT to access the defined KCD realms.Instead, when Kerberos Constrained Delegation isused, a trust relation has been previously establishedbetween BlackBerry Control and the Key DistributionCenter, and BlackBerry Control communicateswith the service on behalf of the app. KerberosConstrained Delegation takes precedence overKerberos PKINIT, even if the user has a validcertificate.

Key requirements for PKINIT

Organizations that want to use Kerberos for BlackBerry Dynamics apps must make sure the followingrequirements are met.

Servers

• Kerberos Constrained Delegation must not be enabled.• Windows Key Distribution Center (KDC) services for KDC server certificates issued by a Certificate Authority

(CA) via the Active Directory Certificate Services must come only from the following Windows Server versions.No other server versions are supported.

• Internet Information Server with Windows Server 2008 R2• Internet Information Server with Windows Server 2012 R2

• In BlackBerry Control:

• The KDC hosts must be in the Allowed Domains of the Connectivity Profile applied to the affected users'policy sets.

• Valid KDC service certificates must be located either in the BlackBerry Dynamics Certificate Store or theDevice Certificate Store.

 | Details of support for client certificates | 40

Client certificates

• The minimum keylength for the certificates must be 2,048 bytes.• Client certificates must include the User Principal Name (UPN) (for example, user@domain.com) in the Subject

Alternative Name (SAN) of object ID (OID) szOID_NT_PRINCIPAL_NAME 1.3.6.1.4.1.311.20.2.3, as specified byMicrosoft. See Microsoft Support: Object IDs associated with Microsoft cryptography.

• The domain of the UPN must match the name of the realm of the Windows Key Distribution Center (KDC)service.

• The Extended Key Usage (EKU) property of the certificate must be Microsoft Smart Card logon(1.3.6.1.4.1.311.20.2.2).

• Certificates must be valid. Validate them against the servers listed above.

Client applications

• In BlackBerry Work, to allow the use of client certificates, you must enable the useEASAuthCert setting.• Apps must not send any password in the HTTP/HTTPS request.• Apps must either set the HTTP/HTTPS header WWW-Authenticate: Negotiate, or not set any

authorization method in the HTTP or HTTPS request, to which the server has responded with 401WWWAuthenticate: Negotiate. For more information, see SPNEGO-based Kerberos and NTLM HTTPAuthentication in Microsoft Windows.

Key points

The following are key points to note when integrating BlackBerry Dynamics and Kerberos infrastructure:

• The KDC host must be in the Allowed Domains of the Connectivity Profile applied to the affected users' policysets in BlackBerry Control.

• The KDC host must be listening on TCP port 88 (Kerberos default port).• BlackBerry Dynamics does not support KDC over UDP.• BlackBerry Dynamics does not use Domain Name System (DNS) records such as SRV, CNAME, or TXT to locate

the correct KDC. That is, the KDC must have an A record (IPv4) or AAAA record (IPv6) in your DNS.• BlackBerry Dynamics does not use Kerberos configuration files (such as krb5.conf) to locate the correct

KDC.• The KDC can refer the client to another KDC host. BlackBerry Dynamics will follow the referral, as long as the

KDC host that is referred to can be reached by BlackBerry Dynamics. This setting is defined in the AllowedDomains of the Connectivity Profile that is applied to the affected users' policy sets in BlackBerry Control.

• The KDC can obtain the TGT transparently to BlackBerry Dynamics from another KDC host.

Background on PKINIT, with FAQ

Consider the interactions in this KDC diagram.

Kerberos PKINIT authentication requires the client (in the drawing, the human John, running a BlackBerryDynamics-enabled application) to be able to contact:

• When initializing the user session, the user's Key Distribution Center (KDC) Authentication Service (AS) toobtain a Ticket-Granting Ticket (TGT)

• When establishing a connection to a resource (in the drawing, Service "A"), the resource’s KDC Ticket-GrantingService (TGS)

In a large organization users and resources might belong to various realms and there may be many KDCs, so howdoes BlackBerry Dynamics find the right one?

 | Details of support for client certificates | 41

1. How does the client locate the user’s KDC Authentication Service when initializing the user’s session?

• Password-based authentication

The realm in the user name must contain the host name of the KDC AS. For example:

User: user@MY.REALM.COM

Password: myPassword• Certificate-based authentication: This is PKINIT.

The realm in the UPN of the user’s certificate must contain the host name of the KDC AS. For example:

UPN (OID 1.3.6.1.4.1.311.20.2.3): user@MY.REALM.COM

2. How does the client locate the resource's KDC Ticket-Granting Service (TGS) when retrieving the resource?

BlackBerry Dynamics attempts to obtain a TGS from the host in the domain of the resources URL. For example:

URL: http://resource.myrealm.com/index.html

The client will connect to KDC TGS running on host myrealm.com on TCP port 88.

 | Details of support for client certificates | 42

Legal notice©2018 BlackBerry Limited. Trademarks, including but not limited to BLACKBERRY, BBM, BES, EMBLEM Design,ATHOC, MOVIRTU and SECUSMART are the trademarks or registered trademarks of BlackBerry Limited, itssubsidiaries and/or affiliates, used under license, and the exclusive rights to such trademarks are expresslyreserved. All other trademarks are the property of their respective owners.

Android, Android Wear, Android Studio, Android SDK, Google, and Google Drive are trademarks of Google Inc. Samsung, Samsung Galaxy Note, Samsung Pass, Samsung Pass SDK and S5 are trademarks of SamsungElectronics Co., Ltd. Gradle is a trademark of Gradle Inc. Apache is a trademark of The Apache SoftwareFoundation. RSA is a trademark of RSA Security. Microsoft, Active Directory, and Windows are either registeredtrademarks or trademarks of Microsoft Corporation in the United States and/or other countries. Xamarin is atrademark of Xamarin Inc. GitHub is a trademark of GitHub Inc. All other trademarks are the property of theirrespective owners.

This documentation including all documentation incorporated by reference herein such as documentationprovided or made available on the BlackBerry website provided or made accessible "AS IS" and "AS AVAILABLE"and without condition, endorsement, guarantee, representation, or warranty of any kind by BlackBerry Limited andits affiliated companies ("BlackBerry") and BlackBerry assumes no responsibility for any typographical, technical,or other inaccuracies, errors, or omissions in this documentation. In order to protect BlackBerry proprietary andconfidential information and/or trade secrets, this documentation may describe some aspects of BlackBerrytechnology in generalized terms. BlackBerry reserves the right to periodically change information that is containedin this documentation; however, BlackBerry makes no commitment to provide any such changes, updates,enhancements, or other additions to this documentation to you in a timely manner or at all.

This documentation might contain references to third-party sources of information, hardware or software,products or services including components and content such as content protected by copyright and/or third-party websites (collectively the "Third Party Products and Services"). BlackBerry does not control, and is notresponsible for, any Third Party Products and Services including, without limitation the content, accuracy,copyright compliance, compatibility, performance, trustworthiness, legality, decency, links, or any other aspectof Third Party Products and Services. The inclusion of a reference to Third Party Products and Services in thisdocumentation does not imply endorsement by BlackBerry of the Third Party Products and Services or the thirdparty in any way.

EXCEPT TO THE EXTENT SPECIFICALLY PROHIBITED BY APPLICABLE LAW IN YOUR JURISDICTION, ALLCONDITIONS, ENDORSEMENTS, GUARANTEES, REPRESENTATIONS, OR WARRANTIES OF ANY KIND, EXPRESSOR IMPLIED, INCLUDING WITHOUT LIMITATION, ANY CONDITIONS, ENDORSEMENTS, GUARANTEES,REPRESENTATIONS OR WARRANTIES OF DURABILITY, FITNESS FOR A PARTICULAR PURPOSE OR USE,MERCHANTABILITY, MERCHANTABLE QUALITY, NON-INFRINGEMENT, SATISFACTORY QUALITY, OR TITLE, ORARISING FROM A STATUTE OR CUSTOM OR A COURSE OF DEALING OR USAGE OF TRADE, OR RELATED TO THEDOCUMENTATION OR ITS USE, OR PERFORMANCE OR NON-PERFORMANCE OF ANY SOFTWARE, HARDWARE,SERVICE, OR ANY THIRD PARTY PRODUCTS AND SERVICES REFERENCED HEREIN, ARE HEREBY EXCLUDED.YOU MAY ALSO HAVE OTHER RIGHTS THAT VARY BY STATE OR PROVINCE. SOME JURISDICTIONS MAYNOT ALLOW THE EXCLUSION OR LIMITATION OF IMPLIED WARRANTIES AND CONDITIONS. TO THE EXTENTPERMITTED BY LAW, ANY IMPLIED WARRANTIES OR CONDITIONS RELATING TO THE DOCUMENTATION TOTHE EXTENT THEY CANNOT BE EXCLUDED AS SET OUT ABOVE, BUT CAN BE LIMITED, ARE HEREBY LIMITED TONINETY (90) DAYS FROM THE DATE YOU FIRST ACQUIRED THE DOCUMENTATION OR THE ITEM THAT IS THESUBJECT OF THE CLAIM.

TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW IN YOUR JURISDICTION, IN NO EVENT SHALLBLACKBERRY BE LIABLE FOR ANY TYPE OF DAMAGES RELATED TO THIS DOCUMENTATION OR ITS USE,OR PERFORMANCE OR NON-PERFORMANCE OF ANY SOFTWARE, HARDWARE, SERVICE, OR ANY THIRDPARTY PRODUCTS AND SERVICES REFERENCED HEREIN INCLUDING WITHOUT LIMITATION ANY OF THEFOLLOWING DAMAGES: DIRECT, CONSEQUENTIAL, EXEMPLARY, INCIDENTAL, INDIRECT, SPECIAL, PUNITIVE,OR AGGRAVATED DAMAGES, DAMAGES FOR LOSS OF PROFITS OR REVENUES, FAILURE TO REALIZE ANY

 | Legal notice | 43

EXPECTED SAVINGS, BUSINESS INTERRUPTION, LOSS OF BUSINESS INFORMATION, LOSS OF BUSINESSOPPORTUNITY, OR CORRUPTION OR LOSS OF DATA, FAILURES TO TRANSMIT OR RECEIVE ANY DATA,PROBLEMS ASSOCIATED WITH ANY APPLICATIONS USED IN CONJUNCTION WITH BLACKBERRY PRODUCTS ORSERVICES, DOWNTIME COSTS, LOSS OF THE USE OF BLACKBERRY PRODUCTS OR SERVICES OR ANY PORTIONTHEREOF OR OF ANY AIRTIME SERVICES, COST OF SUBSTITUTE GOODS, COSTS OF COVER, FACILITIES ORSERVICES, COST OF CAPITAL, OR OTHER SIMILAR PECUNIARY LOSSES, WHETHER OR NOT SUCH DAMAGESWERE FORESEEN OR UNFORESEEN, AND EVEN IF BLACKBERRY HAS BEEN ADVISED OF THE POSSIBILITY OFSUCH DAMAGES.

TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW IN YOUR JURISDICTION, BLACKBERRY SHALLHAVE NO OTHER OBLIGATION, DUTY, OR LIABILITY WHATSOEVER IN CONTRACT, TORT, OR OTHERWISE TOYOU INCLUDING ANY LIABILITY FOR NEGLIGENCE OR STRICT LIABILITY.

THE LIMITATIONS, EXCLUSIONS, AND DISCLAIMERS HEREIN SHALL APPLY: (A) IRRESPECTIVE OF THE NATUREOF THE CAUSE OF ACTION, DEMAND, OR ACTION BY YOU INCLUDING BUT NOT LIMITED TO BREACH OFCONTRACT, NEGLIGENCE, TORT, STRICT LIABILITY OR ANY OTHER LEGAL THEORY AND SHALL SURVIVE AFUNDAMENTAL BREACH OR BREACHES OR THE FAILURE OF THE ESSENTIAL PURPOSE OF THIS AGREEMENTOR OF ANY REMEDY CONTAINED HEREIN; AND (B) TO BLACKBERRY AND ITS AFFILIATED COMPANIES, THEIRSUCCESSORS, ASSIGNS, AGENTS, SUPPLIERS (INCLUDING AIRTIME SERVICE PROVIDERS), AUTHORIZEDBLACKBERRY DISTRIBUTORS (ALSO INCLUDING AIRTIME SERVICE PROVIDERS) AND THEIR RESPECTIVEDIRECTORS, EMPLOYEES, AND INDEPENDENT CONTRACTORS.

IN ADDITION TO THE LIMITATIONS AND EXCLUSIONS SET OUT ABOVE, IN NO EVENT SHALL ANY DIRECTOR,EMPLOYEE, AGENT, DISTRIBUTOR, SUPPLIER, INDEPENDENT CONTRACTOR OF BLACKBERRY OR ANYAFFILIATES OF BLACKBERRY HAVE ANY LIABILITY ARISING FROM OR RELATED TO THE DOCUMENTATION.

Prior to subscribing for, installing, or using any Third Party Products and Services, it is your responsibility toensure that your airtime service provider has agreed to support all of their features. Some airtime serviceproviders might not offer Internet browsing functionality with a subscription to the BlackBerry® Internet Service.Check with your service provider for availability, roaming arrangements, service plans and features. Installationor use of Third Party Products and Services with BlackBerry's products and services may require one or morepatent, trademark, copyright, or other licenses in order to avoid infringement or violation of third party rights. Youare solely responsible for determining whether to use Third Party Products and Services and if any third partylicenses are required to do so. If required you are responsible for acquiring them. You should not install or useThird Party Products and Services until all necessary licenses have been acquired. Any Third Party Products andServices that are provided with BlackBerry's products and services are provided as a convenience to you and areprovided "AS IS" with no express or implied conditions, endorsements, guarantees, representations, or warrantiesof any kind by BlackBerry and BlackBerry assumes no liability whatsoever, in relation thereto. Your use of ThirdParty Products and Services shall be governed by and subject to you agreeing to the terms of separate licensesand other agreements applicable thereto with third parties, except to the extent expressly covered by a license orother agreement with BlackBerry.

The terms of use of any BlackBerry product or service are set out in a separate license or other agreement withBlackBerry applicable thereto. NOTHING IN THIS DOCUMENTATION IS INTENDED TO SUPERSEDE ANY EXPRESSWRITTEN AGREEMENTS OR WARRANTIES PROVIDED BY BLACKBERRY FOR PORTIONS OF ANY BLACKBERRYPRODUCT OR SERVICE OTHER THAN THIS DOCUMENTATION.

BlackBerry Enterprise Software incorporates certain third-party software. The license and copyright informationassociated with this software is available at http://worldwide.blackberry.com/legal/thirdpartysoftware.jsp.

BlackBerry Limited2200 University Avenue EastWaterloo, OntarioCanada N2K 0A7

 | Legal notice | 44

BlackBerry UK Limited200 Bath RoadSlough, Berkshire SL1 3XEUnited Kingdom

Published in Canada

 | Legal notice | 45