Android - Medallia

Contents

1 Implementation
2 Full API Reference
3 Change Notes

Implementation

In order to start working with Cooladata Android SDK watch the video tutorial or follow the steps below:

Step 1 – Add Cooladata SDK to your project

The CoolaData Android SDK support Android version 2.3 and up. The library depends on OkHttp library. All sending, storing and reading of data is done on a background thread.
Choose one of the following options to add the SDK to your project:

As a Gradle dependency:

dependencies {compile 'com.cooladata.android:android-sdk:2.2.3'}

As a Maven dependency:

<dependency>
<groupId>com.cooladata.android</groupId>
<artifactId>android-sdk</artifactId>
<version>2.2.3</version>
</dependency>

Download Jar with transitive dependencies (will include OkHttp artifact) or without transitive dependencies and copy it into the “libs” folder in your Android project. If you will be using the jar without embedded dependencies please validate that in case you have the OkHttp library on your classpath as well.
Embed the source code in your project using source Jar.

Step 2 – Manifest.xml configuration

To ensure that you request the permissions required for the library to work, add the following permissions within the AndroidManifest.xml element:

<!-- Mandatory permission -->
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"/>
 
<!-- Optional, but recommended to preserve battery usage -->
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>

Step 3 – Initialization

Initialize the tracker by calling the CoolaDataTracker.setup method:

public class MyApplication extends Application {
...
    @Override 
    public void onCreate() {
        super.onCreate();
        
        // init the cooladata tracker with app key and user id
        // NOTE - Do not forget to replace the app key and the user id to your own values
        CoolaDataTracker.setup(this,
            new CoolaDataTrackerOptions("aknek0zuo8i4ztcmgopn5wotsceg80m9"));
    }
...
}

We recommend calling the setup method once from Application.onCreate.

Step 4 – Track Events

Call the trackEvent method from your activity:

void CoolaDataTracker.trackEvent(String eventName, Map<string, object="", eventProperties);

The SDK collects the events you tracked and sends them every few seconds, or once the buffer is full (to conserve battery and network usage). If you want to manually send events immediately to CoolaData, call CoolaDataTracker.flush:

@Override
protected void onDestroy() {
super.onDestroy();
CoolaDataTracker.flush();
}

We recommend to always call flush from the Activity.onDestroy method, to avoid losing the last few events.

Full API Reference

Setup

The setup method used to initialize a new CoolaDataTracker singleton object.

void CoolaDataTracker.setup(Context applicationContext, CoolaDataTrackerOptions setupOptions);

Setup Parameters:

Name	Type	Mandatory	Description
context	Context	Yes	The application context
options	CoolaData Tracker Options	Yes	See below

Setup Options:

Name	Type	Mandatory	Description
appKey	String	Yes	The AppKey provided by CoolaData.
userId	String	No	Explicit user ID for this device. Providing userId will override the system userId. During the initialization the SDK will try to search for user_id in the following order: 1. “user_id” property 2. advertising ID if available 3. Device id if has permission 4. If none of above succeed a random UUID will be assigned for the current user.

trackEvent

trackEvent method syntax:

void CoolaDataTracker.trackEvent(String eventName, Map<string, object=""> eventProperties);

Tracker Parameters:

Name	Type	Mandatory	Description
eventName	String	Yes	The name of the event to report
userID	String	No	Explicit user ID for this event - should only be provided for manual user management
sessionId	String	No	Explicit session id for this event - should only be provided for manual session management
eventProperties	Map	No	The custom properties to be sent with the event

Examples:

Track a “search” event:
```
CoolaDataTracker.trackEvent("Search");
```

Track an “add to cart” event with “product type” and “amount” properties:

Map<String, Object> properties = new HashMap<String, Object>();
properties.put("Type", "T-Shirt");
properties.put("Amount", 2);

// track event with properties
CoolaDataTracker.trackEvent("Add Item", properties);

Track a “checkout” event with “status”, “amount” and “username”:

Map<String, Object> properties = new HashMap<String, Object>();
properties.put("Status", "success");
properties.put("Amount", 50.99);

// track event with properties
CoolaDataTracker.trackEvent("Add Item", getCurrentLoggedInUser(), properties);

Session Management

CoolaData groups consecutive events into session automatically (according to the project settings). To manually override session management, session attribute can be provided. For example:

CoolaDataTracker.trackEvent("Add Item", getCurrentLoggedInUser(), “A3E1-338F-BB12-CD81”, properties);

Campaign Tracking

CoolaData provides the ability to track marketing campaigns for Android, by automatically setting properties associated with how users find an app in the Google Play Store. To enable this feature, add the Install Referrer Receiver, or add the following tag to the tag in the AndroidManifest.xml file:

receiver
  android:name="com.cooladata.android.ReferrerReceiver"
  android:exported="true">
  <intent-filter>
    <action
	android:name="com.android.vending.INSTALL_REFERRER" />
  </intent-filter>
</receiver>

Once the AndroidManifest.xml file is updated, you will automatically send referrer and utm properties (campaign, content, medium, source, and term) information together with each event that you send to CoolaData.

The best way to test this type of referral tracking is to use adb to send the installation intent. Once connected via the adb shell, the following command should be used:

am broadcast -a com.android.vending.INSTALL_REFERRER -n your.pacakage.name.here/.ReferralReceiver --es "referrer" 
"utm_source%3dtest_source%26utm_medium%3dtest_medium%26utm_term%3dtest_term%26utm_content%3dtest_content%26utm_campaign%3dtest_name"

For additional information on how to test a Google Play campaign measurement implementation click here.

Change Notes

date	change
20/12/2015	Ability to disable identity tracking. (if set to true, tracker won't try to resolve device id or advertising id for username). Please note that this feature is not included into official 2.2.3 release, only as custom build. Will be released as a part of 2.2.4 release.
11/11/2015	Start using OkHttp as HTTP layer, yet remained ability to use old HTTP layer for compatibility issues (.setUseOldHttpClient(true) option)
7/11/2015	Move using standard JSON library (not sure whether it worth adding to release notes, anyway added this here)
19/10/2015	Time calibration meachnism improvement (avoid excessive calls to time calibration API)
14/10/2015	Add custome event handler support (Coca Cola request) - ability to add custom way to ahndle tracking cooladata tracker events. Events are not sent to cooladata when custom tracker is in use.
12/10/2015	Add time callibration to send events using server time
20/9/2015	Exception logging
13/4/2015	Added thresholds support to controll memory used by tracker (queues while device is offline, or between flushes), however not in use yet
19/1/2015	Added support for advertizing ID retreival. Now if user ID was not provided and app has access to advertizong ID than username is set to advertizing ID.
16/1/2015	Generated random UID became persistent between application sessions. Added device connectivity state check.
31/12/2014	User ID is not mandatory any more for tracker initialization. Device ID will be used if no user id provided. In case no permission to get Device ID then random UUID will be assigned.