Events Overview

CoolaData enables you to track your users’ behavioral funnels by sending website/app events (comprised of properties) to CoolaData.

The following is an example of an event sent to CoolaData as a JSON –

{“event_name”:”deposit_server”,”transaction_id”:”63219″,”session_os”:”PC”,”depositamount”:”100″,”pearlsamount”:”0″,”blackpearlsamount”:”0″}

The only mandatory field that you must enter in an event is event_name, (which in this example) has the value deposit_server). An event name describes the event that occurred. You can specify any event name. For example, item_open, search_performed, game_level_3_achieved and so on.

All other properties are optional. You can add as many as you want according to your needs.

In addition to the properties that you had, each CoolaData Tracker (SDK) automatically enriches each event with various properties.

GSSC 1 To read about the properties that CoolaData automatically enriches in events.

GSSC 1To plan which events to track.

The following shows the same event (as shown above) sent as it arrives at CoolaData, after a CoolaData tracker automatically added (enriched) the user ID and the event’s timestamp –

{“user_id”:”123456″,”event_time_ts”:”1467763537524″,”event_name”:”deposit_server”,”transaction_id”:”63219″,”session_os”:”PC”,”depositamount”:”100″,”pearlsamount”:”0″,”blackpearlsamount”:”0″}

GSSC 1To see an example event with many properties.

GSSC 1To see how to override the user ID and the event’s timestamp.

Best Practice Tip – Here is an example of an efficient and an inefficient way to send a button click event – It is preferable to create a single button_clicked event that has a button_name property. It’s not efficient to send a different event for each button that is clicked, such as button_ A_clicked, button_ B_clicked, button_ C_clicked and so on.

Events and Properties – Best Practices for Getting Started

Planning Events and Their Properties – Best Practices

When you get start working with CoolaData, we recommend filling in an Excel sheet listing the events to be sent to CoolaData, including the event name and a description of each. Put a link to here from the General Getting Started topic

In addition, for each event name, we recommend describing the properties to be included in that event, including its property name and description. Any property that you define can be sent with any event.

GSSC 1To learn about property scopes.

GSSC 1To download an Excel sheet that has columns that you can fill in.

GSSC 1To plan which events to track.

Best Practice Tip – Here is an example of an efficient and an inefficient way to send a button click event – It is preferable to create a single button_clicked event that has a button_name property. It’s not efficient to send a different event for each button that is clicked, such as button_ A_clicked, button_ B_clicked, button_ C_clicked and so on.

Getting Started Defining Events and Their Properties – Best Practices

Self-learning Versus Lock Mode

CoolaData provides two modes for controlling the automatic generation of events and properties. Self- learned is the default mode. Contact your CoolaData customer success representative if you would like to change to Lock mode.

  • Self-learned – This is the default option. This means that all event names and all their properties are accepted by CoolaData (and are not defined as invalid). After each event and its properties are automatically defined by CoolaData, all subsequent events must arrive with properties that have the same data type. Otherwise, they are defined as invalid and not entered into CoolaData. We recommend that initially you start working with CoolaData using this option. Afterwards, you can start using the Lock option, described below.
  • Lock: This option enables you to control which event names and event properties are accepted by CoolaData. This means that only previously defined events and properties are considered valid, whether they were Self-learned or defined by you.
    • New Events Are Invalid – New events are not accepted and are stored in an Invalid Events table which you can review.
    • New Properties Are Not Accepted – New properties in an event are not accepted into CoolaData. The event itself (including all its other properties) is accepted into CoolaData. However, the new properties are not accepted – they are simply dropped.
    • Different Data Types Are Not Accepted – Properties with a different data type than originally defined are not accepted into CoolaData. All these events are listed in an Invalid Events table with a description that you can review.

GSSC 1To learn how to define new events and new properties yourself.

Controlling New Events and Properties – Strategies for Getting Started

Here are two strategies for getting started defining the valid events and properties to be accepted by CoolaData.

  • Total Control – Recommended
  • Initial Freestyle – Then Lock down
Total Control – Recommended

This option gives you complete control over which events and properties are valid in CoolaData, meaning all other events are not accepted by CoolaData and will appear in the Invalid Events list.

  1. Contact your CoolaData customer success representative to change to Lock mode.
  2. Plan which events and properties will be considered valid.
  3. Define the valid events.
  4. Define the valid properties.
Initial Freestyle – Then Lock down

With this option CoolaData automatically generates events and properties from incoming events. You then get rid of the unwanted ones and lock down (prevent) the generation of new events and properties.

  1. By default, CoolaData operates in Self-learning mode.
  2. Send a few samples of each kind of event to CoolaData. CoolaData will automatically define these events and their properties as valid.
  3. Review all the automatically generated events and properties and then disable all unwanted events and delete all unwanted properties.
  4. Contact your CoolaData customer success representative to change to Lock mode.
  5. Notify all CoolaData integrators not to send the disabled events or the deleted properties because they will be sent to the Invalid Events list.

Defining an Event

To start working with CoolaData, either –

  • Define all the events that CoolaData will accept (as described below) and work in Lock mode. To work in Lock mode, contact your CoolaData customer success representative.

– OR –

  • Work in Self-learned mode (the default mode) so that all events names and properties are automatically defined in CoolaData. In this case, there is no need to read the following.

To create an event:

  1. Open your workspace in the CoolaData Administrator console and select Project .
  2. Click the Add button in the top right of the window to add a new event:

4-3

  1. Fill in the window as follows and click the Save button.
    • Name (Mandatory) – Describe the event that occurred in lowercase without spaces. For example, item_open, search_performed, game_level_3_achieved and so on.
    • Category – Select the value Other.
    • Active – Active is the default. If needed, deselect this option to specify that events with this Name (described above) are not loaded into CoolaData (Not Active). Non Active events are not listed in CoolaData’s Invalid Events list.
    • Include in Path – A path defines a specific sequence of events in the same user session. CoolaData provides various visualization options showing the path of events in a user session, such as a Funnel report or Cohort report. Only events for which this option is selected 4-4 are included in these visualizations.

An example of an event that you may not want to include is a keep_alive event that verifies the devices’ connection.
Regardless of the value selected in the Include in Path field (meaning even if it is off), the event still affects the session_duration (which is the duration of the session, in milliseconds) and is still counted in the session_event_counter (which is the number of events in the session).
GSSC 1Click here for more details about ending a session.

Defining a Property

Here’s how to define the properties that are accepted by CoolaData.

Note – Self-learning mode is the default CoolaData operation mode. In Self-learning mode, there is no need to define properties. Therefore, you can skip this section, if CoolaData is configured to Self-learning mode (not Lock mode).

Each property that you define can belong to any event sent to CoolaData.

To define a property:

  1. Open your workspace in the CoolaData Administrator console and select Project projecticonProperties  properties.

4-5

  1. Click on Add button in the top right of the window to add a new property.
  2. Select Property. The following displays:

4-6

  1. Fill in the window as follows and click the Save button.
    • Name – Describe the property of the event in lowercase without spaces. For example, button name, url, application_name, amount and so on. This is the name that appears in CoolaData in all visualizations and which you can query.
    • Source – Specify the name of this property as it appears in the JSON of the event that arrives at CoolaData. CoolaData uses the Name property (described above) like an alias. Use the Name property to query your data.
    • Data Type – Specify the data type, such as Integer, String, Timestamp and so on.

GSSC 1Check this out to see the syntax for sending properties with various data types.

    • Scope – Select the scope of this property. We recommend that when you are first starting out with CoolaData, that you use EVENT scope.
      • EVENT (default) The value of this property only applies to the event in which it appears. For example, deposit_amount or page_viewed.
      • USER – The latest value of this property affects all future events of the same user. For example, user_status or user_address.
      • SESSION – The latest value of this property affects all events of the same user in the same session (from the session’s start until its end). For example, user_location or user_app_version.
    • Classification – Selecting this option determines how CoolaData handles this property in the user interface.

Generally, CoolaData uses a property’s Data Type field (described above) to determine how to handle that property in the CoolaData Admin Console and database. However, in some cases, you may want the property to be handled differently than its data type indicates. For example, when a property is defined with the data type String, but that property contains a numeric value.

      • DIMENSION – Typically, this property is a string that describes something. The following is an example of filter operators that are offered by CoolaData for a DIMENSION property. These operators are all suited for strings – !!!!!!!!!!!!!!!!!!!!!!!!

4-7

      • MEASURE – Typically, this property is a numeric value. For example, enabling aggregation and averaging, as well as slicing by comparative operators, such as less than (<) or greater than (>). The following is an example of filter operators that are offered by CoolaData for a MEASURE property. These operators all suited for numeric values –

4-8

    • Lookup values refreshing – CoolaData manages lookup tables for up to 300 of the values received for each property. Select this option to specify that CoolaData keeps the 300 most recent values of this property versus the first 300 values received by CoolaData. By default, this option is not selected, meaning that the first 300 values are added to the lookup table and newer values are not added.

The following shows an example of where this lookup table appears in the user interface. This example shows a filter definition dropdown menu showing the values from a lookup table –

4-9

Tip – Here are a few examples of when it is a good idea to turn this option on (refresh) – when it represents recently published articles, popular songs and so on. Here are a few examples of when it is a good idea to turn this property off – when it represents countries, statuses or device types, because there’s not more than 300 such values, and they don’t change very often.

Tip – In order to send a Boolean data type (such as Yes or No), use string data type and enter the values Yes and NO. Another option is to specify an Integer data type and to enter the values 1 and 0.

Tip – In Self-Learning mode, CoolaData automatically interprets a timestamp property in an event as String data type regardless of whether it was sent in the JSON inside quotes or not. The best way to ensure that CoolaData handles a property as Timestamp data type is to define it as Timestamp in the Data Type field (described above) before the event is sent with this property. The event must also be sent according to the proper property data type syntax.

Event Property Data Type Syntax

Here’s the syntax for sending properties with various data types.

After you define a property’s data type or after CoolaData has learned its data type (when in Self-Learning mode), then any event that arrives afterwards with a different data type (as determined by the syntax below) is sent to the CoolaData Invalid Events list.

JSON Structure Example

{“event_name”:”deposit_server”,”transaction_id”:”683219″,”session_os”:”PC”,”depositamount”:100,”pearlsamount”:”0″,”blackpearlsamount”:”0″}

  • Integer Property – Must be a plain integer number. For example, “depositamount”:100.
  • Float Property – Must be a float number. For example, “depositamount”:100.3.
  • String Property – Must be encased in double quotes. For example, “event_name”:”deposit_server”.
  • Custom Timestamp Property – This type of property is added to an event by you. It must be encased in double quotes and using timestamp format. For example, “metadata_command_create”: “2015-10-21T18:02:13.627382+00:00”.
  • Common Event Timestamp Property – This type of property is automatically added by CoolaData to an event. It must be encased in double quotes and using Epoch timestamp format. For example, “event_timestamp_epoch”: “1461263697530”.
  • User Identifier – The user_id specifies the identifier of the end user who performed the event. The user ID can be assigned by you or by a CoolaData Tracker. To specify your own identifier for each user, simple include the user_id property in the event’s JSON encased in double quotes. CoolaData will not overwrite it. For example, “user_id”: “1”.
  • Session IP – The session_ip specifies the IP address of the user’s session in which the event occurred. The session IP may be assigned by you or by a CoolaData Tracker. To specify your own session IP, simple include the session_ip property in the event’s JSON encased in double quotes. CoolaData will not overwrite it. For example, “session_ip”:”192.168.255.255″.

Example Event

Here’s an example of an event with a lot of properties.

{

“formId”: “null”,

“referring_url”: “http://click.everest/mountain/link/agent/

“enviroment”: “Abalon”,

“event_timezone_offset”: “8”,

“tracker_version”: “3.2.1”,

“session_dua”: “Mozilla/5.0 (Linux; Android 4.4.2; SM-N900S Build/KOT49H) AppleWebKit/537.36 (KHTML, like Gecko) Version/4.0 Chrome/30.0.0.0 Mobile Safari/537.36”,

“sample_version”: “2.3.4.1”,

“url”: “https://www.bla.com/abcd/pages/default/

“tracker_type”: “javascript”,

“session_platform”: “Linux armv7l”,

“accountId”: “67890”,

“history_length”: “1”,

“websiteId”: “12345”,

“user_id”: “167554-362e001f”,

“session_screen_size”: “360×640”,

“cookie_size”: “2817”,

“event_timestamp_epoch”: “1569449258730”,

“event_name”: “nova_page_view”,

“feedback_uuid”: “null”,

“referring_domain”: “click.abc”

}

Print Friendly