JavaScript – CoolaData Eventualizer

CoolaData Eventualizer is designed to streamline your onboarding and setup, by allowing you to easily and quickly add tracking on your site.

Setup

First, install the chrome extension from the chrome web store: https://goo.gl/TAsPcf
Next, activate the extension on your website by clicking its icon (near the URL bar).
pasted-image-0

Select your project

The extension will check if you already have the CoolaData tracker implemented on the page.
If it is found, the project it refers to will be selected automatically (skip demo mode).
If it is not found, you’ll be asked to select the project you want to use, or create a new project.
Next, copy the code and add it to the page header – you can paste it as is, or using Google Tag Manager.
Until this is done you can get started by using the demo mode.

Demo mode

Demo mode enables you to try out CoolaData’s tracking before making any changes to your website.
Demo mode tracks events locally, so your interactions with the website trigger CoolaData events only on your computer, only while in demo mode.

First, define some events on the site (see Creating events below).
Next, open another tab on the site. Demo mode will start working for any new tab you open – you’ll be able to tell you’re in demo mode by the indication on the extension button and by the banner in the top left corner of the screen:
pasted-image-0-2demo icon

Click or hover over the items for which you defined events.
You can see the events you generate by clicking the ‘Event Log’, as well as on the ‘live events’ page in app.cooladata.com (events can take up to 2 minutes to show).

The events you and all other users create in the extension on this project in demo mode will be saved and tracked on the site once the tracking code has been implemented.

Exit demo mode by clicking the link at the bottom right or closing the extension.

 

Creating events

  1. To define a new event on an item click ‘Create New Event’.
    pasted-image-0-3
  2. Move your mouse pointer over any clickable element in the page – the element will be marked to indicate you can place an event on it.
    Hold down the ALT button to see through the extension, in case a popup blocks your access to something behind it.
    pasted-image-0-4
  3. Click the element to create an event on it.
    pasted-image-0-9

Defining an event:

  1. Event name: select a name according to the naming convention:
    pasted-image-0-6
  2. Matching Elements: Elements similar to the selected element are detected and selected by default for the event. All the elements will be marked on the webpage. All the selected elements will trigger this event.
    • Pick one of the other options in the drop-down list to only trigger the event on this specific element, or select a different group of elements (elements included in each element group will highlight when you hover over the list items.
      pasted-image-0-7
    • Add elements from the page to the selection or remove elements you’ve already clicked on by holding down the ‘Ctrl’ key while clicking on the elements you want to add/remove.
  3. User Interaction: Choose whether the event will be tracked on hover or click.
    pasted-image-0-8
  4. Event Properties: You can attach properties to the event to get additional data, such as: the text from the element that was clicked, the user id from the URL, etc. For your convenience, you may select properties from a list of options:
    • Element: Track attributes from the element the user interacted with. Choose from the available attributes by checking the check-boxes next to them. If you want another element attribute for the property value, start typing the attribute name and an autocomplete will appear with the possible options – choose one of them to get the dynamic element attribute. If you don’t choose an option from the autocomplete, the value will be the static string you’ve entered. A sample value for the element will appear to the right of the property name. Click an attribute name to change the property name.
      pasted-image-0-5
    • URL: Record any part of the URL. The result will be dynamic, according to the value of the URL when the event is fired.
    • Relative Element: Record properties from another element on the page. Click the element you’d like to record attributes from. Hovering over possible elements will color them in orange (?).
      If you’re tracking multiple elements, and you choose a ‘relative’, there are two possible scenarios:

      • The properties of the chosen ‘relative’ will be recorded when interacting with either one of the tracked elements. In this case, all of the tracked elements will get the same property value. Click ‘Add Relative’ add more ‘relatives’ to record properties from.
      • The extension may detect elements in the webpage that are similar to the ‘relative’ and are ‘closer’ to the tracked elements. In this case, the property values recorded for different tracked elements will vary. Each element-relative pair will have an orange frame around it so you can see where the properties will come from for each element.
    • JavaScript: Add your own JavaScript code to be executed when the event is fired to add more dynamic properties not included in the options above.
  5. Save your event: Click on ‘Save Event’ when you’re done defining your event.

 

Events list

To view/edit existing events, click on the ‘Event List’ button in the menu.
A popup with the list of events created using the extension will appear.
Hovering over any of the list items will highlight the elements on the page associated with the event.
Clicking the pencil icon on a list item will open the event for editing.

  • Updating an event: to modify an existing event open it on the events list, make any changes, and click ‘Update Event’.
    pasted-image-0-10
  • Deleting an event: Delete the event by clicking on ‘Remove’ at the bottom-left.

 

Event log

Click on ‘Event Log’ in the menu to open the CoolaData live events table, which shows the data as it is recorded in the project.

 

View events stats

You can view the stats of events on your webpage. When not in the process of creating a new event, hover over an element with any events attached to it will show info and statistics for that element, such as:

  • The list of events defined for the element and their properties
  • The number of events fired in the last 7 days
  • A chart of the number of events fired over time.

event-stats

Print Friendly

JavaScript – Manual Configuration

Implementation

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

Step 1 – Initialization

To start tracking with the CoolaData JavaScript library, simply paste the following code into each page you want to track, before the closing </head> tag.

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

The above setup includes the recommended implementation options:

 

Step 2 – Track Events

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

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

Example:

Sending an event using JQuery on an HTML page. A function is called when a form’s send button is clicked (this example uses ninja forms). Using JQuery to extract the data filled in the form.

 

Full API Reference

init

The init function in the setup initializes a new instance of the CoolaDataTracker object. The following table includes all configuration options:

ParameterTypeMandatoryDefaultDescription
app_keyStringYesThe specific project app key provided by CoolaData
http_postBooleanNoFalseUse HTTP POST method instead of the default GET method
img_src_get_requestBooleanNoFalseSend an image (1x1 pixel) as GET request for XHR requests
disable_cookieBooleanNoFalseDisables 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_hostStringNoapi.cooladata.comReplace 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*BooleanNoFalseSend page_load event automatically every time a user views the page. Sent with page_url and page_title properties only (cannot be modified).
user_idStringNoFalseSpecify the user_id on the page's cooladata tracker init to associate all events (including track_pageload) to the current user.
izzyClickBooleanNoFalseAllows to use the CoolaData Eventualizer tracker to visually manage your events.

* Note: the track_pageload event is sent with the user_id specified in the init. If no user_id was specified in the init, a random user_id will be generated and the events will not be associated with the user_id sent in trackEvent.

trackEvent

Once you have the snippet on your page you can track events by calling cooladata.trackEvent with the event name and properties.

ParameterTypeMandatoryDescription
eventNameStringYesThe name of the event to report.
eventPropertiesObjectNoObject containing all additional properties in format: "property_name":"property_value". See example below.
user_idStringNoSend 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_epochNumberYes**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 propertiesString/NumberNoAny additional properties mapped in the project. See more information in Managing Properties.

trackEventLater

Track event later provides the ability to track a bulk of events. All events will stored on a local queue until 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 events that happen simultaneously, only after all have been concluded.

Example:

1. Add an event to the queue:

2. flush

Print Friendly

JavaScript – Auto Tracker (beta)

The JavaScript Auto Tracker SDK bring new automatic abilities to the JavaScript SDK. It enables sending events without any configuration except of simple initial implementation. Right after the initial implementation the Tracker will send a variety of events that enable the client to immediately get insights on his app/website.

This tracker is currently in beta phase.

Setup

To start tracking with the CoolaData Auto 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:

 

Recommended Configuration:

Alternatively, you can set each event specifically as in the following example:

Note: the ‘One Click SDK’ supports all functions and methods ( init  |  trackEvent  |  trackEventLater  |  flush) of the standard JavaScript SDK. For more information please see the documentation.

 

Auto Events

The events sent automatically with the tracker.

Page View

Event Type: Page View
Event Trigger: page loading
Event Structure (properties):
{
“event_name”: “Page Title”,
“eventType”: “Page View”,
“session_dua”: “as regular tracker “,
“referrer”: “Referre URL”,
“user_id”: “<sent by client || Coola User_id>”,
“page_id”: “<Unique>”,
“pageRefresh”: true | false ,
“event_timestamp_epoch”: “1449148357738”,
“url”: “URL”
}
Event preset configuration:
pageView : true | false (default is false)

 

Button click
Event Type: Button click

Event Trigger: click on any Button in the DOM

Event Structure (properties):
{
“event_name”: “elementText – Button Click”,
“eventType”: “Button Click”,
“session_dua”: “as regular tracker “,
“user_id”: “<sent by client || Coola User_id>”,
“page_id”: “page_id of Page View Event”
“event_timestamp_epoch”: “1449148357738”,
“url”: “URL” ,
“pageName”: “Page Title”,
“buttonType”: “Type attr”,
“buttonCounter”: “counter of button clicks in the same page_id”,
“durationFromPageLoad”: “duration from page load to the click”,
“durationFromLastClick”: “duration from last click to the click”
“elementText”: ” inner HTML of element”
}

Event preset configuration:
buttonClick : true | false (default is false)

 

Link click

Event Type: Link click

Event Trigger: click on any Link in the DOM

Event Structure (properties):
{
“event_name”: “elementText – Link Click”,
“eventType”: “Link Click”,
“session_dua”: “as regular tracker “,
“user_id”: “<sent by client || Coola User_id>”,
“page_id”: “page_id of Page View Event”
“event_timestamp_epoch”: “1449148357738”,
“url”: “URL” ,
“pageName”: “Page Title”,
“href”: “href attr”,
“linkCounter”: “counter of link clicks in the same page_id”,
“durationFromPageLoad”: “duration from page load to the click”,
“durationFromLastClick”: “duration from last click to the click”
“elementText”: ” inner HTML of element”
}

Event preset configuration:
linkClick : true | false (default is false)

 

Input click
Event Type: Input click

Event Trigger: click on any Input Element in the DOM

Event Structure (properties):
{
“event_name”: “Page Title – Input Click”,
“eventType”: “Input Click”,
“session_dua”: “as regular tracker “,
“user_id”: “<sent by client || Coola User_id>”,
“page_id”: “page_id of Page View Event”
“event_timestamp_epoch”: “1449148357738”,
“url”: “URL” ,
“pageName”: “Page Title”,
“inputType”: “input type attr”,
“inputName”: “input name attr”,
“fromId”: “from id attr”,
“fromFieldsId”: “all form inputs id attr”,
“fromFieldsName”: “all form inputs name attr”,
“inputCounter”: “counter of inputs clicks in the same page_id”,
“durationFromPageLoad”: “duration from page load to the click”,
“durationFromLastClick”: “duration from last click to the click”,
“durationInputField”: “duration from start click to the focus out”,
“elementValue”: ” value of element (only if input_duration flag is TRUE”)
}

Event preset configuration:
inputClick : true | false (default is false)
input_duration: true | false (default is false)
If TRUE will send duration from start click – focus out and the real element Value

 

Select click
Event Type: Select click

Event Trigger: click on any Select Element in the DOM

Event Structure (properties):
{
“event_name”: “Page Title – Input Click”,
“eventType”: “Input Click”,
“session_dua”: “as regular tracker “,
“user_id”: “<sent by client || Coola User_id>”,
“page_id”: “page_id of Page View Event”
“event_timestamp_epoch”: “1449148357738”,
“url”: “URL” ,
“pageName”: “Page Title”,
“inputType”: “input type attr”,
“inputName”: “input name attr”,
“fromId”: “from id attr”,
“fromFieldsId”: “all form inputs id attr”,
“fromFieldsName”: “all form inputs name attr”,
“inputCounter”: “counter of inputs clicks in the same page_id”,
“durationFromPageLoad”: “duration from page load to the click”,
“durationFromLastClick”: “duration from last click to the click”,
“elementValue”: ” value of Selected
}

Event preset configuration:
inputSelectClick : true | false (default is false)
select_change : true | false (default is false)
If TRUE will send the real element value

 

Textarea click
Event Type: Textarea click

Event Trigger: click on any Textarea Element in the DOM

Event Structure (properties):
{
“event_name”: “Page Title – Textarea Click”,
“eventType”: “Textarea  Click”,
“session_dua”: “as regular tracker “,
“user_id”: “<sent by client || Coola User_id>”,
“page_id”: “page_id of Page View Event”
“event_timestamp_epoch”: “1449148357738”,
“url”: “URL” ,
“pageName”: “Page Title”,
“inputType”: “Textarea type attr”,
“inputName”: “textarea name attr”,
“fromId”: “from id attr”,
“fromFieldsId”: “all form inputs id attr”,
“fromFieldsName”: “all form inputs name attr”,
“inputCounter”: “counter of inputs clicks in the same page_id”,
“durationFromPageLoad”: “duration from page load to the click”,
“durationFromLastClick”: “duration from last click to the click”,
“durationInputField”: “duration from start click to the focus out”,
“elementValue”: ” value of element (only if input_duration flag is TRUE”)
}

Event preset configuration:
inputTextareaClick: true | false (default is false)
input_duration: true | false (default is false)
If TRUE will send duration from start click – focus out and the real element Value

Print Friendly

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:
  • As a Maven 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:

 

Step 3 – Initialization

Initialize the tracker by calling the CoolaDataTracker.setup method:

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

 

Step 4 – Track Events

Call the trackEvent method from your activity:

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:

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.

Setup Parameters:

NameTypeMandatoryDescription
contextContextYesThe application context
optionsCoolaData Tracker OptionsYesSee below

Setup Options:

NameTypeMandatoryDescription
appKeyStringYesThe AppKey provided by CoolaData.
userIdStringNoExplicit 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:

Tracker Parameters:

NameTypeMandatoryDescription
eventNameStringYesThe name of the event to report
userIDStringNoExplicit user ID for this event - should only be provided for manual user management
sessionIdStringNoExplicit session id for this event - should only be provided for manual session management
eventPropertiesMapNoThe custom properties to be sent with the event

Examples:

  • Track a “search” event:
  • Track an “add to cart” event with “product type” and “amount” properties:
  • Track a “checkout” event with “status”, “amount” and “username”:

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:

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:

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:

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

 

Change Notes

datechange
20/12/2015Ability 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/2015Start using OkHttp as HTTP layer, yet remained ability to use old HTTP layer for compatibility issues (.setUseOldHttpClient(true) option)
7/11/2015Move using standard JSON library (not sure whether it worth adding to release notes, anyway added this here)
19/10/2015Time calibration meachnism improvement (avoid excessive calls to time calibration API)
14/10/2015Add 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/2015Add time callibration to send events using server time
20/9/2015Exception logging
13/4/2015Added thresholds support to controll memory used by tracker (queues while device is offline, or between flushes), however not in use yet
19/1/2015Added 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/2015Generated random UID became persistent between application sessions. Added device connectivity state check.
31/12/2014User 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.
Print Friendly

iOS

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:

  1. Create the Podfile
    • If this is your first Pod in your iOS project, create a file named Podfile:
    • If you already use CocoaPods in your project, add a reference to CoolaData ‘s Pod:
  2. Open the terminal app, change dir to your xcode project and run:

    This command creates an xcode workspace for your project, and configures it to use CocoaPods.
  3. 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.

Add the following code inside the application:didFinishLaunchingWithOptions function.

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.

Full API Reference

setupWithApiToken

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

NameTypeMandatoryDescription
appKeyNSStringYesThe AppKey provided by CoolaData.
serviceEndPointNSStringNoThe base URL for the CoolaData Tracker to use when accessing the CoolaData gateway.
userIdNSStringYesThe 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.
sessionIdNSStringNoThe Session ID relevant for this instance of the CoolaDataTracker.

CoolaDataDeliveryResult

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

NameTypeDescription
eventIdNSStringThe ID of the event as specified in the track event.
statusBOOLThe status of the delivery. False or True.
deliveryStatusDescriptionNSStringThe description of the status state.
deliveryStatusCodeIntThe HTTP error code of the delivery attempt.
responsePropertiesNSDictionaryCustom properties to be sent with the event result.

trackEvent

Track user’ event

NameTypeMandatoryDescription
eventNameNSStringYesThe name of the event to report. This parameter is mandatory.
withEventIdNSStringNoThe Event ID relevant for this event. This parameter is optional. If response block is passed, event id must also be provided.
userIdNSStringNoThe 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.
sessionIdNSStringNoThe Session ID relevant for this event. This parameter is optional.
optionalDataNSStringNoThe custom properties to be sent with the event. This parameter is optional.
errorNSErrorNoA 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.
responseBlockBlockNoWhen 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.

Print Friendly