BlackBerry Dynamics runtime object interface, including authorization. More...
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.
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:
authorize
, which is direct initiation.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.
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 | GDApp Event 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:
An authorized application may change an authorization state to 'locked' and prompt the user to reauthenticate by using Reauthenticate .
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:
GDStateListener
interface, which implicitly sets the activity instance as its own observer object.setGDSt
ateListener()
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 autho
rize()
call, or by calling the setGDAppEv
entListener()
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 GDStateL
istener
nor GDAppEv
entListener
, 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.
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.
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.
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.
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:
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.
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:
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.
See the icc package reference for details of shared services.
The syntax rules of entitlement version values are as follows.
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.
See the Application User Interface Restrictions page.
See the Build-Time Configuration page.
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:
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.
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.
The following code snippets illustrate some common tasks.
The following snippet shows indirect initiation of BlackBerry Dynamics authorization processing, and implicit setting of the authorization state transition observer.
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.
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.
The following snippet shows explicit setting of a singleton object as the authorization state transition observer.
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.
The following snippet shows direct initiation of BlackBerry Dynamics authorization processing.
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.
The following snippet shows configuration of Programmatic Activation using ActivationSetting
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... | |
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. | |
|
static |
This method returns a reference to the BlackBerry Dynamics runtime object.
The BlackBerry Dynamics runtime object is a "singleton class".
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 Acti
vity
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.
android.app.Fragment
instance) to the associated activity at run time.onAttachFragment
callback of the Acti
vity
instance will be invoked when this method is called.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.activity | the android.app.Activity instance associated with the activity that is being registered, typically this . |
GDInitializationError | if a subclass of a BlackBerry Dynamics activity replacement class is passed as the parameter. |
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:
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.
context | android.app.Service instance associated with the background service, typically this . |
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.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. |
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.
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.
context | Android Context object for the application, typically this to pass a reference to the android.app.Application instance. |
GDInitializationError | if the parameter is null or otherwise invalid. |
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.
stateListener | the observer, which must implement the GDStateListener interface. |
GDInitializationError | if an Activity is passed as the observer. |
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.
eventListener | the observer object, which must implement the GDAppEventListener interface. |
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.
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 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.
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.
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.
The runtime checks for compliance with the most up-to-date policies every time authorization is processed.
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.
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.
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.
GDInitializationError | if the BlackBerry Dynamics runtime encountered an error during initialization. |
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
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.
context | Android Context object for the application. |
true
if the application has been activated. false
otherwise. 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.
String
containing the entitlement identifier.GDInitializationError | if called before authorization processing has been initiated. |
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.
String
containing the entitlement version.GDInitializationError | if called before authorization processing has been initiated. |
|
static |
String
containing the BlackBerry Dynamics runtime library version in major.
minor.
build format. 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.
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.com.good.gd.error.GDNotAuthorizedError | if BlackBerry Dynamics authorization processing has not yet completed. |
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.
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.com.good.gd.error.GDNotAuthorizedError | if BlackBerry Dynamics authorization processing has not yet completed. |
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.
true
if the user interface element opened OK, or was already open. false
if this application is in the Wiped state.com.good.gd.error.GDNotAuthorizedError | if BlackBerry Dynamics authorization processing has not yet completed. |
boolean supportsFingerprintAuthentication | ( | ) | throws GDNotAuthorizedError |
Call this method to check whether BlackBerry Dynamics fingerprint authentication is currently available.
Fingerprint authentication will be available if:
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.
true
if fingerprint authentication is available. false
otherwise.com.good.gd.error.GDNotAuthorizedError | if BlackBerry Dynamics authorization processing has not yet completed. |
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.
context | Android Context object for the application. |
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. 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.
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. |
|
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. |
|
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. |
|
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. |
|
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. |
|
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. |
|
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. |
|
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. |
|
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. |
|
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. |
|
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:
|
|
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. |
|
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. |
|
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. |
|
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: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.
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 |
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.
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.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.
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.
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.
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.
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
.
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.
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. |
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.
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:
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:
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.
identifier | String containing the entitlement identifier. |
callback | reference to the results observer, which must implement the GDEntitlementVersionsRequestCallback interface. |
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.
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:
This function can be called prior to authorize
, in order to configure the user interface as displayed during authorization processing.
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. |
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:
MODE_PRIVATE
.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.
name | String containing the name of the preferences file. |
mode | int specifying the operating mode of the preferences file, which must be MODE_PRIVATE . |
android.content.SharedPreferences
instance that can be used to access preferences. 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:
See:
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.
receiver | BroadcastReceiver that will receive broadcasts. |
filter | IntentFilter that specifies the types of notification to send to the receiver. |
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.
receiver | BroadcastReceiver representing the receiver to remove. |
|
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.
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. |
|
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.
blockId | String specifying the block identifier. |
|
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.
GDErrorRemoteLockout
result code. An event with that result code would be dispatched if a remote lock-out command was received from the management console.
|
static |
true
if destinationTenantID is provided false
if destinationTenantID is emptyCall 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.
destinationTenantID | String specifying the tenant identifier of the UEM management console. |
uemServerAddress | String containing the URL for UEM enrollment service. |
|
static |
See under getApplicationConfig.
|
static |
See under getApplicationConfig.
|
static |
See under getApplicationConfig.
|
static |
See under getApplicationConfig.
|
static |
See under getApplicationConfig.
|
static |
See under getApplicationConfig.
|
static |
See under getApplicationConfig.
|
static |
See under getApplicationConfig.
|
static |
See under getApplicationConfig.
|
static |
See under getApplicationConfig.
|
static |
See under getApplicationConfig.
|
static |
See under getApplicationConfig.
|
static |
See under getApplicationConfig.
|
static |
See under getApplicationConfig.
|
static |
See under getApplicationConfig.
|
static |
See under getApplicationConfig.
|
static |
See under getApplicationConfig.