GDAndroid Class Reference

BlackBerry Dynamics runtime object interface, including authorization. More...

Description

This class represents the application's connection to its embedded BlackBerry Dynamics runtime instance, and hence to the wider BlackBerry Dynamics platform infrastructure.

The programming interface includes a number of methods that the application must call at particular points in the application execution cycle. The application must also implement a handler for events dispatched from this interface. Calling the methods, and handling the events correctly, ensures compliance with enterprise security policies. This programming interface also includes a number of miscellaneous methods for various purposes, such as setting a custom logo for display in the BlackBerry Dynamics user interface.

The application must initialize the runtime object, using this programming interface, prior to using any other BlackBerry Dynamics interface. Initialization will only succeed if the end user has been set up in the enterprise BlackBerry Dynamics management console, and is entitled to use the application.

The user's entitlement to the application may later be revoked or temporarily withdrawn. For example, temporary withdrawal may take place if the user is inactive for a period of time. In either case, the application will be notified with an event or callback from this interface.

See also

System administration tasks

Manuals page for the BlackBerry Dynamics enterprise servers for the Platform Overview.

BlackBerry Dynamics Platform Connection

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

• Call authorize, which is direct initiation.
• Call activityInit, which is indirect initiation.

An application can use only direct or indirect authorization initiation, not both. The direct and indirect authorization initiation mechanisms each require different implementations in the application code. The mechanisms also place different restrictions on classes in the application user interface. See the Application User Interface Restrictions page for details.

Authorization generally includes establishing a data connection to the BlackBerry Dynamics proxy infrastructure, and hence to the enterprise that set up the end user entitlement. In addition, authorization will also include any necessary registration of the device, at the BlackBerry Dynamics Network Operation Center (infrastructure activation), and at the enterprise (enterprise activation). See under Activation, below, for more details.

Authorization may include user interaction, see the documentation of the authorize method, below, for details. All user interaction that is part of authorization takes place in a user interface that is built into the BlackBerry Dynamics runtime library, not part of the application.

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

Further changes to the authorization state can take place, and are notified to the application in the same way. See under Authorization State, below.

See also

Enterprise Simulation mode for instructions on building an application to run in a special limited mode in which authorization with the enterprise is only simulated.

Network Operation Center server addresses on the application developer portal, for IP address and port number details of the BlackBerry Dynamics Network Operation Center services.

Authorization State

The BlackBerry Dynamics runtime maintains the authorization state of the application. The programming interfaces that can be utilized by the application depend on its current authorization state.

The initial state of the application when it starts is not authorized. In this state the application can utilize the authorization processing initiation interface but cannot utilize any principal interfaces, such as secure store access and secure communication.

After authorization has been initiated and has succeeded, the application enters the authorized state. The principal interfaces can then be utilized.

Authorization of the end user may be temporarily withdrawn, in which case the application enters the locked state. This would happen when, for example, the user doesn't interact with the application for an extended period and the enterprise inactivity time out expires. Note that the authorization of the application itself has not been withdrawn in this state, only the authorization of the end user to access the application's data.
In the locked state, the BlackBerry Dynamics runtime superimposes an unlock screen on the application user interface to prevent the user from interacting with it or viewing its data. Note that the runtime doesn't block the whole device user interface, which means that native notification features and other ancillary mechanisms, such as widgets, could still be utilized by the application. The application mustn't cause sensitive enterprise data to be displayed through these features and mechanisms when in the locked state.
The application can continue to utilize the principal BlackBerry Dynamics interfaces, in the background.

After a temporary withdrawal ends, the application returns to the authorized state. This would happen when, for example, the user enters their security password in the unlock screen.

Authorization may also be permanently withdrawn, in which case the application enters the wiped state. This would happen when, for example, the end user's entitlement to the application is removed by the enterprise administrator. In the wiped state, the application cannot utilize the principal BlackBerry Dynamics interfaces. Attempting to do so will result in an exception or error being thrown.

Transitions of the authorization state are notified to the application by the BlackBerry Dynamics runtime. There are two interfaces for receiving notifications:

• GDStateListener provides simple state transition notifications. One of a number of callback methods in the application code is invoked by the runtime.
• GDAppEventListener provides detailed information. A GDAppEvent object with a number of attributes is dispatched from the runtime.

The authorization states and their corresponding callbacks are listed in the following table.

State	Description	GDStateListener callback	GDAppEvent type value
Not authorized	Initial state. The application can initiate authorization, but cannot utilize the principal interfaces.
Authorized	Either the user has just been authorized to access the application, following authorization processing, or a condition that caused authorization to be withdrawn has been cleared. The application can utilize the principal interfaces.	onAuthorized	GDAppEventAuthorized
Locked	Authorization of the user has been temporarily withdrawn, for example due to inactivity. User interaction is blocked. The application can still utilize the principal interfaces.	onLocked	GDAppEventNotAuthorized
Wiped	Authorization of the user has been permanently withdrawn, for example due to violation of an enterprise policy for which the enforcement action is to wipe the secure container. The application cannot use any interfaces.	onWiped	GDAppEventNotAuthorized This is the same event type as the Locked state transition event.

The transitions in the above table are also shown in the Authorization state transition diagram.

The BlackBerry Dynamics runtime user interface includes all the necessary screens and messages to inform the user of the authorization state. The application code needs only to ensure:

• That it doesn't bypass the runtime user interface.
• That it doesn't attempt to access the principal interfaces prior to authorization.
• That it doesn't attempt to access the principal interfaces after the authorization state has changed to wiped.

An authorized application may change an authorization state to 'locked' and prompt the user to reauthenticate by using Reauthenticate .

Authorization State Transition Notification Interfaces

There are a number of mechanisms for receiving notification of transitions in the authorization state.

• GDStateListener provides simple state transition notifications by a custom interface.
• GDAppEventListener provides detailed information by a custom interface.
• GDStateAction provides simple state transition notifications by Android local broadcast.

See under Authorization State, above, for an introduction.

All interfaces require that an observer object is set.

The GDStateListener observer can be set in one of two ways:

• Declare an activity as extending the GDStateListener interface, which implicitly sets the activity instance as its own observer object.
• Call the setGDStateListener() method and pass the observer object as a parameter, which sets the observer explicitly. See the GDAndroid.setGDStateListener method reference for details.

Setting the observer explicitly could be used when the application has a singleton class that handles all authorization state transitions.

The GDAppEventListener observer is always set explicitly, either in the authorize() call, or by calling the setGDAppEventListener() method.

The GDStateAction observer is always set explicitly, by calling the GDAndroid.registerReceiver method.

If the application only uses GDStateAction to monitor authorization, and doesn't implement GDStateListener nor GDAppEventListener, then the BlackBerry Dynamics event receiver check must be switched off. Instructions for switching off are on the Build-Time Configuration page, under the Event Receiver Check heading.

Comparison

The GDAppEventListener interface exposes a complete and detailed view of the state of the BlackBerry Dynamics runtime. It was the only interface in some earlier releases of the SDK for Android.

The GDStateListener interface is a simplified layer, at a higher level than the GDAppEventListener interface. Although GDStateListener exposes less detail, what it does provide is sufficient to enable the application to manage completely its execution cycle. The GDStateListener interface was designed to be easier to implement in the application code.

The GDStateAction interface presents the same information as GDStateListener, but through a native mechanism.

New applications should implement GDStateListener as a first choice.

Programming interface restrictions

The application cannot use any of the principal BlackBerry Dynamics interfaces before authorization has succeeded. If the application attempts to do so, the runtime throws an error, which results in the application being terminated. The error that is thrown is a subclass of the Error class, and not the Exception class. No declaration or handling of the error is required in the application code.

The runtime doesn't throw errors for transient conditions, but only for apparent programming errors in the application. Consequently, these errors are only expected when the application is in development, and not when the application is in production. The failure message of the error object will describe the programming error.

The recommended approach is that the application should be allowed to terminate, so that the failure message can be read in the device log. The failure message will describe the programming error, which can then be corrected.

Activation

In BlackBerry Dynamics, activation refers to a number of registration procedures that must be completed in order to access all platform capabilities. Once a particular activation has been completed, registration credentials are stored on the device. This means that each activation need only be processed once.

Activations are generally transparent to the application. The application will call a BlackBerry Dynamics authorization method, and the runtime will process whichever activations are required.

There are two activations in BlackBerry Dynamics.

Infrastructure activation

Recognition of the application instance as a terminal by the BlackBerry Dynamics central server.

Enterprise activation

Association of the terminal with a provisioned end user at the enterprise. This requires activation credentials, which may be obtained by any of the following means.

• Entered manually into the BlackBerry Dynamics user interface.
• Retrieved progammatically via another BlackBerry Dynamics application, known as Easy Activation. .

See also

System administration tasks.

Enterprise Simulation mode for instructions on building an application to run in a special limited mode in which there is no enterprise activation.

Identification

Every BlackBerry Dynamics application has a unique identifier and version for the purposes of entitlement management, publishing, and service provider registration. The identifier was previously referred to as the Good Dynamics application identifier, or in the abbreviated form GD App ID, but is now referred to as the entitlement identifier.

Entitlement identifiers are used:

• In the application.
• In the BlackBerry Dynamics management console at the enterprise.
• In some administrative user interfaces accessible via the application developer portal.

A BlackBerry Dynamics entitlement identifier is generally accompanied by a separate entitlement version.

In the mobile application, the entitlement identifier and version values are set by the authorization call, as documented in the authorize method reference, below. In the management console, the entitlement identifier and version values are entered as part of application management.

See also

System administration tasks.

Entitlement Identifier Format

Entitlement identifiers are textual and follow a typical naming convention. The reversed Internet domain of the application developer forms the initial part of the identifier. For example, applications developed by BlackBerry can have identifiers that begin "com.blackberry." because BlackBerry owns the blackberry.com Internet domain.

The rest of the identifier is made up of the application's name, possibly preceded by a number of categories and sub-categories. Categories and sub-categories are separated by full stops. For example, the identifier of an example remote database application, made by BlackBerry, could be: "com.blackberry.gd.examples.remotedb". Note that BlackBerry also owns the good.com domain, so could also use "com.good.gd.examples.remotedb".

Formally, the syntax of an entitlement identifer is a string that:

• Contains only the following ASCII characters: hyphen (dash), full stop (period), numeric digit, lower-case letter.
• Conforms to the <subdomain> format initially defined in section 2.3.1 of RFC1035 and subsequently modified in section 2.1 of RFC1123.

Entitlement Version Format

A BlackBerry Dynamics entitlement version is a string made up of a sequence of numbers separated by full stops (periods). The following represents best practice.

• The first release of the application should have "1.0.0.0" as its entitlement version.
• The version string should change in subsequent releases in which one of the following software changes is made:
  • The application starts to provide a new shared service or shared service version.
  • The application stops providing a shared service or shared service version.
  Otherwise, version should not change in the release.

See the icc package reference for details of shared services.

The syntax rules of entitlement version values are as follows.

• A version string consists of one to four version numbers separated by full stop (period) characters.
• A version number consists of one of the following:
  • A single zero.
  • A sequence of up to three digits with no leading zero.

The syntax can be formally expressed as the following regular expression: (0|[1-9][0-9]{0,2})(.(0|[1-9][0-9]{0,2})){0,3}

Don't use a different entitlement version for an early access or beta software release. Instead, add a suffix to the BlackBerry Dynamics entitlement identifier and native application identifier used for general access. For example, the entitlement identifier "com.example.gdapp.beta" could be used to identify a "com.example.gdapp" beta release.
Using a different native identifier makes it possible for general access and early access software to be installed on the same mobile device, and facilitates use of different signing certificates.

Application user interface restrictions

See the Application User Interface Restrictions page.

Build-Time Configuration

See the Build-Time Configuration page.

Enterprise Configuration Information

There are a number of methods in this class for obtaining enterprise configuration information, including settings that apply to the current end user. The GDAndroid.getApplicationPolicy and GDAndroid.getApplicationConfig methods are examples of this type of method.

All the methods of this type:

• Return their results in a collection of objects.
• Have a corresponding GDStateListener callback that is invoked, and a corresponding GDAppEvent event type that is dispatched to the application's GDAppEventListener instance, when the result would change.

For example, the GDAndroid.getApplicationPolicy method returns a Map<String, Object> collection. When there is a change, the onUpdatePolicy callback is invoked, and a GDAppEventPolicyUpdate event is dispatched.

Use these methods as follows.

1. Make a first call to get an initial collection.
2. Retain the collection, and refer to it in any code that utilizes its values.
3. When the update callback is invoked, or an update event is received, discard the retained collection and call the method again to get a new collection.

Don't make a subsequent call to the same method until an update event has been received. The BlackBerry Dynamics runtime generates a new collection for each call to one of these methods. If the application code makes multiple calls and retains all the returned collections, then they will all consume memory or other application resources.

Code Snippets

The following code snippets illustrate some common tasks.

Indirect Authorization Initiation

The following snippet shows indirect initiation of BlackBerry Dynamics authorization processing, and implicit setting of the authorization state transition observer.

public class MyActivity extends Activity implements GDStateListener {
 
    public void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
 
        GDAndroid.getInstance().activityInit(this);
 
        // rest of Activity initialization ...
    }
 
    // GDStateListener method implementations
 
    public void onAuthorized() {
        startSecureDBAccess();
        startAppComms();
    }
}

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

Connection to the BlackBerry Dynamics platform is initiated by calling activityInit() in the onCreate method. This code would also be present in all the other activity classes in the application.

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

The above code relies on the identification parameters being in the assets/settings.json file, as shown in the following snippet.

{
    "GDApplicationID": "com.example.browser",
    "GDApplicationVersion": "1.0.0.0",
    "GDConsoleLogger": [
        "GDFilterErrors",
        "GDFilterWarnings",
        "GDFilterInfo",
        "GDFilterDetailed"
    ]
}

The above sets "com.example.browser" as the BlackBerry Dynamics entitlement identifier, and "1.0.0.0" as the BlackBerry Dynamics entitlement version.

The above also configures the logging level of the application. See Runtime activity log.

Singleton Authorization State Transition Observer

The following snippet shows explicit setting of a singleton object as the authorization state transition observer.

public class MyApplication extends Application {
 
    public void onCreate() {
        GDAndroid.getInstance().setGDStateListener(MyGDStateListener.sharedInstance());
    }
}

The singleton MyGDStateListener object is set as the authorization state transition observer for all activity classes in the application.

The setting is in the onCreate method of the Application subclass, which would be registered in the AndroidManifest.xml file using the application tag.

Direct Authorization Initiation

The following snippet shows direct initiation of BlackBerry Dynamics authorization processing.

public class LaunchActivity extends Activity {
    private boolean _authorizeCalled = false;
 
    // Override annotation should go here
    public void onResume() {
        super.onResume();
 
        if (!_authorizeCalled) {
            GDAndroid.getInstance().authorize(MyGDAppEventListener.sharedInstance());
            _authorizeCalled = true;
        }
 
        // rest of activity initialization here, but no use of BlackBerry
        // Dynamics programming interfaces.
    }
 
    // rest of class code here.
}

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

The singleton MyGDAppEventListener object is set as the BlackBerry Dynamics runtime event handler.

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

Usage of ActivationSetting in Programmatic Activation

The following snippet shows configuration of Programmatic Activation using ActivationSetting

Bundle b = new Bundle();
 
b.putString(ApplicationState.ActivationParameter.UserIdentifier.name(), hello@world.net);
b.putString(ApplicationState.ActivationParameter.AccessKey.name(), abcdefghijlmnop);
b.putBoolean(ApplicationState.ActivationParameter.ShowUserInterface.name(), false);
 
GDAndroid.getInstance().programmaticActivityInit(context, b);

Public Member Functions
void	activityInit (android.app.Activity activity) throws GDInitializationError
	Register an activity for BlackBerry Dynamics monitoring, including indirect authorization processing. More...
boolean	serviceInit (final Context context) throws GDInitializationError
	Initiate authorization processing for a background service. More...
void	programmaticServiceInit (final Context context, Bundle activationParameters)
	Initiate programmatic activation for a background service. More...
void	applicationInit (Context context) throws GDInitializationError
	Prepare the runtime (optional). More...
void	setGDStateListener (GDStateListener stateListener)
	Set the GDStateListener observer explicitly. More...
void	setGDAppEventListener (GDAppEventListener eventListener)
	Set the GDAppEventListener observer. More...
void	authorize (GDAppEventListener eventListener) throws GDInitializationError
	Connect to the BlackBerry Dynamics infrastructure with direct authorization processing. More...
void	programmaticActivityInit (android.app.Activity activity, Bundle activationParameters)
	Initiate programmatic activation. More...
boolean	isActivated (Context context)
	Check whether the application has been activated. More...
String	getApplicationId () throws GDInitializationError
	Get the effective BlackBerry Dynamics entitlement identifier. More...
String	getAppVersion () throws GDInitializationError
	Get the effective BlackBerry Dynamics entitlement version. More...
boolean	openChangePasswordUI () throws GDNotAuthorizedError
	Open the BlackBerry Dynamics change password user interface. More...
boolean	openFingerprintSettingsUI () throws GDNotAuthorizedError
	Open the BlackBerry Dynamics fingerprint settings user interface. More...
boolean	openSafeWiFiSetupUI () throws GDNotAuthorizedError
	Open the BlackBerry Dynamics MTD SafeWiFi setup user interface. More...
boolean	supportsFingerprintAuthentication () throws GDNotAuthorizedError
	Check whether fingerprint authentication is currently available. More...
boolean	canAuthorizeAutonomously (Context context)
	Check whether it is possible to authorize autonomously. More...
Map< String, Object >	getApplicationConfig () throws GDNotAuthorizedError
	Get application configuration and other settings from the enterprise. More...
Map< String, Object >	getApplicationPolicy () throws GDNotAuthorizedError
	Get application-specific policy settings from the enterprise management console, as a collection. More...
String	getApplicationPolicyString () throws GDNotAuthorizedError
	Get application-specific policy settings from the enterprise management console, as JSON. More...
Vector< GDServiceProvider >	getServiceProviders () throws GDNotAuthorizedError
	Get providers of shared services. More...
Vector< GDServiceProvider >	getServiceProvidersFor (String serviceId, String version, GDServiceType serviceType) throws GDNotAuthorizedError
	Discover providers of a specific shared service. More...
int	getEntitlementVersions (String identifier, GDEntitlementVersionsRequestCallback callback)
	Check whether the end user has a particular entitlement. More...
void	configureUI (final Drawable smallApplicationLogo, final Drawable bigApplicationLogo, final Integer color)
	Configure the visual appearance of the BlackBerry Dynamics user interface. More...
SharedPreferences	getGDSharedPreferences (String name, int mode)
	Access a preferences file in the BlackBerry Dynamics secure store. More...
GDAuthDelegateInfo	getAuthDelegate ()
	Get an AuthDelegateInfo object containing details of the application to which this application has delegated its authentication. More...
void	registerReceiver (BroadcastReceiver receiver, IntentFilter filter)
	Register for notifications sent by local broadcast. More...
void	unregisterReceiver (BroadcastReceiver receiver)
	Remove a local broadcast receiver. More...

Static Public Member Functions
static synchronized GDAndroid	getInstance ()
	Get a reference to the runtime interface object. More...
static String	getVersion ()
	Get the BlackBerry Dynamics runtime library version. More...
static void	executeBlock (String blockId, String title, String message)
	Blocks application locally with defined blockId. More...
static void	executeUnblock (String blockId)
	Unblocks application locally with defined blockId. More...
static void	executeRemoteLock ()
	Lock the application permanently. More...
static boolean	executePendingConsoleMigration (String destinationTenantID, String uemServerAddress)
	Executes migration of the application to a different management console. More...

Static Public Attributes
static final String	GDAppConfigKeyServers = GDAndroidAPI.GDAppConfigKeyServers
	Constant key value for application server configuration. More...
static final String	GDAppConfigKeyConfig = GDAndroidAPI.GDAppConfigKeyConfig
	Constant key value for application-specific configuration data. More...
static final String	GDAppConfigKeyPreventDataLeakageOut = GDAndroidAPI.GDAppConfigKeyPreventDataLeakageOut
	Constant key value for the outbound Data Leakage security policy indicator. More...
static final String	GDAppConfigKeyPreventDataLeakageIn = GDAndroidAPI.GDAppConfigKeyPreventDataLeakageIn
	Constant key value for the inbound Data Leakage security policy indicator. More...
static final String	GDAppConfigKeyPreventAndroidDictation = GDAndroidAPI.GDAppConfigKeyPreventAndroidDictation
	Constant key value for allowing or disallowing use of dictation. More...
static final String	GDAppConfigKeyPreventAndroid3rdPartyKeyboards = GDAndroidAPI.GDAppConfigKeyPreventAndroid3rdPartyKeyboards
	Constant key value for allowing or disallowing use of 3rd party keyboards. More...
static final String	GDAppConfigKeyPreventScreenCapture = GDAndroidAPI.GDAppConfigKeyPreventScreenCapture
	Constant key value for allowing or disallowing screen capture. More...
static final String	GDAppConfigKeyInstanceIdentifier = GDAndroidAPI.GDAppConfigKeyInstanceIdentifier
	Constant key value for application instance identifier. More...
static final String	GDAppConfigKeyDetailedLogsOn = GDAndroidAPI.GDAppConfigKeyDetailedLogsOn
	Constant key value for whether detailed diagnostic logging is switched on for this application instance or by policy for the current user. More...
static final String	GDAppConfigKeyPreventUserDetailedLogs = GDAndroidAPI.GDAppConfigKeyPreventUserDetailedLogs
	Constant key value for whether the end user is allowed to switch on detailed logging. More...
static final String	GDAppConfigKeyUserId = GDAndroidAPI.GDAppConfigKeyUserId
	Constant key value for the user's enterprise email address. More...
static final String	GDAppConfigKeyUserPrincipalName = GDAndroidAPI.GDAppConfigKeyUserPrincipalName
	Constant key value for the user's User Principal Name (UPN). More...
static final String	GDAppConfigKeyProtectedByPassword = GDAndroidAPI.GDAppConfigKeyProtectedByPassword
	Constant key value for whether the application is protected by a BlackBery Dynamics password. More...
static final String	GDAppConfigKeyExtraInfo = GDAndroidAPI.GDAppConfigKeyExtraInfo
	Constant key value for extra information from the management console. More...
static final String	GDAppEnterpriseIdActivated = GDAndroidAPI.GDAppEnterpriseIdActivated
	Constant key value for whether BlackBerry Enterprise Identity is setup. More...
static final String	GDAppConfigKeyEnterpriseIdFeatures = GDAndroidAPI.GDAppConfigKeyEnterpriseIdFeatures
	Constant key value containing a JSON array of available Enterprise Identity features. More...
static final String	GDAppConfigKeyCommunicationProtocols = GDAndroidAPI.GDAppConfigKeyCommunicationProtocols
	Constant key value for the list of communications protocols allowed by the enterprise. More...
static final String	GDProtocolsKeyTLSv1_0 = GDAndroidAPI.GDProtocolsKeyTLSv1_0
	Constant value for a secure communication protocol: TLS version 1.0. See under GDAndroid.getApplicationConfig.
static final String	GDProtocolsKeyTLSv1_1 = GDAndroidAPI.GDProtocolsKeyTLSv1_1
	Constant value for a secure communication protocol: TLS version 1.1. See under GDAndroid.getApplicationConfig.
static final String	GDProtocolsKeyTLSv1_2 = GDAndroidAPI.GDProtocolsKeyTLSv1_2
	Constant value for a secure communication protocol: TLS version 1.2. See under GDAndroid.getApplicationConfig.
static final String	GDAppConfigKeyAndroidKeyboardRestrictedMode = GDAndroidAPI.GDAppConfigKeyAndroidKeyboardRestrictedMode
	Constant key value for whether keyboard restricted mode is enabled. See under GDAndroid.getApplicationConfig.

Member Function Documentation

getInstance()

static synchronized GDAndroid getInstance ( )

static

This method returns a reference to the BlackBerry Dynamics runtime object.

The BlackBerry Dynamics runtime object is a "singleton class".

Returns

Reference that can be used to call, for example,GDAndroid.authorize.

activityInit()

void activityInit

(

android.app.Activity

activity

)

throws GDInitializationError

Call this method to register an activity for monitoring by the BlackBerry Dynamics runtime. Pass the android.app.Activity instance associated with the activity as a parameter.

When a monitored activity is created, the runtime will initiate authorization processing if necessary. This is indirect authorization processing initiation. See under BlackBerry Dynamics Platform Connection, above, for an introduction. The authorization processing steps will be the same as when GDAndroid.authorize is called. Application identification parameters will be read from the assets/settings.json file.

Calling this method from the onCreate method of the Activity subclass is one way for an activity to comply with the BlackBerry Dynamics application user interface restrictions. See the Application User Interface Restrictions page for details and for alternative ways to comply.

Don't pass an instance of a subclass of a BlackBerry Dynamics activity replacement class as the parameter of this method.

Implementation by fragment attachment

BlackBerry Dynamics monitoring of the user interface is implemented by attaching a fragment (android.app.Fragment instance) to the associated activity at run time.
A consequence of the fragment attachment implementation is that the onAttachFragment callback of the Activity instance will be invoked when this method is called.
It is possible for the application code to attach one or more fragments of its own, and to extend the onAttachFragment callback in order to obtain references to those fragments. In that case it would be necessary to check the type of every fragment passed in an onAttachFragment invocation, so that the fragment attached by BlackBerry Dynamics is not mistaken for one of the application code's own fragments.

Parameters

activity

the android.app.Activity instance associated with the activity that is being registered, typically this.

Exceptions

GDInitializationError

if a subclass of a BlackBerry Dynamics activity replacement class is passed as the parameter.

serviceInit()

boolean serviceInit

(

final Context

context

)

throws GDInitializationError

Call this method to initiate authorization processing for a background service. Pass the android.app.Service instance associated with the service as a parameter.

This method should be called when the application receives a background event that might be possible to process without foreground execution. Background events in scope include:

• Notifications for Google Cloud Messaging (GCM) or Firebase Cloud Messaging (FCM), see https://developers.google.com/cloud-messaging/.
• Background broadcasts.
• Explicit Intent notifications.

Authorization processing can complete in background, if all the following conditions are met:

• Activation has completed. The application must have run in foreground and completed authorization processing at least once for this to be the case.
• Authorization can complete autonomously, without user interaction, i.e. a no-password enterprise policy is in effect for the current end user.

Call this method in the onCreate method of the Service subclass that processes the background event. Call GDAndroid.canAuthorizeAutonomously first, to check that a no-password policy applies to the current end user and autonomous authorization is possible.

If authorization can complete autonomously, calling this method results in the same processing and notification as if GDAndroid.authorize had been called. Application identification parameters will be read from the assets/settings.json file.

Parameters

context

android.app.Service instance associated with the background service, typically this.

Returns

true if authorization can complete autonomously. The application will be notified when authorization completes, or if it fails for some reason.

false if authorization cannot complete autonomously. No further notification will be dispatched.

Exceptions

GDInitializationError

if the parameter is null or the calling Service doesn't implement GDStateListener interface unless there is a singleton Listener to receive BlackBerry Dynamics runtime events. If a singleton has been provided then it is optional for Service to implement the interface.

programmaticServiceInit()

void programmaticServiceInit	(	final Context	context,
		Bundle	activationParameters
	)

Call this method to initiate programmatic activation in the background.

• context android.app.Service instance associated with the background service.
• Bundle See: ApplicationState.ActivationParameter class reference for details of ActivationParameters.

Only call this method after checking that the application is not already activated, by calling the GDAndroid.isActivated method.

Activation progress can be monitored using ApplicationState.getActivationState. For example, if the user is required to set a password and therefore the application must be brought to the foreground the EActivatingForegroundRequired state will be returned.

To programmatically activate in the foreground use GDAndroid.programmaticActivityInit instead.

applicationInit()

void applicationInit

(

Context

context

)

throws GDInitializationError

Call this method to prepare the BlackBerry Dynamics runtime for use by the application.

The runtime prepares itself automatically when either GDAndroid.authorize or GDAndroid.activityInit is called, so calling this method is generally unnecessary. However, calling this method is necessary if a local broadcast receiver is being used for notification of the first completion of authorization processing. See the GDStateAction class reference.

This method can be called in the Application class implementation. This method need only be called once, when the application starts. Calling this method doesn't initiate authorisation processing, which must still complete before the BlackBerry Dynamics programming interface can be used by the application. See the Application User Interface Restrictions page.

Parameters

context

Android Context object for the application, typically this to pass a reference to the android.app.Application instance.

Exceptions

GDInitializationError

if the parameter is null or otherwise invalid.

setGDStateListener()

void setGDStateListener

(

GDStateListener

stateListener

)

Call this method to set the authorization state transition observer explicitly. Pass the object to set as the observer as a parameter.

See under Authorization State Transition Notification Interfaces, above, for a description of the implicit and explicit mechanisms for setting the observer. The implicit mechanism is an alternative to using this method.

A reference to the observer object will be retained by the BlackBerry Dynamics runtime. The observer mustn't be an Activity instance, because Activity instances can be destroyed at any time by the operating system.

This method would typically be called in the onCreate method of the subclass of Application referred to in the application tag in the AndroidManifest.xml file. It shouldn't be called from the onCreate method of an activity class. The Android operating system doesn't guarantee the order in which activities have their onCreate methods called.

This method must be called before the authorization initiation method, either GDAndroid.authorize or GDAndroid.activityInit, is called.

Parameters

stateListener

the observer, which must implement the GDStateListener interface.

Exceptions

GDInitializationError

if an Activity is passed as the observer.

See also

Authorization State, above, for an introduction to the transitions that would be notified to the observer.

setGDAppEventListener()

void setGDAppEventListener

(

GDAppEventListener

eventListener

)

Call this method to set the authorization state event handler. Pass the object to set as the handler, the observer, as a parameter.

This method is provided so that the GDAppEventListener interface can be used in addition to the GDStateListener interface, when indirect authorization processing initiation is in use.

When direct authorization processing initiation is in use, the handler would typically be set when GDAndroid.authorize is called, and not by calling this method separately.

Parameters

eventListener

the observer object, which must implement the GDAppEventListener interface.

See also

Authorization State, above, for an introduction to the transitions that would be notified to the observer.

authorize()

void authorize

(

GDAppEventListener

eventListener

)

throws GDInitializationError

Call this method to initiate BlackBerry Dynamics authorization processing directly.

Authorization can also be initiated indirectly. See the Application User Interface Restrictions page for details of the programming interface. See under BlackBerry Dynamics Platform Connection, above, for an introduction to authorization processing.

Authorization involves a number of exchanges with various servers in the BlackBerry Dynamics proxy infrastructure, and may involve user interaction. The following processing items are the most significant.

Infrastructure activation

The BlackBerry Dynamics runtime registers the application instance as a terminal with the BlackBerry Dynamics Network Operation Center (NOC). The NOC issues registration credentials, which are encrypted and stored locally by the runtime. Infrastructure activation is not processed if registration credentials are already present.

Enterprise activation

Enterprise activation is the completion of the enterprise provisioning process. An access key will have been created by the enterprise management console, and made available to the runtime instance embedded in the application. See under Activation, above, for the methods by which the key can be made available.

During enterprise activation, the runtime sends the key to the NOC. If the key is recognized, the application instance is associated with the enterprise that created the key. Enterprise registration credentials are then issued, and encrypted and stored locally by the runtime.
Enterprise activation is not processed if enterprise registration credentials are already present.
Note that successful enterprise activation has the effect of consuming the access key. This will be the case even if a later stage of authorization processing fails, or if it is found that the user isn't entitled to this application.

Entitlement checking

The enterprise that provisioned the end user can later withdraw the user's entitlement to the application. Withdrawal is flagged in the enterprise's management console. The runtime checks the end user's ongoing entitlement to the application every time authorization is processed. (In addition, withdrawal may be notified to the runtime by the NOC.)
In the management console, entitlement is given to particular versions of particular applications. The entitlement version and identifier values built into the application must match exactly with a version and identifier to which the user has been given entitlement in the management console. If there isn't an exact match, then user entitlement is assumed to have been withdrawn.
If the user is found not to be entitled, then the runtime deletes all locally stored application data and authentication credentials.

Policy update

Policies govern many aspects of the BlackBerry Dynamics user experience. For example, the minimum characteristics of the end user's security password with respect to length and types of character are governed by a policy. So is the need for the end user to set a security password. The runtime checks for and retrieves updated policies every time authorization is processed.

Policy checking

The runtime checks for compliance with the most up-to-date policies every time authorization is processed.

Configuration retrieval

The runtime retrieves a set of application configuration settings from the enterprise management console during authorization processing. These will have been stored in the management console. See under GDAndroid.getApplicationConfig for a list of settings.

Unlock secure store

The BlackBerry Dynamics secure store is unlocked during authorization. If the store is protected by an end-user password, then the user must enter their password for authorization processing to complete. Password entry takes place in a BlackBerry Dynamics user interface, not in the application user interface.

Note that BlackBerry Dynamics user interfaces mentioned in the above, such as Enterprise activation and Password entry, are opened and closed as needed, without reference to the application.

When direct authorization processing initiation is in use, this method must be called before any other BlackBerry Dynamics methods.

Data communication during authorization processing doesn't go via the proxy specified in the device's native settings, if any.

Parameters

eventListener

the authorization state event handler, which must implement the GDAppEventListener interface.

Application identification parameters will be read from the settings.json file in the assets/ folder of the application. Some earlier versions of the BlackBerry Dynamics SDK for Android could instead read values from the AndroidManifest.xml file but this option has now been removed.

The value of the following entries will be utilized:

settings.json Key	Value
GDApplicationID	BlackBerry Dynamics entitlement identifier. (This identifier was previously referred to as the Good Dynamics application identifier, or in the abbreviated form GD App ID.) This identifier is used to control access to the application by end users, and to configure its application server connections. The value passed must be the same as the value present in the enterprise management console. (Note that the value needn't be the same as the native application identifier.) For syntax details see under Entitlement Identifier Format, above.
GDApplicationVersion	BlackBerry Dynamics entitlement version number The version number can be combined with the entitlement identifier, above, to control access to particular versions of the application.

Authorization is asynchronous. When authorization processing completes, the authorization state event handler's onGDEvent callback is invoked. If a GDStateListener observer has been set and authorization succeeds, then its onAuthorized callback is also invoked. See setGDStateListener.

See also

System administration tasks.

Exceptions

GDInitializationError

if the BlackBerry Dynamics runtime encountered an error during initialization.

programmaticActivityInit()

void programmaticActivityInit	(	android.app.Activity	activity,
		Bundle	activationParameters
	)

Call this method to initiate programmatic activation, and register an activity for monitoring by the BlackBerry Dynamics runtime. Programmatic activation can only be utilized by applications that can obtain credentials for enterprise activation on behalf of the end user. The credentials are passed as parameters to this method. The credentials must already have been generated, by an enterprise BlackBerry Dynamics management console, prior to this method being called.

Activation requires processing on the BlackBerry Dynamics Network Operation Center (NOC). From an architectural point-of-view, there is a single NOC for all BlackBerry Dynamics enterprises and users. For practical reasons, however, there may actually be a number of NOC deployments. For example, there may be separate production and development deployments. The application can specify which NOC is to process programmatic activation, in the nocAddress parameter to this method.

Calling this method also initiates authorization processing, as if the GDAndroid.activityInit method had been called.

Only call this method after checking that the application is not already activated, by calling the GDAndroid.isActivated method.

See: ApplicationState.ActivationParameter class reference for details of ActivationParameters to use in Bundle argument

isActivated()

boolean isActivated

(

Context

context

)

Call this method to check whether the application has already been activated. It is necessary to check whether the application has been activated before initiating programmatic activation.

Parameters

context

Android Context object for the application.

Returns

true if the application has been activated.

false otherwise.

getApplicationId()

String getApplicationId

(

)

throws GDInitializationError

This method returns the BlackBerry Dynamics entitlement identifier that was effective at authorization time.

This method can only be called after BlackBerry Dynamics authorization processing has been initiated, either directly with GDAndroid.authorize, or indirectly with GDAndroid.activityInit.

Returns

String containing the entitlement identifier.

Exceptions

GDInitializationError

if called before authorization processing has been initiated.

getAppVersion()

String getAppVersion

(

)

throws GDInitializationError

This method returns the BlackBerry Dynamics entitlement version that was effective at authorization time.

This method can only be called after BlackBerry Dynamics authorization processing has been initiated, either directly with GDAndroid.authorize, or indirectly with GDAndroid.activityInit.

Returns

String containing the entitlement version.

Exceptions

GDInitializationError

if called before authorization processing has been initiated.

getVersion()

static String getVersion ( )

static

Returns

String containing the BlackBerry Dynamics runtime library version in major.minor.build format.

openChangePasswordUI()

boolean openChangePasswordUI

(

)

throws GDNotAuthorizedError

Call this method to show the BlackBerry Dynamics change password user interface.

This method enables a BlackBerry Dynamics user interface element to be included in the application's own user interface.

If authorization is delegated to another application, then that application will be opened and its Change Password user interface will be shown.

Returns

true if the user interface element opened OK, or was already open.

false if this application does not have a password, or is in the Wiped state.

Exceptions

com.good.gd.error.GDNotAuthorizedError

if BlackBerry Dynamics authorization processing has not yet completed.

openFingerprintSettingsUI()

boolean openFingerprintSettingsUI

(

)

throws GDNotAuthorizedError

Call this method to show the BlackBerry Dynamics fingerprint settings user interface.

This method enables a BlackBerry Dynamics user interface element to be included in the application's own user interface. It should only be included if fingerprint authentication is currently available, which can be determined by calling the supportsFingerprintAuthentication method, below.

Returns

true if the user interface element opened OK, or was already open.

false if fingerprint authorization isn't available, or if the interface cannot be opened for another reason, see under openChangePasswordUI, above.

Exceptions

com.good.gd.error.GDNotAuthorizedError

if BlackBerry Dynamics authorization processing has not yet completed.

openSafeWiFiSetupUI()

boolean openSafeWiFiSetupUI

(

)

throws GDNotAuthorizedError

Call this method to show the BlackBerry Dynamics MTD SafeWiFi setup user interface.

This method enables an application to prompt the user to turn on BlackBerry Dynamics SafeWifi checks. The user interface guides and prompts the user to grant the location OS permission to the application. This permission is required to enable the security feature.

Returns

true if the user interface element opened OK, or was already open.

false if this application is in the Wiped state.

Exceptions

com.good.gd.error.GDNotAuthorizedError

if BlackBerry Dynamics authorization processing has not yet completed.

supportsFingerprintAuthentication()

boolean supportsFingerprintAuthentication

(

)

throws GDNotAuthorizedError

Call this method to check whether BlackBerry Dynamics fingerprint authentication is currently available.

Fingerprint authentication will be available if:

• Fingerprint authentication is currently allowed by the enterprise that the end user represents.
• The device on which the application is installed has a fingerprint sensor that is supported by BlackBerry Dynamics.

This method can be used to determine whether the BlackBerry Dynamics fingerprint settings should be offered within the application's own user interface, see openFingerprintSettingsUI, above.

The enterprise that the end user represents can allow and disallow fingerprint authentication by changing a policy setting in their BlackBerry Dynamics management console. This means that the return value of this method could be different at different times, if the enterprise has changed their policies.

Returns

true if fingerprint authentication is available.

false otherwise.

Exceptions

com.good.gd.error.GDNotAuthorizedError

if BlackBerry Dynamics authorization processing has not yet completed.

canAuthorizeAutonomously()

boolean canAuthorizeAutonomously

(

Context

context

)

Call this method to check whether autonomous authorization is possible. Autonomous authorization won't be possible if the application is protected by a BlackBerry Dynamics password. This means a password or other interactive authentication that is enforced by the BlackBerry Dynamics runtime.

Interactive authentication will be enforced by BlackBerry Dynamics unless a no-password policy applies to the current end user. A no-password policy would typically be put in place only in the case that interactive authentication is enforced by some other means. For example, enterprise mobile device management (MDM) can be used to force users to set a device password or lock pattern. In that case, the enterprise might choose to set a no-password policy for BlackBerry Dynamics, so that end users don't have to enter two passwords.

If interactive authentication isn't enforced by BlackBerry Dynamics, then it is possible for authorization processing to complete autonomously, because interaction with the user isn't required.

The intended use of this method is to check whether it is possible for authorization processing to complete autonomously, before calling the GDAndroid.serviceInit method.

Note that it won't be possible to authorize autonomously if enterprise policy specifies that the application delegates authentication to another application. This would only happen if the current end user somehow had both policies in place: authentication delegation, and no-password. This combination isn't recommended. There would seem to be no point in delegating authentication to another application if that other application is going to authenticate the end user without interaction.

This method can be called before authorization processing is complete.

Parameters

context

Android Context object for the application.

Returns

true if autonomous authorization is possible.

false if a password is enforced by BlackBerry Dynamics, or if autonomous authorization isn't possible for some other reason.

getApplicationConfig()

Map<String, Object> getApplicationConfig

(

)

throws GDNotAuthorizedError

This method returns a collection of application configuration and other settings. The settings will have been made in the enterprise management console, and retrieved by the BlackBerry Dynamics runtime.

Retrieval of configuration settings may happen during authorization processing, or whenever settings are changed. When changed settings have been retrieved by the runtime, a GDAppEventRemoteSettingsUpdate event will be dispatched to the application. See the GDAppEvent class reference for details, and see the notes under the Enterprise Configuration Information heading, above.

Note that retrieval isn't as such triggered by calling this function.

Returns

Map<String, Object> object containing configuration values. Use the GDAppConfigKey constant strings as keys.

Any of the following configuration settings may be present.

Key Constant	Setting	Type
GDAppConfigKeyServers	Application server configuration. A number of servers can be configured for an application, in the management console. See the GDAppServer class reference for documentation of the details that are returned for each configured server.	java.util.List of GDAppServer
GDAppConfigKeyConfig	Application-specific configuration data. As well as the application server details, above, a free text can also be entered in the management console. Whatever was entered is passed through by the runtime and made available to the application code here.	String
GDAppConfigKeyPreventDataLeakageOut	Outbound Data Leakage policy indicator. true means that enterprise security policies require that the end user must be prevented from taking any action that is classified as data loss or data leakage in the BlackBerry Dynamics Security Compliance Requirements document. false means that the above policy isn't in effect, so the user is permitted to take those actions.	Boolean
GDAppConfigKeyPreventDataLeakageIn	Inbound Data Leakage policy indicator. true means that enterprise security policies require that the end user must be prevented from copying into the application data that originates from elsewhere than another BlackBerry Dynamics application activated by the same end user on the same device or computer. false means that the above policy isn't in effect, so the user is permitted to copy in data from any other application.	Boolean
GDAppConfigKeyPreventAndroidDictation	Dictation Prevention policy indicator. true means that enterprise security policies require that the end user must be prevented from using dictation as a form of input. false means that the above policy isn't in effect, so the user is permitted to use dictation. This setting is included for completeness. The policy is generally enforced by the BlackBerry Dynamics runtime without reference to the application code.	Boolean
GDAppConfigKeyPreventScreenCapture	Screen Capture Prevention policy indicator. true means that enterprise security policies require that the end user must be prevented from creating screen capture images. false means that the above policy isn't in effect, so the user is permitted to create screen capture images. This setting is included for completeness. The policy is generally enforced by the BlackBerry Dynamics runtime without reference to the application code. See the appendix page: Screen Capture Control.	Boolean
GDAppConfigKeyDetailedLogsOn	Logging level. false means that the logging level is low, and only minimal logs should be written. true means that the logging level is high, and detailed logs should be written. Detailed logs facilitate debugging of issues encountered at run time. The BlackBerry Dynamics runtime will automatically adjust its logging according to the configured setting. The setting is present in the programming interface so that the application can adjust its logging consistently with the runtime.	Boolean
GDAppConfigKeyPreventUserDetailedLogs	User detailed logging block indicator. true if the end user is blocked from switching on detailed logging, false otherwise. Use this configuration key to determine whether to offer the end user an option to switch on detailed logging. Only offer the end user an option to switch on detailed logging if it isn't blocked by policy. See com.good.gd.log.GDLogManager for how to switch on detailed logging from the application code.	Boolean
GDAppConfigKeyUserId	Enterprise user identifier, typically email address. An enterprise identifier for the end user is one of the credentials required for activation of BlackBerry Dynamics application. This could be the email address entered in the activation user interface when the application was run for the first time, for example. The value obtained for this setting will initially be the enterprise email address, or other identifier, used for activation. If the enterprise email address of the end user changes after activation then the value of this setting will also change, next time it is obtained.	String
GDAppConfigKeyUserPrincipalName	User Principal Name. The User Principal Name (UPN) will have been retrieved from the enterprise Active Directory (AD) service by the enterprise management console, and then sent to the runtime, initially at activation time. This value will only be present if the current end user corresponds to an AD entry. The value may or may not be the same as the GDAppConfigKeyUserId value, depending on enterprise domain configuration. The value will be in username@fully.qualified.domain.name format. If the UPN of the end user changes after activation then the value of this setting will also change, next time it is obtained.	String
GDAppConfigKeyInstanceIdentifier	Application instance identifier. The BlackBerry Dynamics runtime generates a unique identifier for the installed application when it is activated. This identifier doesn't change during upgrade of the application. It can be matched with a value on the management console, for tracking and analysis. This identifier will be different: For the same application installed on different devices, even if installed for the same end user in the same deployment. For different applications installed on the same device. If the application is uninstalled and reinstalled. The identifier will change value if the end user is migrated from one management console instance to another. See also the GD_STATE_CONTAINER_MIGRATION_PENDING migration pending Intent Filter reference documentation.	String
GDAppConfigKeyCommunicationProtocols	Communication protocols allowed by the enterprise. A list of allowed and disallowed communication protocols can be set in the enterprise management console. The runtime will have retrieved the list, initially at activation time. The list is represented as a Map<String, Boolean> collection with the following keys: GDAndroid.GDProtocolsKeyTLSv1_0 GDAndroid.GDProtocolsKeyTLSv1_1 GDAndroid.GDProtocolsKeyTLSv1_2 The value in the collection for a particular key will be true if the corresponding protocol is allowed, and false otherwise. Some earlier versions of the management console software don't support this feature, and don't provide a list of allowed and disallowed protocols to the runtime. In that case, this element will be null instead of a collection.	Map<String, Boolean>
GDAppConfigKeyProtectedByPassword	BlackBerry Dynamics password enforcement. true if a password or other interactive authentication is enforced by BlackBerry Dynamics, false otherwise. See GDAndroid.canAuthorizeAutonomously for discussion.	Boolean
GDAppConfigKeyExtraInfo	Extra information sent by the management console. The management console can send extra information that isn't required for the operation of the BlackBerry Dynamics runtime but which might be of use to the application. For example, one or more additional identifiers for the end user could be included as extra information. The values will be encapsulated in a single JavaScript Object Notation (JSON) string. Some earlier versions of the management console software don't provide extra information. In that case, this element will be absent from the collection.	String

Data Leakage Policy Enforcement

The Data Leakage policy (DLP) mentioned in the above must generally be enforced by the application. Using the classes in the BlackBerry Dynamics Widget package can assist with enforcement. Other security policies are enforced by the BlackBerry Dynamics runtime, without reference to the application.

Application Server Selection

The GDAppConfigKeyServers value will contain a list of the servers that have been configured for the application in the enterprise management console. In the case that more than one server has been configured, the recommended selection algorithm is as follows:

1. For each priority value in the list, starting with the highest:
2. Select a server that has that priority, at random.
3. Attempt to connect to the server.
4. If connection succeeds, use that server.
5. If connection fails, try another server at the same priority, at random.
6. If there are no more untried servers at that priority, try the servers at the next lower priority.

See also

System administration tasks

java.util.Map on the android.com developer website.

The GD-Secure compliance document.

getApplicationPolicy()

Map<String, Object> getApplicationPolicy

(

)

throws GDNotAuthorizedError

This method returns a collection of application-specific policy settings. The settings will have been made in the management console, and retrieved by the BlackBerry Dynamics runtime.

For more documentation of the feature and how application policies are defined, see the Application Policies Definition documentation.

Retrieval of policy settings may happen during authorization processing, or whenever settings are changed. When changed settings have been retrieved by the runtime, a GDAppEventPolicyUpdate event will be dispatched to the application. See the GDAppEvent class reference for details, and see the notes under the Enterprise Configuration Information heading, above.

Note that retrieval of that latest policy from the management server is not triggered by calling this function.

Returns

Map<String,Object> containing policy settings.

The keys will be the same as the settings identifiers in the policy definition. The values will be the particular values that apply to the end user. The value types are mapped from the definition as follows.

Definition Type	Map Value Type
null	null
boolean	Boolean
double	Number
int	Number
object	Map<String,Object>
array	Vector<Object>
string	String

See also

GDAndroid.getApplicationPolicyString

getApplicationPolicyString()

String getApplicationPolicyString

(

)

throws GDNotAuthorizedError

This method returns application-specific policy settings in a JavaScript Object Notation (JSON) string. The settings will have been made in the management console, and retrieved by the BlackBerry Dynamics runtime.

For more documentation of the feature and how application policies are defined, see the Application Policies Definition documentation.

Retrieval of policy settings may happen during authorization processing, or whenever settings are changed. When changed settings have been retrieved by the runtime, a GDAppEventPolicyUpdate event will be dispatched to the application. See the GDAppEvent class reference for details, and see the notes under the Enterprise Configuration Information heading, above.

Note that retrieval isn't as such triggered by calling this function.

Returns

String containing policy settings in a JSON string. The string will evaluate to an object with an attribute for each application-specific setting. The names of the attributes will be the same as the settings identifiers in the policy definition. The attribute values will be the particular values that apply to the end user.

See also

GDAndroid.getApplicationPolicy

getServiceProviders()

Vector<GDServiceProvider> getServiceProviders

(

)

throws GDNotAuthorizedError

This method returns a list of all available providers of shared services. The list contains both application-based and server-based service providers.

The returned list is based on the BlackBerry Dynamics entitlement configuration in the enterprise management console and in the central BlackBerry Dynamics Catalog. An entitlement can correspond to an application, or can be a placeholder for something more abstract such as access to a feature or resource. In any case, entitlements have unique identifiers and versions.

The list includes an entry for each entitlement version that meets all the following conditions.

• The entitlement version is registered as the provider of one or more shared services, see notes on service provider registrations, below.
• The end user that activated the running application has been granted the entitlement version, i.e. they are entitled to the service provider.
• For entitlements that represent application-based service providers: the corresponding application has been installed and activated for the same end user, and on the same device or computer, as the current application.

Service provider registrations are stored within the BlackBerry Dynamics infrastructure, on a server known as the Catalog. Registrations are stored as relationships between entitlement versions and service identifiers. The user interface for registration administration is either the enterprise management console, or a website that can be reached via the application developer portal. The same user interfaces are used for the creation and administration of individual shared service definitions.

The runtime retrieves the information used to generate the list of service providers from the Catalog, and from the enterprise management console. Retrieval can take place when the application is authorized, or when another application activates on the same device, or when the configuration is changed in the enterprise management console. Note that retrieval isn't as such triggered by calling this method.

For each entitlement version that satisfies the above conditions, this method returns a GDServiceProvider object.

The returned details for an application-based provider can be used to send a service request to the service provider using BlackBerry Dynamics AppKinetics. See the icc package reference for details of the programming interface. See under Service Provider Requirements on that page for information on service provider registration, which is a prerequisite for an application to be on the list returned by this function.

The returned details for a server-based provider can be used to establish HTTP or TCP socket communications with a server instance.

Returns

Vector of GDServiceProvider objects containing the list of available service providers. The order of objects in the list is unspecified.

A single service could have multiple providers. A single provider could provide multiple services, and multiple versions of services.

When changed details have been retrieved by the runtime, a GDAppEventServicesUpdate event will be dispatched to the application. See the GDAppEvent class reference for details, and see the notes under the Enterprise Configuration Information heading, above.

Icon images

The objects returned by this method can include icon images for service provider applications. Utilization of icon images is optional. If the application does utilize icon images, then make a setting in the settings.json file in the assets/ folder of the application as follows.

"GDFetchResources": true

If the setting is missing or the value is false, this indicates that the application doesn't utilize icon images.

The data for icon images would be retrieved by the BlackBerry Dynamics runtime, from a BlackBerry Dynamics Catalog service. BlackBerry may switch off the icon image service at the Catalog from time to time, for operational reasons. If the icon image service is switched off then all icon images in the returned objects will be null.

getServiceProvidersFor()

Vector<GDServiceProvider> getServiceProvidersFor	(	String	serviceId,
		String	version,
		GDServiceType	serviceType
	)		throws GDNotAuthorizedError

This method returns a list of the available providers of a specified service.

The returned list is based on the BlackBerry Dynamics entitlement configuration in the enterprise management console and in the central BlackBerry Dynamics Catalog. The list includes an entry for each entitlement version that meets all the following conditions.

• The entitlement version would be on the list of service providers returned by the GDAndroid.getServiceProviders method, see above.
• The entitlement version is registered as a provider of the specified service.
• The entitlement version is registered as a provider of the specified service type, either server-based or application-based.
• The entitlement version is registered as a provider of the service version, if specified.

Parameters

serviceId	String specifying the identifier of the required service.
version	String specifying the required version of the service, or null to leave unspecified.
serviceType	GDServiceType value specifying the required type of service.

Returns

Vector of GDServiceProvider objects containing the list of available service providers. The order of objects in the list is unspecified.

See also the note on Icon images in the getServiceProviders method documentation, above.

getEntitlementVersions()

int getEntitlementVersions	(	String	identifier,
		GDEntitlementVersionsRequestCallback	callback
	)

Call this method to check whether the current end user has a specific BlackBerry Dynamics entitlement. The return value is a list of entitlement versions, which might be empty.

This method can be used to check for entitlement to:

• A specific BlackBerry Dynamics mobile or desktop application, identified by a BlackBerry Dynamics entitlement identifier.
• A more abstract entitlement, such as a feature, also identified by an entitlement identifier.

Note that there is a single namespace and format for entitlement identifiers, whether used for applications or for more abstract entitlements. All entitlements have versions, as well as identifiers. The syntax for entitlement identifiers and versions is detailed above, under the headings Entitlement Identifier Format and Entitlement Version Format. The syntax applies to all types of entitlement.

Specify the entitlement to be checked by passing its identifier as a parameter. The return value will be a list:

• If the end user doesn't have the specified entitlement, the list will have zero elements.
• Otherwise, the list will have one element for each version to which the end user is entitled. Each element will be a GDVersion object.

This method is asynchronous.

The result list is returned by invocation of a callback method in an observer object. Pass the observer object as a parameter to this method. The result list will be passed as a parameter to the callback invocation. If an error occurs and the entitlement cannot be checked, null will be passed instead of the list, and a numeric error code will be passed in another parameter to the callback.

This method can be called a second time without waiting for the results of a first call to be received. Results may be provided in any order, i.e. the callback could be invoked for a later call before or after being invoked for a first call. This method returns a value that can be used to match calls to results. The same value will also be passed to the asynchronous invocation of the results callback.

Calling this method can result in data communication with the BlackBerry Dynamics infrastructure.

Parameters

identifier	String containing the entitlement identifier.
callback	reference to the results observer, which must implement the GDEntitlementVersionsRequestCallback interface.

Returns

int containing a value that identifies this check and which will later be passed to the results callback.

The entitlements of the end user can change, for example if the user's group membership is changed at the enterprise management console. The BlackBerry Dynamics runtime is notified of these changes by the BlackBerry Dynamics infrastructure, and dispatches a GDAppEventEntitlementsUpdate event to the application. See the GDAppEvent class reference for details, and see the notes under the Enterprise Configuration Information heading, above.

configureUI()

void configureUI	(	final Drawable	smallApplicationLogo,
		final Drawable	bigApplicationLogo,
		final Integer	color
	)

Call this method to configure the visual appearance of the built-in BlackBerry Dynamics user interface. The following aspects can be configured:

• Logo images.
• Brand color, used for the key line and interactive elements.

This function can be called prior to authorize, in order to configure the user interface as displayed during authorization processing.

Parameters

smallApplicationLogo	Drawable for the image to show as the logo on the unlock screen and other places where a smaller logo is used. The image will be scaled to fit the screen, with aspect ratio preserved.
bigApplicationLogo	Drawable for the image to show as the logo on the welcome screen and other places where a larger logo is used. The image will be scaled to fit the screen, with aspect ratio preserved.
color	Integer for the brand color, or null to select the default.

See also

GDAndroid.authorize for details of which BlackBerry Dynamics user interface elements may be shown during authorization processing.

android.graphics.Color on the android.com developer website for a programming interface to generate integer values for colors.

getGDSharedPreferences()

SharedPreferences getGDSharedPreferences	(	String	name,
		int	mode
	)

Call this method to access a preferences file stored in the BlackBerry Dynamics secure store.

This method returns a SharedPreferences object that can be used to take actions on the preferences file, such as reading and editing preference settings. The returned object implements the android.content.SharedPreferences interface with the following exceptions:

• Only the application that created the preferences file can access it. The only supported operating mode is MODE_PRIVATE.
• The preferences file can only be accessed after BlackBerry Dynamics authorization processing has completed.

See the android.content.SharedPreferences interface reference on android.com for details of the API.

Multiple preference files can be created, with different names. The preferences file name is specified as a parameter to this method. If a preferences file with the specified name doesn't exist at the time this method is called, an object reference is still returned. If an editor commit action is taken on the returned object, a new preferences file will be created, in the secure store.

Parameters

name	String containing the name of the preferences file.
mode	int specifying the operating mode of the preferences file, which must be MODE_PRIVATE.

Returns

android.content.SharedPreferences instance that can be used to access preferences.

See also

android.content.Context.getSharedPreferences method reference on android.com

getAuthDelegate()

GDAuthDelegateInfo getAuthDelegate

(

)

Call this method to get an AuthDelegateInfo object containing details of the application to which this application has delegated its authentication. If there is no such delegated application, GDAuthDelegateInfo.isAuthenticationDelegated() will be false.

When openChangePasswordUI() returns false, indicating that authentication has been delegated, this method may be used to obtain information to display to the user.

registerReceiver()

void registerReceiver	(	BroadcastReceiver	receiver,
		IntentFilter	filter
	)

Call this method to register for specific notifications sent by local broadcast. In this release of the BlackBerry Dynamics SDK for Android, the following types of notification are sent by local broadcast:

• Change of network connection status.
• Change of Push Channel service availability.
• Messages, errors, and state changes on individual Push Channel connections.
• Change of authorization state.
• Change to application configuration and other settings from the enterprise.
• Change to the application-specific policy settings of the current end user.
• Change to services-related configuration.
• Change to the entitlements of the end user.
• Results on the re-authentication attempts.

See:

• GDNetworkInfo class reference for details of the network connection status and Push Channel service availability notification, and sample code.
• PushChannel class reference for details of notifications on individual Push Channel connections.
• GDStateAction class reference for details of other notifications.

This programming interface makes use of the following native classes:

• BroadcastReceiver: notifications will be dispatched to a BroadcastReceiver in the application code.
• IntentFilter, to specify the types of notification to dispatch to a particular receiver.

The receiver will be run on the main thread of the application. Long-running processing generally shouldn't be run on the main thread. If the receiver processing is long-running then the receiver should spawn a new thread, or use some other mechanism to cause the processing to take place on a thread other than the main thread.

This method can be called before authorization is complete, but not before one of the following has been called.

• GDAndroid.applicationInit.
• GDAndroid.authorize.
• GDAndroid.activityInit.

Parameters

receiver	BroadcastReceiver that will receive broadcasts.
filter	IntentFilter that specifies the types of notification to send to the receiver.

See also

BroadcastReceiver on the android.com developer website.

IntentFilter on the android.com developer website.

unregisterReceiver()

void unregisterReceiver

(

BroadcastReceiver

receiver

)

Call this method to remove a previously registered receiver of local broadcasts. The receiver is specified as a parameter.

The specified receiver will not receive any more local broadcasts from the BlackBerry Dynamics runtime, for any type of notification.

Parameters

receiver

BroadcastReceiver representing the receiver to remove.

executeBlock()

static void executeBlock ( String  blockId, String  title, String  message  )

static

Call this method to block use of the application, as though a remote block had been received from the enterprise management console. Include a title and description to inform the user what threat or action has triggered the block. If several blocks have been applied then it is the most recent block which will be displayed to the user in the block screen.

While blocked, the application can utilize the principal Dynamics APIs like secure storage and secure communications.

Blocks are persisted which means that after an application is restarted and the user is authenticated the block screen will be displayed. In addition a GDAppEvent with the result code GDErrorBlocked would be dispatched. This event would be received for blocks applied locally with this method and those applied from the management console.

The application should persist in secure storage the blockId called in this method. When a GDErrorBlocked event is received the application should check if any blocks are applied locally and determine if the block can now be removed.

Parameters

blockId	String specifying the block identifier. This identifier is required to subsequently remove the block.
title	String containing the title shown on the block screen.
message	String containing the detailed message to display on the block screen.

executeUnblock()

static void executeUnblock ( String  blockId )

static

Call this method to remove a block screen with associated blockId. Other local or remote blocks will still leave the application blocked. Blocks applied by the management console cannot be unblocked using this method.

Parameters

blockId

String specifying the block identifier.

executeRemoteLock()

static void executeRemoteLock ( )

static

Call this method to lock the application permanently, as though a remote lock-out had been received from the enterprise management console. The application data will become inaccessible but won't be erased.

A remote lock-out is, in effect, a withdrawal of the end user's authorization to utilise the application. The user cannot unlock the application in the normal way, for example they cannot enter their BlackBerry Dynamics password, if a remote lock-out is in place. Instead, a special unlock code must be obtained from the management console, and entered in the remote unlock BlackBerry Dynamics user interface.

See also

GDAppEvent class reference, which mentions the GDErrorRemoteLockout result code. An event with that result code would be dispatched if a remote lock-out command was received from the management console.

executePendingConsoleMigration()

static boolean executePendingConsoleMigration ( String  destinationTenantID, String  uemServerAddress  )

static

Returns

true if destinationTenantID is provided

false if destinationTenantID is empty

Call this method to execute a migration of the application to the specified management console. This should only be called by an application that has been informed by the management console that a migration request is pending. If a migration request is not pending calling this method may result in the container being wiped.

Parameters

destinationTenantID	String specifying the tenant identifier of the UEM management console.
uemServerAddress	String containing the URL for UEM enrollment service.

Member Data Documentation

GDAppConfigKeyServers

final String GDAppConfigKeyServers = GDAndroidAPI.GDAppConfigKeyServers

static

See under getApplicationConfig.

GDAppConfigKeyConfig

final String GDAppConfigKeyConfig = GDAndroidAPI.GDAppConfigKeyConfig

static

See under getApplicationConfig.

GDAppConfigKeyPreventDataLeakageOut

final String GDAppConfigKeyPreventDataLeakageOut = GDAndroidAPI.GDAppConfigKeyPreventDataLeakageOut

static

See under getApplicationConfig.

GDAppConfigKeyPreventDataLeakageIn

final String GDAppConfigKeyPreventDataLeakageIn = GDAndroidAPI.GDAppConfigKeyPreventDataLeakageIn

static

See under getApplicationConfig.

GDAppConfigKeyPreventAndroidDictation

final String GDAppConfigKeyPreventAndroidDictation = GDAndroidAPI.GDAppConfigKeyPreventAndroidDictation

static

See under getApplicationConfig.

GDAppConfigKeyPreventAndroid3rdPartyKeyboards

final String GDAppConfigKeyPreventAndroid3rdPartyKeyboards = GDAndroidAPI.GDAppConfigKeyPreventAndroid3rdPartyKeyboards

static

See under getApplicationConfig.

GDAppConfigKeyPreventScreenCapture

final String GDAppConfigKeyPreventScreenCapture = GDAndroidAPI.GDAppConfigKeyPreventScreenCapture

static

See under getApplicationConfig.

GDAppConfigKeyInstanceIdentifier

final String GDAppConfigKeyInstanceIdentifier = GDAndroidAPI.GDAppConfigKeyInstanceIdentifier

static

See under getApplicationConfig.

GDAppConfigKeyDetailedLogsOn

final String GDAppConfigKeyDetailedLogsOn = GDAndroidAPI.GDAppConfigKeyDetailedLogsOn

static

See under getApplicationConfig.

GDAppConfigKeyPreventUserDetailedLogs

final String GDAppConfigKeyPreventUserDetailedLogs = GDAndroidAPI.GDAppConfigKeyPreventUserDetailedLogs

static

See under getApplicationConfig.

GDAppConfigKeyUserId

final String GDAppConfigKeyUserId = GDAndroidAPI.GDAppConfigKeyUserId

static

See under getApplicationConfig.

GDAppConfigKeyUserPrincipalName

final String GDAppConfigKeyUserPrincipalName = GDAndroidAPI.GDAppConfigKeyUserPrincipalName

static

See under getApplicationConfig.

GDAppConfigKeyProtectedByPassword

final String GDAppConfigKeyProtectedByPassword = GDAndroidAPI.GDAppConfigKeyProtectedByPassword

static

See under getApplicationConfig.

GDAppConfigKeyExtraInfo

final String GDAppConfigKeyExtraInfo = GDAndroidAPI.GDAppConfigKeyExtraInfo

static

See under getApplicationConfig.

GDAppEnterpriseIdActivated

final String GDAppEnterpriseIdActivated = GDAndroidAPI.GDAppEnterpriseIdActivated

static

See under getApplicationConfig.

GDAppConfigKeyEnterpriseIdFeatures

final String GDAppConfigKeyEnterpriseIdFeatures = GDAndroidAPI.GDAppConfigKeyEnterpriseIdFeatures

static

See under getApplicationConfig.

GDAppConfigKeyCommunicationProtocols

final String GDAppConfigKeyCommunicationProtocols = GDAndroidAPI.GDAppConfigKeyCommunicationProtocols

static

See under getApplicationConfig.