Properties are used to add additional information to an event. For example, we can add item type price to an “item_added” event.
The number of properties for each event is only limited by the total number of available properties in the project.
You can send any properties with any event you send to CoolaData.
CoolaData provides two types of properties: standard and virtual properties (see below).

 

Properties

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

  1. Open Project projecticonProperties  properties.
  2. Click on Add button in the top right of the window to add a new property.
    4-5
  3. Select Property. The following displays:
    4-6
  4. 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.
      • Property names must begin with a letter, and can contain letters, numbers, and underscores (space and dash are not supported).
      • Names cannot use any CQL functions, such as: Select, From, Where, As, NULL, And, Between, Join, Left, Outer, Inner, On.
      • Names cannot use a CoolaData reserved words – the following is a list of CoolaData reserved words:
        internal_user_id
        internal_session_id
        user_alias
        session_clean_path
        session_duration
        session_end_time_ts
        session_events_counter
        session_full_category_path
        session_full_clean_category_path
        session_full_clean_path
        session_full_path
        session_funnel_path
        session_serial_event_counter
        uid
        sid
      • Properties names are not case sensitive, so ‘User_Level’ and ‘user_level’ will be treated as the same property.
        Properties values are case sensitive, so the values ‘US’ and ‘us’ will be treated as two distinct values.
    • 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: Integer, Float, String, or Timestamp.
      • In order to send a Boolean data type (such as Yes or No), either use string (TRUE/FALSE) OR integer (1/0).
      • 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.
      • It is not possible to change a property’s data type once it is created. To do so, the property and all the data saved with it until that point will have to be deleted. It is recommended to create an new property instead in order to avoid data loss.
    • Scope: Select the scope of this property. We recommend that when you are first starting out with CoolaData, that you use EVENT scope. It is not possible to change a scope of a property once it is created. To do so, the property and all the data saved with it until that point will have to be deleted. It is recommended to create a new property instead in order to avoid data loss
      • Event: data applicable only to a specific event.
        Example: “price”:”52.50″ – the next event in the session will not have a value for the “price” property unless specifically sent with it.
      • Session: data applicable to the entire session, i.e. the specific visit to the site/app. Session scope data will be added to all events in the session following the event that included this property.
        Example: “device_type”:”iphone 6″ – all the following events in the session will include the this property’s value. If during the same session, a new event with a different value for this property is sent, it will take over for all consecutive events in the session. The final value received will be the one saved for the session, i.e. will be the value returned when querying only at the user/session scope. This property will not contain any value in the next sessions until updated per that session.
      • User: Applicable to a user’s lifetime. A user scope property will be added to all events of this user following the event that included this property, including in future sessions.
        Example: “user_email”:”sam@work.com” – assuming that the user property will continue to be true for all future actions, every event of the same user from that event on will include the user property “user_email” with the value “sam@work.com”. This will continue unless the value is overwritten by a new event with a different value for this property, which will take precedence from the new event forward.
      • Automatic Scope Mapping: When using the self-learned mapping, the scope is set automatically based on the metadata received. The default scope is event. To change the automatically assigned property scope, add a prefix to the property name. Once a property scope is saved the property scope prefix will be ignored, i.e. if the property scope prefix is changed or removed, it will not change the scope of the event. The prefixes are:
        • {s} for SESSION scope. Example: {s}referral_id
        • {u} for USER scope. Example: {u}source_campaign
      • Enriching events: Enriching events with user/session scope properties requires the value to first be saved – it will only take effect with the events received after it. Therefore, if multiple events are sent simultaneously, these events might not include the property value.
    • 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
      Examples of when to turn this on (refresh): when it represents recently published articles, popular songs and so on.
      Examples of when to turn this 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.

 

Examples

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.

  • 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″.

An example of an event with a lot of properties:

 

Virtual Properties

A Virtual Property is based on a JSON or an expression that you define, typically depending on the value of another property. For example, the domain of an email property, or a group of property values, for example. A virtual property is a client side calculation. It allows you to create additional dimensions on the data by applying rules that are used for the retrieval of data (including aggregation).

A Virtual Property can be used throughout Cooladata in the same way as a regular property.

There are two kinds of Virtual Properties:

  • Virtual Dimension: the equivalent to a CASE expression
  • Virtual Measure: any CQL function

 

Virtual Dimension

A Virtual Dimension property enables you to replace the value of the property sent in the event with a specific set of strings according to the logic that you define. This is typically done in order to categorize events (meaning to divide them into groups) according to the value of the property sent in the event. After the event is stored in CoolaData, you can query this property in the same way that you would any other property.

The property configuration is done using a JSON which contains the following:

  • datatype: string/float/integer/timestamp
  • default: the property’s default value, in case it fails to match any of the conditions (not mandatory)
  • mapping: a list of values that match Boolean expressions using other properties. The value will be determined by the first condition that qualifies as true.

 

Examples:

  1. Mapping the property “item_id” to the actual item name:
  2. Mapping the default property “session_ip_country” to regions:

 

Virtual Measure

A Virtual Measure property enables you to replace the value of a property sent in an event using a CQL function that you define in the CoolaData Administrator console (as described below). After the event is stored in CoolaData, you can query this property in the same way that you would any other property.

Examples

  1. Multiplying item_price with item_quantity to get the total income for the item. The expression will be:

  2. Converting EUR values to USD by multiplying by the exchange rate (the rate can be updated at any time any will effect all data retroactively). The expression will be:
  3. Extracting domain from an email using regular expression functions:

 

New Virtual Property

  1. Open your workspace in the CoolaData Administrator console and select Project  → Properties  properties.
  2. Click on Add  button in the top right of the window to add a new property.

9-2

  1. Select Virtual Dimension or Virtual Measure.
  2. Configure the expression/JSON.
  3. Click the Save button.

 

Common Properties

Each CoolaData tracker automatically enriches the events that you send by adding more properties (these are also called common properties).

For a full list of common properties see Common Properties.

Common properties are added to all projects. These include data collected automatically by Cooladata trackers according to the specific OS, and enrichments done on the event, session and user level.

 

User Level:

We identify the user_id, and then look at everything we know about this user. For every event we collect we look to see whether the user was already active in the past. If he was, we assign the same user_internal_id to that user, connecting all his data to the same user_id.

Any user scope property you previously sent is added to the events we received on the user, such as: email, age, address, etc.

Additional information we learned during the last events is added to the user profile to be used in the next events this user will perform.

 

Session and Event Level:

All the session data we received earlier to that session is added to the event. For example, when we identify a utm_source or a url_referrer parameter in the first event of the session we will copy this information (property) for all the following events during that same session (or until a new value for this property is received). The same is done for all the session scope properties you defined.

  • Geo location: from the IP of the event we deduce the country, city, state and region for any event we receive.
  • Device: based on the “device user agent” we add to the event information such as device type, operating system, browser and so on.
  • URL: we add to the the UTM tags and URL referrer based on the URL of the event, broken down to URL, UTM and traffic_source properties.
  • is_new: on the first session the user ever did we mark all the events in the session as new (is_new=1). You can use this to distinguish new from returning users.
  • event_duration: we add the time (in milliseconds) it took the user to perform each event to the event. This is done by calculating the time that passed from the current event to the following one performed by the same user. Thus, the duration of the last event of every session is always zero. This enables you to see where users stall,  or what phases in their path are carried quickly.
  • session_duration: the total time passed from the first event in the session to the last. We calculate this when the session is completed (30 mins of inactivity,  configurable per project), to enable the analyst to easily understand session durations and the session duration distribution.
  • session_length: the number of events the user has performed during the session. We add this number to the session to enable the analyst to see how many events are performed during a session, for example to easily identify extremely short ‘bounce’ sessions.

 

Full Property List:

PropertiesDescriptionJSiOSAndroidASUnity
app_idThe app/bundle ID in the Play/Apple stores, Bundle ID. E.g. com.mycompany.myapp++
app_versionThe version of the app. E.g. 2.3.1++
browser_nameBrowser Name. E.g. Chrome, Safari+++
browser_versionThe version of the browser. E.g. 10, 11+++
carrierWireless carrier of the device owner. E.g. Orange, Vodafone++
connectivity_stateThe connectivity state of the device. E.g. Mobile, WiFi, Offline+++
customer_user_idThe user id of the hosting app.+++++
device_brandThe marketing brand of the device. E.g. iPhone 4, Samsung Galaxy S III+++++
device_manufacturerThe device manufacturer name. E.g. Samsung, Apple+++
device_modelThe device model name. E.g. "iPad 3,4", GT-I9300+++++
device_nameThe user defined name of the device. Note: on Android, this property is not supported and always contains the string "".+
device_orientationThe device orientation. E.g. Portrait, Landscape+++
device_osThe Operating System of the device. E.g. Android, iOS+++++
device_os_versionThe OS version of the device. E.g. 4.1+++++
device_screen_sizeThe width and the height of the device screen. E.g. 300x400++++
device_typeThe type of the device. E.g. Desktop, Mobile, Tablet++++
device_unique_identifierA unique device identifier. In iOS it will return UIDevice identifierForVendor, and in Android the device IMEI.+
event_time_tsThe timestamp of the event+++++
install_referrerInstall Referral is used to track the installation source of the app.+
ip_cityThe city of the event sender, extracted from the IP+++
ip_countryThe country of the event sender, extracted from the IP.+++
ip_latitudeThe latitude location of the event sender, extracted from the IP.+++
ip_longitudeThe longitude location of the event sender, extracted from the IP.+++
ip_regionThe region of the event sender, extracted from the IP.+++
location_altitudeThe altitude, available only if the user permitted to access location and supported by device.+
location_latitudeThe latitude location, available only if the user permitted to access location+
location_longitudeThe longitude location, available only if the user permitted to access location+
page_titleThe web page's title tag.+
page_urlThe URL of the page the user was on when the event was sent. Sent with page_load events by default.
page_url_paramsAll params included in the URL, after question mark character of the page the user was on when the event was sent. Sent with page_load events by default.+
referring_domainThe the domain that users "came from" when visiting your page.+
referring_urlThe the URL that users "came from" when visiting your page.+
session_durationThe duration of the session in milliseconds.+++++
session_idA unique ID that assigns a specific user for the duration of that user's visit.+++++
session_screen_scaleThe current screen resolution, in this format: {SCREEN_WIDTH , SCREEN_HEIGHT}+
time_in_appThe time in seconds from the Cooladata tracker initialization (usually from application load time if Cooladata tracker is initialized when the application loads).+
timezone_offsetThe device time zone offset from UTC time, in hours. E.g. -2.5+++
tracker_typeCoolaData tracker type. E.g. Android, iOS++++
tracker_versionCoolaData tracker version. E.g. 2.1.0++++
traffic_sourceA combination of the page URL and the page referrer to infer where traffic to the website has come from.+
user_idCoolaData internal user id. Always use the property when applicable.++++
user_local_timeThe user local time calculated based on the UTC time + timezone offset+++
utm_campaignCampaign Name - Used for keyword analysis. Use utm_campaign to identify a specific product promotion or strategic campaign. E.g. spring_sale++
utm_contentCampaign Content - Used for A/B testing and content-targeted ads to differentiate ads or links that point to the same URL. E.g. logolink, textlink++
utm_mediumCampaign Medium - Used to identify a medium such as email or cost-per- click. E.g: cpc++
utm_sourceCampaign Source - Used to identify a search engine, newsletter name, or other source. E.g. google++
utm_termCampaign Term - Used for paid search to note the keywords for this ad. E.g. running+shoes++
Print Friendly, PDF & Email