Android
To start working with Journey Analytics Android SDK watch the video tutorial or follow the steps below:
Step 1 – Add Journey Analytics SDK to your project
The Journey Analytics 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.
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" property2. advertising ID if available3. Device id if has permission4. 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
Journey Analytics 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
Journey Analytics 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. |