• BlackBerry Dynamics
  • Runtime library for Android applications
  • 7.1.0.192
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.

StateDescriptionGDStateListener
callback
GDAppEvent
type value
Not authorizedInitial state.
The application can initiate authorization, but cannot utilize the principal interfaces.
AuthorizedEither 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.
onAuthorizedGDAppEventAuthorized
LockedAuthorization of the user has been temporarily withdrawn, for example due to inactivity.
User interaction is blocked. The application can still utilize the principal interfaces.
onLockedGDAppEventNotAuthorized
WipedAuthorization 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.
onWipedGDAppEventNotAuthorized
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...
 
void programmaticActivityInit (android.app.Activity activity, String userID, String accessKey)
 Initiate programmatic activation (deprecated) More...
 
void programmaticActivityInit (android.app.Activity activity, String userID, String accessKey, URL nocAddress)
 Initiate programmatic activation (deprecated) 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 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< GDServiceProvidergetServiceProviders () throws GDNotAuthorizedError
 Get providers of shared services. More...
 
Vector< GDServiceProvidergetServiceProvidersFor (String serviceId, String version, GDServiceType serviceType) throws GDNotAuthorizedError
 Discover providers of a specific shared service. More...
 
Vector< GDServiceProvidergetServiceProvidersFor (String serviceId, String version, GDServiceProviderType serviceProviderType) throws GDNotAuthorizedError
 Discover providers of a specific shared service (deprecated). 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...
 
void configureUIWithBlockedMessage (final String message)
 Customize the BlackBerry Dynamics blocked screen (deprecated). More...
 
void configureUIWithWipedMessage (final String message)
 Customize the BlackBerry Dynamics wiped screen (deprecated). 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)
 Executes migration of the application to a different management console. More...
 

Static Public Attributes

static final String GDAppConfigKeyServers = "appServers"
 Constant key value for application server configuration. More...
 
static final String GDAppConfigKeyConfig = "appConfig"
 Constant key value for application-specific configuration data. More...
 
static final String GDAppConfigKeyPreventDataLeakageOut = "copyPasteOn"
 Constant key value for the outbound Data Leakage security policy indicator. More...
 
static final String GDAppConfigKeyPreventDataLeakageIn = "preventPasteFromNonGDApps"
 Constant key value for the inbound Data Leakage security policy indicator. More...
 
static final String GDAppConfigKeyPreventAndroidDictation = "preventAndroidDictation"
 Constant key value for allowing or disallowing use of dictation. More...
 
static final String GDAppConfigKeyPreventScreenCapture = "preventScreenCapture"
 Constant key value for allowing or disallowing screen capture. More...
 
static final String GDAppConfigKeyInstanceIdentifier = "containerId"
 Constant key value for application instance identifier. More...
 
static final String GDAppConfigKeyCopyPasteOn = "copyPasteOn"
 Deprecated constant key value for Data Leakage security policy indicator. More...
 
static final String GDAppConfigKeyDetailedLogsOn = "detailedLogsOn"
 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 = "preventUserDetailedLogs"
 Constant key value for whether the end user is allowed to switch on detailed logging. More...
 
static final String GDAppConfigKeyUserId = "userId"
 Constant key value for the user's enterprise email address. More...
 
static final String GDAppConfigKeyUserPrincipalName = "upn"
 Constant key value for the user's User Principal Name (UPN). More...
 
static final String GDAppConfigKeyProtectedByPassword = "protectedByPassword"
 Constant key value for whether the application is protected by a BlackBery Dynamics password. More...
 
static final String GDAppConfigKeyExtraInfo = "extraInfo"
 Constant key value for extra information from the management console. More...
 
static final String GDAppEnterpriseIdActivated = "enterpriseIdActivated"
 Constant key value for whether BlackBerry Enterprise Identity is setup. More...
 
static final String GDAppConfigKeyEnterpriseIdFeatures = "enterpriseIdFeatures"
 Constant key value containing a JSON array of available features. More...
 
static final String GDAppConfigKeyCommunicationProtocols = "communicationProtocols"
 Constant key value for the list of communications protocols allowed by the enterprise. More...
 
static final String GDProtocolsKeyTLSv1_0 = "TLSv1"
 Constant value for a secure communication protocol: TLS version 1.0. See under GDAndroid.getApplicationConfig.
 
static final String GDProtocolsKeyTLSv1_1 = "TLSv1.1"
 Constant value for a secure communication protocol: TLS version 1.1. See under GDAndroid.getApplicationConfig.
 
static final String GDProtocolsKeyTLSv1_2 = "TLSv1.2"
 Constant value for a secure communication protocol: TLS version 1.2. See under GDAndroid.getApplicationConfig.
 
static final String GDAppConfigKeyAndroidKeyboardRestrictedMode = "keyboardRestrictedMode"
 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
activitythe android.app.Activity instance associated with the activity that is being registered, typically this.
Exceptions
GDInitializationErrorif 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:

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

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
contextAndroid Context object for the application, typically this to pass a reference to the android.app.Application instance.
Exceptions
GDInitializationErrorif 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
stateListenerthe observer, which must implement the GDStateListener interface.
Exceptions
GDInitializationErrorif 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
eventListenerthe 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
eventListenerthe 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 KeyValue
GDApplicationIDBlackBerry 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.
GDApplicationVersionBlackBerry 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
GDInitializationErrorif the BlackBerry Dynamics runtime encountered an error during initialization.

◆ programmaticActivityInit() [1/3]

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

◆ programmaticActivityInit() [2/3]

void programmaticActivityInit ( android.app.Activity  activity,
String  userID,
String  accessKey 
)
Deprecated:
This method is deprecated and will be removed in a future release. Please use the latest version of GDAndroid.programmaticActivityInit.

Calling this method is equivalent to calling the form with an additional URL parameter, see below, and specifying the URL of the default production Network Operation Center.

◆ programmaticActivityInit() [3/3]

void programmaticActivityInit ( android.app.Activity  activity,
String  userID,
String  accessKey,
URL  nocAddress 
)
Deprecated:
This method is deprecated and will be removed in a future release. Please use the latest version of GDAndroid.programmaticActivityInit.

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.

Parameters
activityandroid.app.Activity instance associated with the activity that is being registered, typically this. The activity must be in foreground when this method is called.
userIDString containing the first enterprise activation credential: the user identifier. This is typically the enterprise email address of the end user.
accessKeyString containing the second enterprise activation credential: the access key.
nocAddressjava.net.URL containing a NOC server address, or an alias. The URL must always include a scheme, such as https.

◆ 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
contextAndroid 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
GDInitializationErrorif 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
GDInitializationErrorif 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.

Returns
true if the user interface element opened OK, or was already open.
false if authorization is delegated to another application, or if this application is in the Wiped state.
Exceptions
com.good.gd.error.GDNotAuthorizedErrorif 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.GDNotAuthorizedErrorif 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.GDNotAuthorizedErrorif 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
contextAndroid 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

GDAppConfigKeyCopyPasteOn (deprecated) This key is deprecated and will be removed in a future release. Use the GDAppConfigKeyPreventDataLeakageOut key instead.

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: 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 class reference on android.com
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 TypeMap Value Type
nullnull
booleanBoolean
doubleNumber
intNumber
objectMap<String,Object>
arrayVector<Object>
stringString
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() [1/2]

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
serviceIdString specifying the identifier of the required service.
versionString specifying the required version of the service, or null to leave unspecified.
serviceTypeGDServiceType 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.

◆ getServiceProvidersFor() [2/2]

Vector<GDServiceProvider> getServiceProvidersFor ( String  serviceId,
String  version,
GDServiceProviderType  serviceProviderType 
) throws GDNotAuthorizedError
Deprecated:
This method is deprecated and will be removed in a future release. Instead use the form in which the last parameter is GDServiceType, not GDServiceProviderType.

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
serviceIdString specifying the identifier of the required service.
versionString specifying the required version of the service, or null to leave unspecified.
serviceProviderTypeGDServiceProviderType 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
identifierString containing the entitlement identifier.
callbackreference 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
smallApplicationLogoDrawable 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.
bigApplicationLogoDrawable 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.
colorInteger 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 class reference on android.com 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
nameString containing the name of the preferences file.
modeint 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

◆ configureUIWithBlockedMessage()

void configureUIWithBlockedMessage ( final String  message)
Deprecated:
This method is deprecated and will be removed in a future release.

Call this method to configure the BlackBerry Dynamics blocked screen. The blocked screen can be configured to display a custom message instead of the default message that is built in to the BlackBerry Dynamics runtime user interface.

The message will be shown in the following case:

  • If a remote container management command to block the user interface has been received.

This function can be called prior to the completion of authorization processing.

Parameters
messageString containing the custom message text, or null to select the default.

◆ configureUIWithWipedMessage()

void configureUIWithWipedMessage ( final String  message)
Deprecated:
This method is deprecated and will be removed in a future release.

Call this method to configure the BlackBerry Dynamics wiped screen. The wiped screen can be configured to display a custom message instead of the default message that is built in to the BlackBerry Dynamics runtime user interface.

The message will be shown in the following case:

  • If a remote container management command to wipe the application has been received.

This function can be called prior to the completion of authorization processing.

Parameters
messageString containing the custom message text, or null to select the default.

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

Parameters
receiverBroadcastReceiver that will receive broadcasts.
filterIntentFilter that specifies the types of notification to send to the receiver.
See also
BroadcastReceiver class reference on the android.com website.
IntentFilter class reference on the android.com 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
receiverBroadcastReceiver 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
blockIdString specifying the block identifier. This identifier is required to subsequently remove the block.
titleString containing the title shown on the block screen.
messageString 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
blockIdString 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)
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
destinationTenantIDString specifying the tenant identifier of the UEM management console.

Member Data Documentation

◆ GDAppConfigKeyServers

final String GDAppConfigKeyServers = "appServers"
static

◆ GDAppConfigKeyConfig

final String GDAppConfigKeyConfig = "appConfig"
static

◆ GDAppConfigKeyPreventDataLeakageOut

final String GDAppConfigKeyPreventDataLeakageOut = "copyPasteOn"
static

◆ GDAppConfigKeyPreventDataLeakageIn

final String GDAppConfigKeyPreventDataLeakageIn = "preventPasteFromNonGDApps"
static

◆ GDAppConfigKeyPreventAndroidDictation

final String GDAppConfigKeyPreventAndroidDictation = "preventAndroidDictation"
static

◆ GDAppConfigKeyPreventScreenCapture

final String GDAppConfigKeyPreventScreenCapture = "preventScreenCapture"
static

◆ GDAppConfigKeyInstanceIdentifier

final String GDAppConfigKeyInstanceIdentifier = "containerId"
static

◆ GDAppConfigKeyCopyPasteOn

final String GDAppConfigKeyCopyPasteOn = "copyPasteOn"
static
Deprecated:
This key is deprecated and will be removed in a future release. Use the GDAppConfigKeyPreventDataLeakageOut value instead.

See under getApplicationConfig.

◆ GDAppConfigKeyDetailedLogsOn

final String GDAppConfigKeyDetailedLogsOn = "detailedLogsOn"
static

◆ GDAppConfigKeyPreventUserDetailedLogs

final String GDAppConfigKeyPreventUserDetailedLogs = "preventUserDetailedLogs"
static

◆ GDAppConfigKeyUserId

final String GDAppConfigKeyUserId = "userId"
static

◆ GDAppConfigKeyUserPrincipalName

final String GDAppConfigKeyUserPrincipalName = "upn"
static

◆ GDAppConfigKeyProtectedByPassword

final String GDAppConfigKeyProtectedByPassword = "protectedByPassword"
static

◆ GDAppConfigKeyExtraInfo

final String GDAppConfigKeyExtraInfo = "extraInfo"
static

◆ GDAppEnterpriseIdActivated

final String GDAppEnterpriseIdActivated = "enterpriseIdActivated"
static

◆ GDAppConfigKeyEnterpriseIdFeatures

final String GDAppConfigKeyEnterpriseIdFeatures = "enterpriseIdFeatures"
static

◆ GDAppConfigKeyCommunicationProtocols

final String GDAppConfigKeyCommunicationProtocols = "communicationProtocols"
static