Offline-Enable Your Android Application

1. Follow the instructions at Try Out the SAP BTP SDK Wizard for Android to create a new application using the SAP BTP SDK Wizard for Android and select Offline for the OData option on the Project Features tab. The push feature is not needed for this application.

   

2. Run the app. After the login process, a screen is displayed explaining that the offline store is opening. As the screen suggests, opening the offline store for the first time can take up to a few minutes. One technique to decrease this initial time is to only download data that is relevant to the user, such as customers that belong in their sales region.

   

3. When you get to the app’s home page, turn on Airplane mode on your device, or disable Wi-Fi and data.

   

4. The entity list screen is populated based on the metadata.xml file retrieved when the application was created. Tap the Products list item.

   

   The Products screen makes a data request to display the available products. Notice that it succeeds without a working network connection. The data request is fulfilled from the offline store that was previously created and populated on the device. Tap the Accessories item to display the detail screen.

   

5. On the detail screen, tap the edit toolbar icon.

   

6. Make a change to the currency code and tap the save toolbar icon.

   

7. Navigate back to the app’s Home screen and tap Synchronize using the three-dot-menu in the top right of the title bar.

   

   The sync should fail because you haven’t turned airplane mode off yet.

   

8. Turn off airplane mode or re-enable Wi-Fi/data and attempt a sync again. You will see a notification that describes the sync action.

   

   When the sync completes, the change you made will have been applied to the back end.

To protect the data in offline store, you must enable offline store encryption by supplying an encryption key.

1. In Android Studio, on Windows, press Ctrl+N, or on a Mac, press command+O, and type OfflineWorkerUtil, to open OfflineWorkerUtil.kt.

2. On Windows, press Ctrl+F12, or on a Mac, press command+F12, and type initializeOffline, to move to the initializeOffline method. Call the setter of storeEncryptionKey method of the OfflineODataParameters instance to encrypt the offline store. In single user mode, before you can get the encryption key using UserSecureStoreDelegate, you must generate and save an encryption key to UserSecureStore first.

   Kotlin

   Copy

   val encryptionKey = if (runtimeMultipleUserMode) {
       UserSecureStoreDelegate.getInstance().getOfflineEncryptionKey()
   } else { //If is single user mode, create and save a key into user secure store for accessing offline DB
       if (UserSecureStoreDelegate.getInstance().getData<String>(OFFLINE_DATASTORE_ENCRYPTION_KEY) == null) {
           val bytes = ByteArray(32)
           val random = SecureRandom()
           random.nextBytes(bytes)
           val key = Base64.encodeToString(bytes, Base64.NO_WRAP)
           UserSecureStoreDelegate.getInstance().saveData(OFFLINE_DATASTORE_ENCRYPTION_KEY, key)
           Arrays.fill(bytes, 0.toByte())
           key
       } else {
           UserSecureStoreDelegate.getInstance().getData<String>(OFFLINE_DATASTORE_ENCRYPTION_KEY)
       }
   }
   storeEncryptionKey = encryptionKey
   

For additional information about multiple user mode, see Enable Multi-User Mode for Your Android Application.

val customersQuery = OfflineODataDefiningQuery("Customers", "Customers", false)
val productsQuery = OfflineODataDefiningQuery("Products", "Products", true)

Defining queries tell the OfflineODataProvider (the class that manages the offline store) which entity sets to store on the device. In the case of the wizard-generated application, there is a defining query for each available entity by default, meaning that each entity is stored offline and available if the user doesn’t have an internet connection. For more information, see Defining Queries.

With an offline-enabled app, requests made against the entity sets that are included in the defining requests will always be fulfilled from the local offline store.

The application allows users to make changes against a local offline store and synchronize manually at any time. The sync operation is performed by a worker. There are three operations that must be implemented in order to use the offline store functionality: open, download, and upload. As their names suggest, the operations open the offline store, download server changes, and upload user changes, respectively. In the wizard-generated application, OfflineOpenWorker implements open during initialization and OfflineSyncWorker implements a sync operation, which requires upload first, and then download.

For more information about how the offline store works, see the Working With Offline Stores.

When syncing changes made while offline, conflicts can occur. One example might be if two people attempted to update a description field for the same product. Another might be updating a record that was deleted by another user. The ErrorArchive provides a way to see details of any of the conflicts that may have occurred. The following instructions demonstrate how to use ErrorArchive.

In this section we will create an Error Information screen that displays the details from the ErrorArchive.

Further information on using the offline feature can be found at Step by Step with the SAP BTP SDK for Android — Part 6 — Offline OData.

Congratulations! You have created an offline-enabled app using the SAP BTP SDK Wizard for Android and examined how the ErrorArchive can be used to view synchronization errors!