Use Usage Reporting in Your Android Application

As shown in the tutorial, Try Out the SAP BTP SDK Wizard for Android, ensure that Enable Usage Reporting is checked when creating the app.

When the app is first installed, a consent screen will automatically be shown to users.

The app must first receive permission to collect usage information from the user.

1. To view the application usage report, go to your management cockpit under Analytics > User Data.

   

   Different charts become available when you select between Sessions, Demographics, and Behavior in the drop-down (green) box. The mark in the yellow box controls whether to display filters that are in the red box right below.

2. To download the usage report, go to Mobile Applications > Native/MDK > btp.sdk.wizapp > Client Usage and User Feedback. You can filter the data by changing the value of the Last 7 Days dropdown. Click the Download icon to export the filtered data to a .csv file.

   

3. Open the downloaded clientUsage_uploads.csv. The file contains usage entries from the app that record different actions, such as button taps and timers.

   Column	Description
   APPLICATIONID	Identifies the app the usage report events were generated from
   DEVICEMODEL	Device type (Samsung, Android Emulator, etc.)
   DEVICEPLATFORM	Android or iOS
   DEVICEVERSION	Device software version
   REGISTRATIONID	A unique ID generated when you first register your device
   USERSESSIONID	A unique ID generated every time the application is re-opened
   RECORDKEY	What kind of information is being described (information about the device (DeviceInfo), an event within the application (BehaviorEvent), etc.)
   RECORDTYPE	BehaviorEvent type (e.g. viewDisplayed, userInteraction)
   TIMERSTART	Time the event began
   TIMERDURATION	How long an event ran for, in seconds
   I_SCREEN	Screen resolution of the device using the current OSLifecycle state as the key
   I_VIEW	The name of the Screen/View where BehaviourEvents are generated
   I_ELEMENT	UI element or screen control that was interacted with
   I_ACTION	Action that the user performed
   I_VALUE	Value related to the interaction, if applicable

   In the following example, there are three different Android devices with varying software versions.

   

   In the next example, the timer recorded how long the user kept the application active on their device before exiting for five different sessions. Recording how long users spend in the application is a typical measurement. You can also specify other processes to time, such as application startup, data requests, or the time taken to open an offline store.

   

   A session is typically defined as how long the app has been open for in the foreground, but different records within the application can also be modified to act as sessions.

4. A single REGISTRATIONID can be associated with multiple USERSESSIONIDs. REGISTRATIONID is independent of your username. In the following example the same user registered on two different devices and ran three user sessions.

   

The Usage feature can be used to instrument an app to track things that might provide insight into a user’s behaviors.

The following steps record how often users start adding or updating products but cancel their changes. This is somewhat similar to a metric in a shopping cart type app, where it might be interesting to know how often items are added to a shopping cart, but the sale is not completed.

Mobile Services provides a Client Usage Configuration under Mobile Client Usage and User Feedback specifying whether uploads to Mobile Services are allowed and how often they should occur. The following instructions demonstrate how to modify the app to read and store the configuration (same as the concept of the following policy) and upload the usage data to Mobile Services using the specified interval.

1. Input the number of days after which a report should automatically be uploaded and click Save. For the purposes of this tutorial, use the value 1 to simplify testing later on.

   

2. In Android Studio, on Windows, press Ctrl+N, or on a Mac, press command+O, and type WizardFlowStateListener to open WizardFlowStateListener class.

3. Near the end of the class, add the following companion objects:

   Kotlin

   Copy

   private var isUsageEnabled: Boolean = false
   private var uploadInterval: Int = 0
   

4. On Windows, press Ctrl+F12, or on a Mac, press command+F12, and type onClientPolicyRetrieved to navigate to the onClientPolicyRetrieved method.

5. At the end of the method, add the following code:

   Kotlin

   Copy

   policies.usagePolicy?.also {
       isUsageEnabled = it.dataCollectionEnabled
       uploadInterval = it.uploadDataAfterDays
       if (isUsageEnabled) {
           UsageBroker.setDataCollectionEnabled(isUsageEnabled)
           uploadUsage()
       }
   }
   

   This code gets the usage policy information from the server client policy and stores it inside global variables.

6. Add the following method in the class:

   Kotlin

   Copy

   private fun uploadUsage() {
       UsageBroker.setDaysToWaitBetweenUpload(uploadInterval)
   
       //if uploadInterval is greater than 0 then auto-upload is considered to be enabled on Mobile Services
       if (uploadInterval > 0) {
           // The upload will only occur if the last upload was more than newDays ago
           AppUsageUploader.addUploadListener(object: AppUsageUploader.UploadListener {
               override fun onSuccess() {
                   Toast.makeText(application, application.getString(R.string.usage_upload_ok), Toast.LENGTH_LONG).show()
               }
   
               override fun onError(error: Throwable) {
                   // make sure to import com.sap.cloud.mobile.foundation.networking.HttpException;
                   if (error is HttpException) {
                       logger.debug("Usage Upload server error: {}, code = {}", error.message(), error.code())
                   } else {
                       logger.debug("Usage Upload error: {}", error.message)
                   }
   
                   val errorMessage = application.getString(R.string.usage_upload_failed)
                   logger.error(errorMessage, error)
               }
   
               override fun onProgress(i: Int) {
                   logger.debug("Usage upload progress: $i")
               }
           })
           UsageBroker.upload(application, false)
       }
   }
   

   This code sets the upload interval for the application’s UsageBroker object and then requests an upload of usage. If the amount of days between uploading is sufficient, it will upload the data and, if not, it will delay the upload. If the Upload Report After interval is 0 it will not upload any usage.

   There may be an error on HttpException. Select it and press Alt+Enter on Windows, or, press option+Enter on Macs, to import the related class from com.sap.cloud.mobile.foundation.networking.

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

8. On Windows, press Ctrl+F, or on a Mac, press command+F, to find:

   Kotlin

   Copy

   usageService.uploadUsageData(forceUpload = true, owner = lifecycleOwner,
   

9. When forceUpload is set to true, the user can upload the usage report through the app’s settings screen, regardless of the number of days specified in the policy.

   When the app is run and the number of days in the policy has passed, there should be a Toast notification showing that the usage report has been uploaded successfully.

10. To test this feature, in Settings > System > Date & time from the emulator, toggle Set time automatically to off.

11. Change the Date to a day in the future and re-run the app (quit first). The usage report should be uploaded automatically.

    

See Client Usage and Step by Step with the SAP BTP SDK for Android — Part 8 — Client Usage for further information on usage.

Congratulations! You have learned how the usage feature can provide insights into how a deployed application is being used!