Print Friendly, PDF & Email

What is an Event?

CoolaData collects user behavior data in the form of events.
An event is an action performed on your site/app.
Each event must be associated with the user who performed it, the time it happened, and the name of the event, and can include additional properties.

For each event, you can manage the following meta data:

  • Event name: The event name as sent to CoolaData and used in queries. Can use any characters, including spaces and capital letters. Event names are not case sensitive, so ‘Login’ and ‘login’ will be treated as the same event.
  • Category: Logical association. Can be used in queries to query multiple events simultaneously. Can be modified at any time and does not affect data storage.
  • Include in path: The path is used for CoolaData’s behavioral functions. Events not in path will not be included in these functions. Disable this only for events you want to exclude from behavioral analysis.

Please note the maximum amount of events per project is 1500 events.

Tracking events

CoolaData enables you to track your users’ behavior by sending events (comprised of properties).

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. All other properties are optional – add as many as you want, according to your needs.

In addition to the properties that you include, each CoolaData Tracker (SDK) automatically enriches each event with various properties. The following shows the same event (as shown above) 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"
}

Best practice:

  1. Create a spreadsheet listing the events to be sent to CoolaData, including the event name and a description of each event.
  2. For each event, describe the properties to be included in that event, including its property name and a description. Remember – any property can be sent with any event.
    For example, we recommend creating a single button_clicked event that has a button_name property, rather than creating a separate event for each button clicked, such as: button_ A_clicked, button_ B_clicked, button_ C_clicked,

Mapping modes

CoolaData provides two modes for controlling the automatic generation of events and properties.

  • 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.
  • Locked: 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.

To change the mapping mode:

  1. Go to Project – Settings
  2. Choose either Self-Learned or Lock mode
  3. Click Apply to save the change

Best Practice:

Either control all the events and properties or start by collecting them and filter them later:

  1. Full control: 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. Change your project mapping mode to Lock.
    2. Plan which events and properties will be considered valid.
    3. Define the valid events.
    4. Define the valid properties.
  2. Collect and filter: 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

When working in Lock mode, define your events using the events management interface.

  1. Open Project – Events.
  2. Click the Add button in the top right of the window to add a new event:
    4-3
  3. 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.
      For example, 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).

Event Timestamps

CoolaData provides these options for specifying the timestamp of an event:

  • Device’s Timestamp (Default) – The CoolaData Tracker automatically adds the device’s timestamp.
    CoolaData automatically enriches each event with an event timestamp (named event_time_ts). This timestamp is determined by the device’s timeclock and indicates when the event happened, meaning when it was sent by your app using the CoolaData Tracker. CoolaData automatically stores and presents event timestamps in UTC time standard. The CoolaData Tracker also automatically adds a timezone_offset property to each event specifying the device’s time zone offset from UTC time, in hours. For example, -2.5.
  • Your Own Timestamp (Optional) – You can add your own timestamp to the event which overrides the device’s timestamp (described above).
    To specify your own timestamp for each event, simple add the event_time_ts property to the event’s JSON. Specify this timestamp in 13-digit format (milliseconds). CoolaData then uses this timestamp instead of your device’s (event_time_ts – described above).
    When using JavaScript Tracker or CoolaData REST API  in order to include your own timestamp, simple include the event_timestamp_epoch property (instead of event_time_ts – described above) in the event’s JSON. CoolaData then uses this timestamp which is UTC time standard.
    This option is only relevant when CoolaData is not set to use server timestamp,.
  • CoolaData Server Timestamp (Optional) – CoolaData assigns its own server’s timestamp to all events.
    In general the timeclocks of some devices’ may not be accurate. Upon request, CoolaData can configure your system so that CoolaData automatically assigns the timestamp of the CoolaData server to each event instead of the timestamp of the device that sent the event. To activate this feature, contact your CoolaData customer success representative.
    Benefit – The advantage of using this feature is to ensure that all the collected data is synchronized to the same clock, and that no events are rejected because of invalid dates.
    When this feature is activated, all timestamps that you send with the event are ignored and an accurate UTC timestamp is assigned instead. If you would like to use this feature and would also like to send your own timestamp, then add your own timestamp to each event in another property. For example, you could name it client_timestamp.

CoolaData automatically performs a sanity check of all event timestamps. By default, an event is considered Invalid when its timestamp is more than 12 hours into the future or 30 days into the past. For example, future timestamps may occur when an end user’s clock is set incorrectly. These types of events are not stored in CoolaData and appear in the Invalid List with the following reason – Future event sent or Past event sent.

Print Friendly, PDF & Email