• BlackBerry Dynamics
  • Runtime library for Android applications
  • 9.1.0.122
Build-Time Configuration

BlackBerry Dynamics utilizes a number of capabilities of the operating system that require build-time configuration. Some build-time configuration is therefore mandatory for all applications.

Component Definitions

A number of component definitions are mandatory for the AndroidManifest.xml files of all applications. These definitions are all present in the manifest of the BlackBerry Dynamics runtime library project, which is installed as part of the SDK for Android. The definitions can be included from the library project into an application project by using automatic manifest merging. This can be enabled in the project properties file of the application by adding the following line:

manifestmerger.enabled=true

Some earlier versions of the BlackBerry Dynamics SDK for Android didn't support automatic manifest merging. The build-time configuration of applications built with one of those earlier versions can generally be simplified for building with the current version.

Upgrading to automatic manifest merging

Some earlier versions of the BlackBerry Dynamics SDK for Android did not support automatic manifest merging. Applications built with these versions will have:

  • Definitions of a number of BlackBerry Dynamics elements in the manifest file.
  • Extra Android permissions that are required by the BlackBerry Dynamics runtime in the manifest file.
  • Source code for an ICC receiving activity class.

All these elements can now be removed unless the application was already registered as a BlackBerry Dynamics AppKinetics™ service provider, and its registration cannot be changed. In that case, there still has to be an ICC receiving activity class in the source code, and a corresponding activity in the manifest file. The class must now be an empty subclass of the GDIccReceivingActivity class. See the GDIccReceivingActivity reference documentation for details and code snippets.

See under Service Provider Requirements in the icc package reference for details of service provider registration.

Event Receiver Check

By default, the BlackBerry Dynamics runtime checks that there is a GDStateListener or GDAppEventListener event receiver when an authorize method such as GDAndroid.activityInit is called. If there isn't, the runtime will throw an error and the program will terminate. This check must be switched off in the case that the application doesn't implement the above interfaces and instead uses the GDStateAction interface to monitor authorization.

The event receiver check can be turned off, as follows.

  1. Create a com.blackberry.dynamics.settings.json file in the assets/ folder of the application. (Note that this is a different name to settings.json which is used for other BlackBerry Dynamics settings.)
  2. Add an attribute CheckEventReceiver and set its value to false, as shown in the example below.

Example com.blackberry.dynamics.settings.json file that switches off the event receiver check:

{
"CheckEventReceiver": false
}
See also
GDStateAction class reference.

Run-Time Integrity Checking

The BlackBerry Dynamics runtime checks its own binary integrity when it runs. This is a function of the BlackBerry Dynamics runtime library, and is required as part of compliance with Federal Information Processing Standards (FIPS). No special build-time configuration is needed to switch on run-time integrity checking in a BlackBerry Dynamics for Android application.

System Permissions

Requirements in previous runtime versions

The BlackBerry Dynamics runtime version 6.1 and earlier had a requirement on the following Android system permissions:

  • Read the telephone state (READ_PHONE_STATE). Information that is only available to applications that have been granted this system permission is utilised to identify the Android device to the BlackBerry Dynamics infrastructure.

Applications that target, and are running on devices at, API level 23 or higher prompted the user to grant the above permissions. The prompt was issued by the BlackBerry Dynamics runtime, without reference to the application code.

In BlackBerry Dynamics runtime version 6.1, applications could ‘opt out’ of this behaviour and thus the runtime would not show the prompt or have access to read the phone state.

The Request Permissions functionality was turned off, as follows.

  1. Create a com.blackberry.dynamics.settings.json file in the assets/ folder of the application. (Note that this is a different name to settings.json which is used for other BlackBerry Dynamics settings.)
  2. Add an attribute Request_READ_PHONE_STATE and set its value to false, as shown in the example below.

Current requirements

From BlackBerry Dynamics runtime version 7.0 the default has been changed such that the runtime will no longer request to read the telephone state. Now if an application requires this state it will have to request it in the normal way.

See also
System Permissions API Guide on the android.com site.

Code Obfuscation Configuration

Code obfuscation tools like Proguard are commonly used to protect the source code of Android applications. If an obfuscation tool is in use when building a BlackBerry Dynamics application, then it must be configured to protect the code in a way that is compatible with the requirements of the BlackBerry Dynamics runtime library. The sample applications that are installed with the the BlackBerry Dynamics SDK for Android all include a Proguard configuration file, which can be used as an example. See also the following example, for the Proguard tool.

Sample code obfuscation configuration

#
# General Rules
# The following rules represent the best practice for BlackBerry Dynamics
# applications.

-optimizationpasses 5
-dontusemixedcaseclassnames
-dontskipnonpubliclibraryclasses
-dontpreverify
-verbose
-optimizations !code/simplification/arithmetic,!field/*,!class/merging/*

-keep public class * extends android.app.Activity
-keep public class * extends android.app.Application
-keep public class * extends android.app.Service
-keep public class * extends android.content.BroadcastReceiver
-keep public class * extends android.content.ContentProvider
-keep public class * extends android.app.backup.BackupAgentHelper
-keep public class * extends android.preference.Preference

-keepclasseswithmembers,includedescriptorclasses class * {
    native <methods>;
}

-keepclasseswithmembers class * {
    public <init>(android.content.Context, android.util.AttributeSet);
}

-keepclasseswithmembers class * {
    public <init>(android.content.Context, android.util.AttributeSet, int);
}

-keepclassmembers class * extends android.app.Activity {
   public void *(android.view.View);
}

-keepclassmembers enum * {
    public static **[] values();
    public static ** valueOf(java.lang.String);
}

-keep class * implements android.os.Parcelable {
  public static final android.os.Parcelable$Creator *;
}

#
# Necessary Configurations
# The following configuration would be necessary for a BlackBerry Dynamics
# application to execute. Some configurations are necessary for the runtime
# library itself, others for library components that it includes.

-keepnames,includedescriptorclasses public class com.good.gd.** { *; }
-keepnames,includedescriptorclasses public class com.good.gt.** { *; }
-keepnames,includedescriptorclasses public class com.blackberry.attestation.** { *; }

-keep class **.ndkproxy.** {  *; }

-keep public class com.good.gd.GDIccReceivingActivity
-keep public class com.good.gd.service.GDService
-keep public class com.good.gd.service.GDIccService
-keep public class com.good.gd.ui.GDInternalActivity
-keep public class com.good.gd.ui.dialogs.GDDialogActivity
-keep public class com.good.gd.ui.subcontainer_activationui.GTWearActivationUIActivity
-keep public class com.good.gt.wearsupport.GTWearInterDeviceListenService
-keep public class com.android.vending.licensing.ILicensingService

-keepclassmembers public class com.good.gd.GDServiceDetail,
                               com.good.gd.GDServiceProvider { *; }

# There are some APIs of which the BlackBerry Dynamics runtime will make use
# only when the application is running in an environment that supports the
# required Android API level. The following configurations suppress these warnings.

-dontwarn com.google.android.gms.**

-dontwarn com.good.gd.**
-dontwarn com.good.gt.**
-dontwarn com.good.gt.wearsupport.**

There are a number of general rules that are best practice for BlackBerry Dynamics applications. There are also a number of configurations without which a BlackBerry Dynamics application cannot execute.