Data Collection for Android Sample App

Intellectual Property

Protected by patents in the U.S. and Europe:

US10430037, EP2684143, US8365188, EP1997041, US8880710, EP1979840, US8898309, EP1979839

A hands on guide to the Android sample app with manual and automated instrumentation.

1. Introduction

The sample app demonstrates how to collect data using the Celebrus Client Side Adapter (CSA) for Android. This document describes how the sample app integrates with various Android UI components.

The Android CSA is used in many Android development tools. However, the sample app is set-up for Android Studio.

1.1. CSA and resources

A Celebrus Server install contains all that is required to get you collecting data with the Celebrus SDK. An example app is located within the Examples folder, whilst the SDK and associated API documentation is located within the SDKs folder.

1.2. Import the CSA library

Extract the CelebrusAndroidSDK file located within the SDKs folder in Celebrus server installation directory and copy the CelebrusAndroidCSA.jar file into the project libs folder.
Add the following dependencies to the build.gradle file:

dependencies {
 compile files('libs/CelebrusAndroidCSA.jar')
}

1.3. Automated instrumentation

The main class is the application level class which extends by android.app.Application. Follow these steps to initialise automated instrumentation in the Android CSA:

Initialise the application logger:

Celebrus.setLogger(new LogCatLogger());

Signal that the app has support for Android API level 14 or higher:

AutoInstrumentApiLevel14.instrument(this);

1.4. Start the Android CSA

Start the CSA in the first activity of the application. Please refer to the class documentation delivered as part of the installation process for further details.

Celebrus.start(useCase,
                communicationsType,
                operationalMode,
                csaName,
                collectionUrl,
                activity,
                isLocationCollectionEnabled,
                isUniqueVisitorTrackingEnabled,
                appName);

In the sample app, the CSA is initialised in the SplashScreen class.

1.5. Configuring demo app

Upon launching the app for the first time a screen is shown allowing the demo to be configured to your Celebrus installation. To access the configuration on subsequent launches use the Main menu option.

Configuring collection details
This screen helps to provide the collection server details to start the CSA, so that the demo app can be configured to connect any of the collection server available.
Configuring Session details
The app user can now be able to configure the session durations and enable the session sharing with WebView, if required.

2. Manual and automated instrumentation

This sample app shows both manual and automated instrumentation.

Automated instrumentation: This mode enables the CSA to perform an automated instrumentation for all View components in the app. Enable automated instrumentation by setting the following variable in the MainApplication class:

public static boolean isManualInstrumentationEnabled = false;

Manual instrument: This mode enables the CSA to perform manual instrumentation for each of the View components in the app. Enable manual instrumentation by setting the following variable in the MainApplication class:

public static boolean isManualInstrumentationEnabled = true;

3. UI controls

This page demonstrates data collection from a wide variety of Android UI controls.

From the home page in the app, click on UI Controls.

3.1. Basic UI controls

This view demonstrates the following UI controls.

Edit text
Password
Check box
Radio option
Spinner
Toggle button
Switch button
Rating bar
Seek bar
Normal button

No integration code is required for automated instrumentation of these UI controls.

Data collected from these UI controls is automatically transmitted to the Collection Servers by the Android CSA. However, to use the data effectively it is essential that every control has a unique ID:

<EditText
 android:id="@+id/etUsername"

3.2. Dialogs

This page demonstrates to instrument the dialogs:

Fragment/Alert dialogs

Automated instrumentation is not possible for dialog fragment and alert dialogs. It is therefore necessary to manually request instrumentation of dialogs once they are created.
Date/Time dialogs

Automated instrumentation is not possible for date or time pickers. If data capture is required from these components, then the manual APIs can be used instead.

Please note that there is no specific integration code to be added for the Auto-instrumentation for the above UI controls. The data collection from these UI controls will be transmitted automatically to the back end servers by the Android CSA. However, it is required to assign an unique ID for each component.

3.3. Submit form values

When a form is completed within the app, all the form field values are gathered together as a set of FormValue instances and sent using the Celebrus.getApi().sendFormValues method. Sending form values should be implemented in the same Activity class (UiControlPageOneActivity in the case of the sample app).

btnSubmitForm.setOnClickListener(new View.OnClickListener() {
     @Override
     public void onClick(View v) {
        final FormValuesBuilder formValues = new FormValuesBuilder();
        builder.addValue(checkBox).addValue(textField);
        Celebrus.getApi().sendFormValues("testFormName","testFormId",formValues);
     }
})

4. Supported layouts

Automated data collection for different layouts is demonstrated in the sample application. There is no separate code required to implement the data collection on these layouts.

From the home page in the app, click on Layouts.

The following table describes the layouts demonstrated in this app and the respective class names:

ANDROID STANDARD LAYOUT CLASS ACTIVITY CLASS IN SAMPLE APP LAYOUT XML IN SAMPLE APP

ANDROID STANDARD LAYOUT CLASS	ACTIVITY CLASS IN SAMPLE APP	LAYOUT XML IN SAMPLE APP
`LinearLayout`	`LinearLayoutActivity`	`activity_linearlayout.xml`
`TableLayout`	`TableLayoutActivity`	`activity_tablelayout.xml`
`FrameLayout`	`FrameLayoutActivity`	`activity_framelayout.xml`
`GridLayout`	`GridViewActivity`	`activity_grid.xml`
`RelativeLayout`	`RelativeLayoutActivity`	`activity_relativelayout.xml`
`Absolutelayout`	`AbsoluteLayoutActivity`	`activity_absolutelayout.xml`
`Tab/FragmentLayout`	`FragmentActivity`	`activity_tablayout.xml`
`RecyclerView`	`RecyclerActivity`	`activity_recyclerview.xml`
`Coordinatorlayout`	`CoordinateLayoutActivity`	`activity_coordinatorlayout.xml`

LinearLayout

LinearLayoutActivity

activity_linearlayout.xml

TableLayout

TableLayoutActivity

activity_tablelayout.xml

FrameLayout

FrameLayoutActivity

activity_framelayout.xml

GridLayout

GridViewActivity

activity_grid.xml

RelativeLayout

RelativeLayoutActivity

activity_relativelayout.xml

Absolutelayout

AbsoluteLayoutActivity

activity_absolutelayout.xml

Tab/FragmentLayout

FragmentActivity

activity_tablayout.xml

RecyclerView

RecyclerActivity

activity_recyclerview.xml

Coordinatorlayout

CoordinateLayoutActivity

activity_coordinatorlayout.xml

5. Manual data collection

The Android CSA supports manual data collection. This is demonstrated in the RelativeLayoutActivity class. The class uses the following methods to collect data when the user clicks on buttons in the View:

Celebrus.getApi().sendTextChangeEvent(final View view );

Celebrus.getApi().sendClickEvent(final View view );

6. Pass device identifier to WebView

When the CSA is started, it creates a unique device identifier. This device identifier is passed to the Collection Server and is used to track user activity across sessions. This identifier should be shared with any WebView components so that the collected data appears from a single device.

Declare a string variable and assign the domain values as comma separated values:

String url = "http://example.in/index.html";
String domains = ".example.co.uk, .example.uk, .example.com ";

Before loading the WebView URL, initialise the method shareDeviceIdWithWebViewDomains with the value from the domain variable:

Celebrus.shareDeviceIdWithWebViewDomains(domains);

7. Share session identifier with WebView

Celebrus collects the events from HTML5 content displayed in the WebView using CelebrusInsert.js, but the different session identifier is generated. However, session identifier can be shared between app and WebView by enabling below.

Celebrus.setAppAndWebViewsShareSession(true);

Below list items in the main menu of the app shows the examples of sharing session identifier.

App WebView Session Sharing - Online content

The demo shows the HTML content displayed from Online. Events collected for this HTML is having the same session identifier of the events collected from the app.
App WebView Session Sharing - File content
Demonstration of session sharing between native and WebView parts of a hybrid app. The HTML content and CelebrusInsert.js are both loaded directly from the app’s asset folder. The events collected for this HTML is having the same session identifier of the events collected from the app.

8. Session identifiers

For testing purposes, the session identifier and the session key generated for the app are displayed in an alert. The following code needs to be included in the required Activity or component. A long press on the volume key up button displays the alert:

@Override
public boolean onKeyDown(int keyCode, KeyEvent event)
{
   if(keyCode == KeyEvent.KEYCODE_VOLUME_UP || keyCode == KeyEvent.KEYCODE_VOLUME_DOWN)
   {
     event.startTracking();
     return true;
   }
   return super.onKeyDown(keyCode, event);
}

@Override
public boolean onKeyLongPress(int keyCode, KeyEvent event)
{
   if(keyCode == KeyEvent.KEYCODE_VOLUME_UP)
   {
     Celebrus.showSessionIdentificationAlert(this);
     return true;
   }
   return super.onKeyLongPress(keyCode, event);
}

9. Send events manually

If the communication type is BATCHED_MANUALLY, then events are collected and queued, but not transmitted to the Collection Server. In order to transmit the collected data, call API Celebrus.sendEventsNow. This feature is demonstrated in SendManuallyActivity class.

When this activity is started, the CSA is restarted with communication type BATCHED_MANUALLY:

Celebrus.stop(false);

Celebrus.start(UseCase.MARKETING,
                Communications.BATCHED_MANUALLY,
                 OperationalMode.LIVE,
                 "devtest",
                 "http://devtest.celebrus.com/[http://devtest.celebrus.com]",
                 this,
                 true,
                 false,
                 "CelebrusTraining");

Celebrus.sendEventsNow is invoked to send the collected data to the Collection Server:

btnSubmit.setOnClickListener(new View.OnClickListener() {
    @Override
    public void onClick(View v) {
        finish();
        Celebrus.sendEventsNow();
    }
});

10. Personalization

Demo app demonstrates the personalization for the below

WebView Personalization

Demonstrates personalization of HTML content displayed within a WebView.

In this demo you can notice the image displayed in the HTML got replaced with the image configured in real-time server.

Native Personalization

Native Personalization demonstrates the personalization to be done in the layout and get the content by initiating the API Celebrus.getApi().contentLoading. In this dmeo you can notice the image of android icon got replaced with the image configured in real-time server.
Native Personalization (Default callback)

Native Personalization demonstrates the personalization to be done in the layout and contentLoading is initialized by constructing the JSON and sending it has a JSON event. Also, this requried a default callback class set as given below. In this demo you can notice the image of android icon got replaced with the image configured in real-time server.
```
final DefaultPersonalizationCallback defaultPersonalizationCallback = new DefaultPersonalizationCallback(this);
```
Please note, DefaultPersonalizationCallback class is derived/extends from AbstractPersonalizationCallback.

11. SSL Certificate Pinning

11.1. Certificate Pinning

Demonstrates certificate pinning using the standard HttpsURLConnection Java class. The app looks for a certificate file named collection-certificate.cer within its assets path. The simplest way to achieve this is to use a web browser. For example using the Chrome web browser:

Open Collection Server’s home page.
Right-mouse click on the secure icon within the browsers address bar which shows the URL.
Select the Certificate option.
Within the Certificate dialog select the Details tab.
Select the Copy to File… resulting in a Certificate Export Wizard dialog opening.
Select Base-64 encoded X.509 (.cer).
Save the certificate to Environment.DIRECTORY_DOWNLOADS/celebrus/assets/.

Note: Create the Environment.DIRECTORY_DOWNLOADS/celebrus/assets/ folder if it does not exist on the device.

Certificate pinning is enabled by selecting the Certificate Pinning option within the app.

If pinning is enabled and the Collection URL doesn’t match the pinned certificate, data collection will not work.

11.2. Key Pinning

Demonstrates key pinning using the standard HttpsURLConnection Java class to pin SSL communications to a fixed Subject Public Key Info. Tha app looks for a public key file named cert-publickey.pem within its assets path. To achieve this following the steps:

Generate the public key as given in Data collection of Android documentation.
Copy the file cert-publickey.pem to Environment.DIRECTORY_DOWNLOADS/celebrus/assets/.

Note: Create the Environment.DIRECTORY_DOWNLOADS/celebrus/assets/ folder if it does not exist on the device.

Public key pinning is enabled by selecting the Key Pinning option withi the app.

If pinning is enabled the Collection URL certificate public key doesn’t match the app’s public key the request will fail.

12. Set Consent

The page demonstrates to set the consent type for the demo app.

Opt-In

Setting Opt-In enables full data collection.
Anonymous

Selecting Anonymous prevents identifying data being collected.
Opt-Out

Setting Opt-Out stops all data being collected.

13. Gesture

Celebrus SDK supports to collect the events for the below gestures.

Zoom Gesture

Selecting the Zoom Gesture option displays an ImageView which when zoomed generates Zoom events as appropriate.
Scroll Gesture

Selecting the Scroll Gesture option displays a ScrollView which when scrolled generated Scroll events showing the current top left x and y position of the scrolled window.
Swipe Gesture

Selecting the Swipe Gesture option display a view which when swipe actions are performed generates Swipe events.

14. Logging

Once the app is configured and running successfully then, you can monitor the events collected through the CSA. This can be done by the default logcat of Android Studio:

If you have configured the live Collection Server URL and CSA name then all the logged events are sent to the Collection Server as well. You can use the Event Sample app in the Configuration Manager to view events.