Introduction

The Android operating system has a feature that automatically backs up application data from the mobile device to an Internet service operated by Google. This feature, Auto Backup, is configurable at build-time. Android applications that target API level 23 or later will be configured, by default, to back up all application data automatically.

The default Auto Backup configuration interferes with the normal secure functioning of BlackBerry Dynamics and can't be used in BlackBerry Dynamics applications. Instead, BlackBerry Dynamics applications must include an explicit Auto Backup configuration that is compatible with normal secure functioning, or must switch off the Auto Backup feature.

There is also an earlier Android feature for backing up application data, known as Key/Value Backup or Backup Agent. This feature isn't configured by default.

See also: Data backup overview on the android.com developer website, for a guide to the native back-up features.

Compatible Android Auto Backup Configuration

An Android Auto Backup configuration that is compatible with BlackBerry Dynamics can be created by using the Backup Support Library. The library is included with the BlackBerry Dynamics software development kit (SDK) for Android. It includes a custom back-up scheme for applications. The scheme can be extended as required.

The library can be utilized in an application as follows.

Add the library files into the application project.
The library is part of the BlackBerry Dynamics SDK for Android. It is installed in the libs/handheld/gd_backup_support/ sub-directory of the BlackBerry Dynamics SDK for Android's main installation location. By default this will be:
$ANDROID_SDK_ROOT/sdk/extras/good/dynamics_sdk/libs/handheld/gd_backup_support/

One way to add the library would be to add lines like the following to the application settings.gradle file.
include 'BlackBerryDynamicsLibrary_BackupSupport'

project(':BlackBerryDynamicsLibrary_BackupSupport').projectDir =

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

Another way to include the library would be to import it as a module, which would make a local copy within the application project.
Include the library in the application build.
The library can be included in the application build by adding the following to the build.gradle file.
compile project(':BlackBerryDynamicsLibrary_BackupSupport')

This will include a back-up scheme configuration file gd_backup_scheme.xml, in the application resources.
Extend the back-up scheme as required.
The back-up scheme can be extended with any rules required by the application. The following rules mustn't be removed from the scheme, nor overriden:
<exclude domain="root" path="app_data/.DContainer/.gdstartupdata"/>

<exclude domain="root" path="app_data/.DContainer/.gdstartupdata2"/>

These rules specify that two files, the start-up data files, aren't backed up.

The scheme could instead be created manually, instead of by adding the library. The scheme would have to apply the above rules.
Add the scheme to the manifest.
To apply the back-up scheme to the application, add it to the AndroidManifest.xml file. Add the following two attributes to the application tag.
android:allowBackup="true"

android:fullBackupContent="@xml/gd_backup_scheme"

The whole tag could look like the following, for example:
<application

android:name=".AppKineticsApplication"

android:icon="@drawable/ic_launcher"

android:label="@string/app_name"

android:theme="@style/Theme.GDSampleAppTheme"

android:uiOptions="splitActionBarWhenNarrow"

android:allowBackup="true"

android:fullBackupContent="@xml/gd_backup_scheme" >

These instructions will create a compatible and extensible Android Auto Backup configuration.

See also: The AppKinetics sample application project that comes with the BlackBerry Dynamics SDK for Android for an example.

Switching off Android Auto Backup

An alternative to creating a compatible configuration for Android Auto Backup is to switch the feature off. This alternative can only be used in an application that doesn't utilize Android Auto Backup.

Android Auto Backup can be switched off in the application AndroidManifest.xml file, in the application tag, by inserting the following attribute.

android:allowBackup="false"

See also: The SecureCopyPaste sample application project that comes with the BlackBerry Dynamics SDK for Android for an example.

Enforcement

The compatibility of a BlackBerry Dynamics application's Android Auto Backup utilization is checked when it executes, by the BlackBerry Dynamics runtime. If the feature is in use in an incompatible way then the runtime will fail authorization of the end user, and throw a GDInitializationError.

Incompatible usage would be:

One or more of the start-up data files is in a domain that is included in Auto Backup.
One or more of the start-up data files isn't in a domain that is excluded from Auto Backup.

Android API Levels

An application that is created with a target API level of 23 or higher will have the Android Auto Backup feature switched on by default. The feature must be configured or switched off, as described above.

Applications can use the earlier back-up feature, Backup Agent, instead of using Auto Backup. BlackBerry Dynamics is compatible with Backup Agent. To utilize it:

Include code for a compatible FileBackupHelper implementation.
Include an android:backupAgent setting in the manifest file.

See the GDFileBackupHelper class reference for how to implement a compatible helper.

An application can be configured to use either Auto Backup or Backup Agent at run time, depending on which is provided at the API level of the device. Current BlackBerry Dynamics only supports devices with an API level that provides Auto Backup. The configuration can still be used and would be made in the AndroidManifest.xml file, in the application tag, by including an android:fullBackupOnly="true" setting. The Backup Agent implementation is then ignored and Auto Backup is used instead, on a device of API level 23 or higher.

Use Cases

The following use cases illustrate how the native and BlackBerry Dynamics features can be used.

Back up nothing

To back up none of a BlackBerry Dynamics application's data nor settings:

Switch off all back-up features in the application AndroidManifest.xml file, in the application tag, by inserting an android:allowBackup="false" setting.

Back up everything

To back up all of a BlackBerry Dynamics application's data and settings:

Create a back-up scheme that includes everything except the start-up data, by following the instructions under Compatible Android Auto Backup Configuration, above.
Apply the scheme to the application, by adding it to the AndroidManifest.xml file. Add attributes like the following to the application tag:
android:allowBackup="true"

android:fullBackupContent="@xml/gd_backup_scheme"
Or implement a Backup Agent that is a subclass of GDFileBackupHelper and apply it in the application manifest.

Back up selected files from outside the secure store

To back up selected files from outside the secure store, such as the Google Cloud Messaging Key file:

Create a back-up scheme that includes only the required files and excludes everything else.
Apply the scheme to the application, by adding it to the AndroidManifest.xml file. Add attributes like the following to the application tag:
android:allowBackup="true"

android:fullBackupContent="@xml/custom_backup_scheme"
Or implement a Backup Agent that isn't a subclass of GDFileBackupHelper and apply it in the application manifest.

Back up selected files from the secure store

This use case isn't supported by the current release of the BlackBerry Dynamics SDK for Android. If the application implements a GDFileBackup subclass that backs up any files from within the secure store, then the whole secure store will be backed up.

Table of Contents