Android

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:

  implementation 'com.cooladata.android:android-sdk:2.4.2'

• As a Maven dependency:<dependency>
  <groupId>com.cooladata.android</groupId>
  <artifactId>android-sdk</artifactId>
  <version>2.4.2</version>
  <type>aar</type>
  </dependency>
• Download aar  and copy it into the “libs” folder in your Android project.

  Please validate that 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:

Setup Options:

trackEvent

trackEvent method syntax:

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

Tracker Parameters:

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