Skip to Content

Use Usage Reporting in Your Android Application

test
0 %
Use Usage Reporting in Your Android Application
Details
// Explore More Tutorials

Use Usage Reporting in Your Android Application

See how the Usage Reporting feature can help provide information on how your app is being used.

You will learn

  • How the Usage Reporting feature works, through demonstration
  • How to customize the consent screen
  • How to further instrument the wizard app
  • How to add code to enable auto-upload of usage data based on the client policy

Step 1: Manual upload of usage data

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

Enable Usage when Creating App

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

The text displayed to the user can be customized by accessing res/values/strings_localized/strings_localized(en).xml (or by pressing Shift twice then searching for strings_localized.xml) and editing the text between the string tags below. For more details on translation, see Add New Languages to your Android Application.

<string name="get_usage_permission_explanation">
  Detailed text about how data privacy pertains to this app and why it is important for the user to enable this functionality
</string>

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

Tap OK to allow the app to record how the app is being used.

Consent Screen

If Not Now was selected, the user’s choice can later be changed in the app’s settings screen.

Usage in Settings

From the settings menu, tap Upload Usage.

Click Upload Usage

The upload will fail with a HTTP 403 error if usage was not enabled in the Mobile Services cockpit.

Upload Failed

To review this policy setting, in the Mobile Services cockpit, access Client Policies through Mobile Applications > Native/Hybrid > Wiz App > Client Policies.

Access Client Policies

The Usage Report Policy specifies if uploads of usage data are allowed and the time interval for automatic usage report uploads.

A value of 0 will initially be in the Upload Report After which we will use in our later implementation of automatically uploading usage reports to the server and it will mean that usage reports will not be uploaded automatically.

Enable Usage in Client Policies

If an empty usage report notification is shown when Upload Usage is selected, navigate away from the app by going to your phone’s home screen and re-entering the app. Then try uploading the usage report again. Placing the app in the background will complete or end the current usage session. Partial sessions can not be uploaded.

Empty Usage Report Upload Attempt

If Upload Usage was successful, then a Toast message should pop up informing you that the usage information has been uploaded to the server.

Successful Usage Upload
Log on to answer question
Step 2: Examine uploaded usage data

To view the application usage report, go to your management cockpit under Analytics > Client Data Report and click the download icon.

Various charts are available by changing the drop down that includes User Sessions per Application and Time Period. The data can be filtered by changing the value of the drop down with Last 7 Days and clicking Go. Then click the download icon to get the filtered data in a csv file.

Download Usage From Management Cockpit

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

Column Description
APPLICATIONID Which application the usage report events were generated from
DEVICEMODEL Type of device (Samsung, Android Emulator, etc.)
DEVICEPLATFORM Android or iOS
DEVICEVERSION Software version of the device
TIMERSTART Time the event began at
TIMERDURATION How long an event ran for in seconds
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 it describing (information about the device (DeviceInfo), an event within the application (BehaviorEvent), etc.)
RECORDTYPE Describes the type of BehaviorEvent (e.g. viewDisplayed, userInteraction)
I_SCREEN Describes the screen resolution of the device and uses the current OSLifecycle state as the key
I_VIEW Screen/View name of 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 example below, there are 3 different Android devices with varying software versions.

CSV Information on Device Specifications

In the next example, the timer recorded how long the user kept the application active for on their device before exiting for 5 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.

CSV Information on Session Times

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.

There can be multiple USERSESSIONIDs associated with a single REGISTRATIONID. REGISTRATIONID is independent of your username and you can see a complete list of all user registrations for the app in the Mobile Services cockpit through Mobile Applications > Native/Hybrid > Wiz App > User Registrations.

In the example below the same user registered through 2 different devices and ran 3 user sessions.

Session Descriptive Information

When the application is initially launched, the report comes to contain entries that describe the device screen, memory and networking capabilities in a condensed form within 4 columns, marking the end of a session.

I_VALUE Description
EnterApplication Screen resolution of the device (I_SCREEN)
location Location permission for the application (denied or authorized); if authorized then it will list the latitude (I_VIEW), longitude (I_ELEMENT) and city (I_ACTION)
device Reiterates the screen resolution (I_SCREEN and I_VIEW), device platform (I_ELEMENT) and specifies the device language (I_ACTION)
memory RAM of the device (I_SCREEN), internal storage (I_VIEW) and available space on SD card (I_ELEMENT)
Device Information in First Entries

The app also records a few of the screens that users enter, and more usage reporting statements can be added in the code to track other specific screens.

In the example below, the user navigated from the Logon screen to the EntitySetListActivity screen and accessed the categories at positions 3 and 0, then entered the Settings screen.

Recording screens that users enter

The code segment that records LogonActivity can be found in the onCreate method in LogonActivity.java.

((SAPWizardApplication)getApplication()).getUsageUtil().eventBehaviorViewDisplayed("LogonActivity","elementID","onCreate","called");

The code segment that records EntitySetListActivity can be found in the onCreate method in EntitySetListActivity.java.

usageUtil = ((SAPWizardApplication) getApplication()).getUsageUtil();
usageUtil.eventBehaviorViewDisplayed(EntitySetListActivity.class.getSimpleName(),
				"elementId", "onCreate", "called");
What does the Usage Reporting feature do?
×
Step 3: Add further usage instrumentation

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

The following steps will 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 a sale is not made.

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

Add the following variable into the ProductsCreateFragment class near the other private variables.

private UsageUtil usageUtil;

On Windows press Ctrl+F12 or on a Mac press command+F12 and type onCreate to move to the onCreate method in the same file.

Find the following line

super.onCreate(savedInstanceState);

Then add the following code segment immediately after

usageUtil = ((SAPWizardApplication)getActivity().getApplication()).getUsageUtil();
usageUtil.eventBehaviorUserInteraction(ProductsCreateFragment.class.getSimpleName(),
  "elementId", "createOrEditProductClicked", "Begin Create or Edit Product");

This generates a usage event record for when a user taps the Add or Edit icon within Products.

On Windows press Ctrl+F12 or on a Mac press command+F12 and type onOptionsItemSelected to move to the onOptionsItemSelected method. Add the following code segment before the default: case in the same file.

case android.R.id.home:
  usageUtil = ((SAPWizardApplication)getActivity().getApplication()).getUsageUtil();
  usageUtil.eventBehaviorUserInteraction(ProductsCreateFragment.class.getSimpleName(),
    "elementId", "onBackPressed", "Create or Edit Product Cancelled");
  return true;

This generates the usage event record whenever the user navigates away from an editing screen without saving.

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

On Windows press Ctrl+F12 or on a Mac press command+F12 and type onOptionsItemSelected to move to the onOptionsItemSelected method.

Modify the return statements so the case and default case end with the below code.

return false;

By changing the return statements to false, it ensures that the code added to ProductsCreateFragment.java gets executed when the navigate back button is pressed.

Build and run the app.

Generate usage information by accessing Products.

Access Products

Tap the floating Add button to create a product.

Create a New Product Item

Press the back button to exit the page without saving.

Press Back Button

Repeat those steps 2 more times to generate multiple entries for the usage report.

Finally, select an existing Product and tap on its Edit button.

Edit Product

Then immediately tap the check mark button to save the information.

Save Product

End the usage session by placing the app in the background. Navigate back into the app.

Upload the usage by going to Settings and tap on Upload Usage.

After downloading the client_uploads.csv file from the Mobile Services cockpit, you should be able to see new entries with I_VIEW values of ProductsCreateFragment and I_ACTION values of onBackPressed and createProductClicked.

New Entries in the Client Upload csv

In 4 empty cells that do not fall under the R column on the Excel spreadsheet, label two of them with Product Create or Edit Clicked and Cancelled Product Create or Edit. Next to Product Create or Edit Clicked, use the below formula to find the number of times the user intended to add/update a product.

=COUNTIF(R:R, "*createOrEditProductClicked*")

Then next to Cancelled Product Create or Edit, use the below formula to find the number of times the user cancelled an add/update product action.

=COUNTIF(R:R, "*onBackPressed*")

In the example, the user tried to create a Product 4 times, but cancelled 3 times.

Counting Product Creation and Cancellations with Excel Formulas
Log on to answer question
Step 4: Auto-upload of usage data

Mobile Services provides a Usage Report Policy under Client Policies specifying if uploads to Mobile Services are allowed and how often they should occur. The following instructions will demonstrate how to modify the app to read and store the policy and upload the usage data to Mobile Services using the specified interval.

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

Set Auto Upload of Usage Report

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

Add the following variables to the ClientPolicy class below the private variables.

private boolean isUsageEnabled;
private int uploadInterval;

public void setUsageEnabled(boolean usageEnabled) { isUsageEnabled = usageEnabled; }

public boolean isUsageEnabled() { return isUsageEnabled; }

public void setUploadInterval(int interval) { uploadInterval = interval; }

public int getUploadInterval() { return uploadInterval; }

This code creates variables to handle usage data and provides them with getters and setters.

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

Add the following variables to the ClientPolicyManager class with the rest of the private static final variables.

private static final String USAGE_POLICY_ENABLED = "dataCollectionEnabled";
private static final String USAGE_POLICY_UPLOAD_AFTER_DAYS = "uploadDataAfterDays";
private static final String SETTINGS_USAGE = "usagePolicy";

On Windows press Ctrl+F12 or on a Mac press command+F12 and type onSuccess to move to the onSuccess method.

Place the following code near the end of the method, before the line downloadLatch.countDown();.

JSONObject usagePolicyJson = result.optJSONObject(SETTINGS_USAGE);
if (usagePolicyJson != null) {
  boolean isUsageEnabled = usagePolicyJson.optBoolean(USAGE_POLICY_ENABLED, false);
  int uploadInterval = usagePolicyJson.optInt(USAGE_POLICY_UPLOAD_AFTER_DAYS, 0);
  policyFromServer.setUsageEnabled(isUsageEnabled);
  policyFromServer.setUploadInterval(uploadInterval);
}

This code gets the usage policy information from the server client policy and stores it inside a ClientPolicy object.

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

Add the following method.

private void uploadUsage() {
    //the ExecutorService runs the code on a separate thread because getting the ClientPolicyManager data makes a significant impact on performance
    ExecutorService executorService = Executors.newSingleThreadExecutor();
    executorService.submit(() -> {
      int newDays = clientPolicyManager.getClientPolicy(true).getUploadInterval();
      UsageBroker.setDaysToWaitBetweenUpload(newDays);

      //if newDays is greater than 0 then auto-upload is considered to be enabled on Mobile Services
      if (newDays > 0) {
        // The upload will only occur if the last upload was more than newDays ago
        UsageBroker.upload(false, this, new AppUsageUploader.UploadListener() {
          @Override
          public void onSuccess() {
            Toast.makeText(getApplication(), getResources().getString(R.string.usage_upload_ok), Toast.LENGTH_LONG).show();
          }

          @Override
          public void onError(Throwable error) {
            // make sure to import com.sap.cloud.mobile.foundation.networking.HttpException;
            if (error instanceof HttpException) {
              LOGGER.debug("Usage Upload server error: {}, code = {}", ((HttpException) error).message(), ((HttpException) error).code());
            } else {
              LOGGER.debug("Usage Upload error: {}", error.getMessage());
            }
            String errorCause = error.getLocalizedMessage();
            ErrorMessage errorMessage = new ErrorMessage(getResources().getString(R.string.usage_upload_failed), errorCause, new Exception(error), false);
            errorHandler.sendErrorMessage(errorMessage);
          }

          @Override
          public void onProgress(int i) {
            LOGGER.debug("Usage upload progress: " + i);
          }
        });
      }
    });
}

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.

On Windows press Ctrl+F12 or on a Mac press command+F12 and type finishLogonActivity to move to the finishLogonActivity method.

In the else block, before the call to startEntitySetListActivity, add the below method call.

uploadUsage();

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

Press Ctrl+F to find:

UsageBroker.upload(false, getContext(), new AppUsageUploader.UploadListener() {

Change the false to true on that line.

This will allow the user to upload the usage report via 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 Toast notification showing that the usage report has been uploaded successfully.

To test this feature, in System > Date & time toggle Automatic date & time to off.

Change the date to a day in the future and re-run the app. The usage report should be uploaded automatically.

Usage Report Successfully Uploaded Toast Message

Further information on usage can be found at Client Usage and Step by Step with the SAP Cloud Platform SDK for Android — Part 8 — Client Usage

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

Log on to answer question

Next Steps

Back to top