Tracking - CoolaDocs

REST API

August 21, 2015 June 6, 2018Tracking

Using CoolaData’s REST API enables customers to send data to CoolaData. All API calls are HTTPS based, and require an app-key, provided by CoolaData. REST API data is sent in POST method.
Each call should be sent as an array of JSONs – one JSON per event. We only support flat JSON files – nested JSON is not supported. A single call may include as many as 300 events in a batch. To achieve better throughput, and if you are having many events per second, you should send ONLY in batch (and not one after the other).

For each call CoolaData responds with a “200 ok” status.
Note: As we accept events in JSON format, avoid using escape characters in the data sent to CoolaData. See a list of all escape chars here: http://json.org/. As a best practice we recommend sending events in the event payload url encoded.

Method:
POST
Endpoint:

1	https://api.cooladata.com/v3/[app_key]/track

Headers:

1	Content-Type: application/x-www-form-urlencoded

Payload:

The payload must be in JSON format, and URL encoded (to avoid escape characters).
The JSON structure is:

1	{events:[{"parameter_name":"parameter_value",...},...]}

The following mandatory parameters must be sent with all events (events without these mandatory fields will be invalid and will not be saved in CoolaData):

Name	Type	Mandatory	Description
event_name	String	Yes	The name of the event to report.
user_id	String	Yes	The id (possibly anonymous) of the user who generated the event
event_timestamp_epoch	Number	Yes*	*Must be sent if the project is NOT set to override event time-stamp with server time. Format is milliseconds (13 digits) only. If the project is defined to override event time-stamp with server time, any time-stamp sent with the event will be ignored. Supported time stamp formats: yyyy-mm-ddThh:mm:ss yyyy-mm-dd yyyy/mm/dd dd/mm/yyyy dd-mm-yyyy Epoch in milliseconds Days and months can also be sent in 3 letter format, such as: Mon, Tue, etc. or Jan, Feb, etc.
custom properties	String/Number	No	See more information here

Example:

{

"events":[

{"event_name":"signup","user_id":"1001","event_timestamp_epoch":1436798955476,"first_name":"john","last_name":"doe"},

{"event_name":"login","user_id":"1005","event_timestamp_epoch":1436798956879,"first_name":"johanna","last_name":"jones"}

]

}

Response:

1	{"results":{},"status":true,"events_count":n,"version":"5"}

Auto Resolution

By default, CoolaData server resolves several properties such as IP and DUA to enrich the event with additional data

DUA Resolution:

User information such as browser, os other technology information is resolved based on the session_dua property.

When one users a REST API, the users session_dua is best be send with every event to enable CoolaData to enrich the event with additional user agent info.

IP Resolution:

Geographic data such as city, country and state according is resolved based on the session_ip property.
When one uses a Rest API, the IP is determined according to your server, hence in such case, the geographical data won’t represent correctly your users’ geographical data. In case you would like to resolve this, send the actual session_ip as part of the event JSON, and if it’s not available set it to be 0 so we won’t override it with the server ip. For example:

1 2	curl -X POST https://api.cooladata.com/v2/aknek0zuo8i4ztcmgopn5wotsceg80m9/track -d '{"events":[{"session_ip":"0","event_name":"Add Item","user_id":"uid_123456"}]}'

JavaScript

August 21, 2015 December 24, 2017Tracking

The Cooladata JavaScript Tracker gives you full control over events sent from your website, by defining default setting (init), sending custom events, and more advanced options.

Initialization

The init function initializes a new instance of the CooladataTracker object.
To start tracking with Cooladata JavaScript Tracker, add the following code to the header of each page you want to track (between the <head> and the </head> tags) and replace the app key with your own:

Note: on WordPress sites, add the snippet in the header.php file. It can usually be found in the wp-admin under appearance -> Editor -> theme header(header.php).

cooladata.init({

"app_key": "<YOUR_APP_KEY>", //replace with the app key, found under "Event Sources" in the Cooladata project menu

"track_pageload": true,

"img_src_get_request": true

});

</script>

The above setup includes the recommended implementation options:

Track page views automatically
Uses a tracking pixel

The following table includes all configuration options:

Parameter	Type	Mandatory	Default	Description
app_key	String	Yes		The specific project app key provided by CoolaData
http_post	Boolean	No	False	Use HTTP POST method instead of the default GET method
img_src_get_request	Boolean	No	False	Send an image (1x1 pixel) as GET request for XHR requests
disable_cookie	Boolean	No	False	Disables cookie creation on the user browser when tracking an event. When true, the user ID sent by CoolaData will change with every page load, and user identification management will be dependent on the user ID sent in the event tracker ("user_id" in the tracker, "customer_user_id" in CQL).
api_host	String	No	api.cooladata.com	Replace the default API domain with a custom domain as the tracker endpoint. For example: "api_host":"tracking.com" will be sent to: http://tracking.com/v1/ [app_key]/track
track_pageload*	Boolean	No	False	Send page_load event automatically every time a user views the page. Sent with the following properties: page_url, page_url_params, page_title.
user_id	String	No	False	Specify the user_id on the page's cooladata tracker init to associate all events (including track_pageload) to the current user.
izzyClick	Boolean	No	False	Allows to use the CoolaData Tagger tracker to visually manage your events.

* Note: The track_pageload parameter is sent together with the user_id. If no user_id was explicitly specified in the cooladata.init() function, a random user_id will be generated and used for each event. Pay attention that if you DON’T send a user_id in the init function but send one in the cooladata.trackEvent() both random and custom user_ids will not be associated with each other.

Track Custom Events

Once you have the Tracker snippet in your page, you can track an event by calling cooladata.trackEvent(); with the event name and its properties:

How to use:

1	cooladata.trackEvent('<event_name>',{'<property_name1>':'<property_value1>', '<property_name2>':'<property_value2>'});

The function is built of a few parts:

The function call: cooladata.trackEvent()
The event name
The properties & their values a JSON. The JSON must be “flat” so you can’t use any nested JSON.

Example:

1	cooladata.trackEvent('Add Item', {'Type': 'T-Shirt', 'Amount': 2, 'email':'sam@email.com'});

Each event can include properties. For example, the above ‘Add Item‘ event includes the item type, number of items, and the purchaser’s email address. Read more about properties.

You could also use JQuery to send an event to the Cooladata server. In this example a function is called when a form’s SEND button is clicked (this example uses ninja forms). JQuery is used here to extract the data from the differentn form’s fields.

jQuery(document).ready(function($){

var sendButton = $("#ninja_forms_field_51"); //the form object sending the form (send button)

sendButton.click(function(){

callTrack4();

});

function callTrack4(){

var name_var = $("#ninja_forms_field_45").val(); //form variables for properties

var lastName_var = $("#ninja_forms_field_46").val();

var email_var = $("#ninja_forms_field_47").val();

var phone_var = $("#ninja_forms_field_48").val();

var property_value_var = $("#ninja_forms_field_49").val();

cooladata.trackEvent('secondPopup', {'name': name_var, 'last_name':lastName_var, 'email':email_var , 'phone':phone_var,'property_value':property_value_var}); //CoolaData trackEvent

}

In the table below you can find all cooladata.trackEvent() elements (some are optional):

Parameter	Type	Mandatory	Description
eventName	String	Yes	The name of the event to report.
eventProperties	Object	No	Object containing all additional properties in format: "property_name":"property_value". See example below.
user_id	String	No	Send if you want to be able to identify users according to your definition for user ID. For example: use this for cross-platform identification where users perform a log-in action.
event_timestamp_epoch	Number	Yes*	*Must be sent if the project is NOT set to override event time-stamp with server time. Format is milliseconds (13 digits) only. If the project is defined to override event time-stamp with server time, any time-stamp sent with the event will be ignored.
custom properties	String/Number	No	Any additional properties mapped in the project. See more information in Managing Properties.

Use a callback function

In some cases, after sending an event to the server, you would want to execute some code on the Browser. This can be easily done by adding a callback function to your cooladata.trackEvent() call.

The process works as follows: Tracker sends event to Cooladata server -> Cooladata server sends OK response to Tracker -> callback function is executed.

How to use:

cooladata.trackEvent('<event_name>',{'<property_name>':'<property_value>'},function(){

//your callback function code here

});

Example:

cooladata.trackEvent('get_coupon',{'discount':'35%',function(){

window.alert('You've got 35% discount!')

});

Track a bulk of events

The cooladata.trackEventLater() method provides the ability to track a bulk of events. All events will be stored on a local queue until the cooladata.flush() method is called. This method can be useful when you want to submit more than one event at a time, for example to send a list of events that are linked together all in a single request, instead of multiple requests.

Example:

1. Add an event to the queue:

1	cooladata.trackEventLater("register_submit",{"user_id":"JohnDoe", "subscription_active":0})

2. Add a second event to the queue:

1	cooladata.trackEventLater("add_to_cart",{"user_id":"JohnDoe", "sku":JSV-4532})

3. Send the events to the Cooladata server

1	cooladata.flush();

Android

August 21, 2015 July 17, 2018Tracking

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:

1

dependencies {compile 'com.cooladata.android:android-sdk:2.2.3'}
As a Maven dependency:

1
2
3
4
5

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

<uses-permission android:name="android.permission.INTERNET" />

<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"/>

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

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

1	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:

1	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:

1

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:

1	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:

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

Unity

August 21, 2015 October 23, 2017Tracking

Setup

1. Download the tracker from: https://github.com/cooladata/cooladata-unity
2. Add the Unity package to your project.
3. Open the unity package with the unity IDE, or add the package as an asset to your project.
4. Add the following import to classes that use the CoolaData tracker:

1	using com.cooladata.tracking.sdk.unity;

5. Create and initialize the CoolaData tracker instance:

1	CoolaDataTracker.getInstance().setup(String appKey, String serviceEndPoint, String userId)

Tracking Events

After the CoolaData Tracker SDK is properly set up, you are ready to report events from your application. To start doing so, you need to call the trackEvent function with suitable parameters on every user’s action that you would like to track.

Prepare the parameters

1 2	Dictionary<string,string> myMap = new Dictionary<string, string>(); myMap.Add("unity param 1", "value1");

Add the event to the queue

1	CoolaDataTracker.getInstance().trackEvent("eventName", myMap);

Other event tracking examples:

CoolaDataTracker.getInstance().trackEvent(eventName, eventProperties);

CoolaDataTracker.getInstance().trackEvent(eventName, userId, eventProperties);

CoolaDataTracker.getInstance().trackEvent(eventName, eventProperties, eventId, callback);

CoolaDataTracker.getInstance().trackEvent(eventName, userId, eventProperties, eventId, callback);

Parameters Descriptions:

Parameter	Mandatory	Description
eventName	Yes	The name of the event to report.
userId	No	The User ID relevant for this instance of the CoolaDataTracker. Can be provided either in the setup or the trackEvent method. If no userId is provided one will be generated automatically.
eventProperties	No	The custom properties to be sent with the event. This parameter is optional. The parameters should be in the Dictionary format.
eventId	No	An ID of the event.
Callback	No	a CoolaDataDeliveryResult type result that will be returned when the data is sent.

iOS

August 21, 2015 October 23, 2017Tracking

Implementation

In order to start working with Cooladata JavaScript SDK follow the steps below:

Step 1 – Add Cooladata SDK to your project

Make sure that you are using the latest version of Xcode (5.0+), and targeting iOS 7.0 or higher. Demo project for Swift and Objective C can be found in our github repository: https://github.com/cooladata/pod.
Choose one of the following options to add the SDK to your project:

Option 1: Download the latest iOS SDK and import it (drag the cooladata-ios-sdk-X.X.X.framework to the framework’s folder in your project and select “Copy items to destination’s group folder”).

Option 2: Use CocoaPods:

Create the Podfile
- If this is your first Pod in your iOS project, create a file named Podfile:
  
  1
  2
  3
  4
  5
  6
  
  platform :ios, '7.0'
  use_frameworks!
  
  target 'MyApp' do
  pod 'CoolaPod', '~> 2.0.7'
  end
- If you already use CocoaPods in your project, add a reference to CoolaData ‘s Pod:
  
  1
  
  pod 'CoolaPod', '~> 2.0.7'
Open the terminal app, change dir to your xcode project and run:

1

$ pod install

This command creates an xcode workspace for your project, and configures it to use CocoaPods.
From now on, make sure to always open the Xcode workspace instead of the project file when building your project.

Step 2 – Initialization

Add the following import to the top of the AppDelegate.m file.

1	#import <cooladata-ios-sdk/CoolaDataTracker.h>

Add the following code inside the application:didFinishLaunchingWithOptions function.

1	[[CoolaDataTracker getInstance] setupWithAppKey:@"aknek0zuo8i4ztcmgopn5wotsceg80m9"];

Note: The CoolaDataTracker is a singleton. Its reference can be obtained by calling the getInstance method: [CoolaDataTracker getInstance]. Creating the new instance of the CoolaDataTracker object manually will cause an error; therefore do not call [CoolaDataTracker alloc] init].

Step 3 – Track Events

After the Cooladata Tracker SDK is properly set up, you are ready to report events from your application. To start doing so, you need to call the trackEvent function with suitable parameters on every users’ action that you would like to track.

// set properties on a dictionary

NSDictionary *properies = @{@"Type" : @"Female",

@"Amount" : @2, @"{u}Email":@"sam@email.com"};

// track event with properties

[[CoolaDataTracker getInstance] trackEvent:@"Add Item" properties:properties];

Full API Reference

setupWithApiToken

This method used to initialize a new CoolaData tracker object. Should be called only once from the application:didFinishLaunchingWithOptions.

Name	Type	Mandatory	Description
appKey	NSString	Yes	The AppKey provided by CoolaData.
serviceEndPoint	NSString	No	The base URL for the CoolaData Tracker to use when accessing the CoolaData gateway.
userId	NSString	Yes	The User ID of the current user. Mandatory in the setupWithApiToken function, or in the trackEvent function. I.e. if the User ID provided in the setupWithApiToken, there's no need to send User ID in the trackEvent function, and vice versa.
sessionId	NSString	No	The Session ID relevant for this instance of the CoolaDataTracker.

CoolaDataDeliveryResult

This object will be returned from the callback function and contains the following.
Parameters

Name	Type	Description
eventId	NSString	The ID of the event as specified in the track event.
status	BOOL	The status of the delivery. False or True.
deliveryStatusDescription	NSString	The description of the status state.
deliveryStatusCode	Int	The HTTP error code of the delivery attempt.
responseProperties	NSDictionary	Custom properties to be sent with the event result.

trackEvent

Track user’ event

Name	Type	Mandatory	Description
eventName	NSString	Yes	The name of the event to report. This parameter is mandatory.
withEventId	NSString	No	The Event ID relevant for this event. This parameter is optional. If response block is passed, event id must also be provided.
userId	NSString	No	The User ID relevant for this event. This parameter is optional only if provided in the setup method. You must provide the userId either in the setup method or in the trackEvent method.
sessionId	NSString	No	The Session ID relevant for this event. This parameter is optional.
optionalData	NSString	No	The custom properties to be sent with the event. This parameter is optional.
error	NSError	No	A pointer to an NSError object. It will be populated with an error in case an immediate error occurs (mandatory parameter was not provided). This parameter is optional.
responseBlock	Block	No	When calling the track event method, you can pass a response block that will be called with the result/error objects upon receive. For this to happen you must also pass an event id. You can pass the same event id for multiple events. All the blocks related to that event id will be called upon receipt of the related results. This parameter is optional.