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. |