Events from Browser

See the Overview for details about setting up the Datacoral Collect Events Slice.

Step 1: Loading and initializing the tracker

Include the following tag to your page to load the tracker:

URL_ENDPOINT : The URL of your Datacoral Events API gateway. Ex. events.dccustomer.datacoral.io

API_KEY : The Datacoral API key to authorize the events invocations. Ex. 1js9q5Gqmk2VDv2omx2WI3yUGV0K7b464fWUJXDX

ENVIRONMENT : Set the environment as dev or prod, based on the emitter of the events

NAMESPACE : The name of this Tracker instance to include with events sent to the collector. The namespace argument attached to every event fired by the new tracker. This allows you to later identify which tracker fired which event if you have multiple trackers running. Ex. landing_pages

APP_ID : Name of application to include with events sent to the collector. The application ID is used to distinguish different applications that are being tracked by the same Snowplow stack. Ex. "finance" or "hr"

<script type="text/javascript">
  ;(function(p,l,o,w,i,n,g){if(!p[i]){p.GlobalSnowplowNamespace=p.GlobalSnowplowNamespace||[];
  p.GlobalSnowplowNamespace.push(i);p[i]=function(){(p[i].q=p[i].q||[]).push(arguments)
  };p[i].q=p[i].q||[];n=l.createElement(o);g=l.getElementsByTagName(o)[0];n.async=1;
  n.src=w;g.parentNode.insertBefore(n,g)}}(window,document,"script","https://datacoral.com/instrumentation/js/1.0.0/dc.js","datacoral"));

 window.datacoral('newTracker', 'NAMESPACE', 'URL_ENDPOINT',
   {
     appId: 'APP_ID',
     platform : 'desktop',
     apiKey : 'AP_KEY',
     datacoralEnv: 'ENVIRONMENT',
     forceSecureTracker : true,
     post: true,
   });
</script>

CORS is enabled for the above endpoint - it will accept requests from only the configured origin. Please provide us the origin to be supported for each environment.

Step 2: Tracking page views and other events

Page views

If you need to track page views, add the following method right after tracker is initialized, before </script>:

window.datacoral('trackPageView');

Custom structured events

To track various user interactions and AJAX events, use the trackStructEvent For example, to track a button click, write an 'onClick' event handler as below

<button onClick="buttonClick();">Track click</button>
function buttonClick(){
    window.datacoral('trackStructEvent', 'some category', 'some action', 'some label', 'some property', 0.1);
}

Customer structured events give you five properties: category (string), action (string), label (string), property (string), value (float). These become the se_category, se_action, se_label, se_property, and se_value columns in Redshift, respectively.

If you want more than five fields then use a custom unstructured event.

Custom unstructured events

To track various user interactions and AJAX events, use the trackUnstructEvent For example, to track a button click, write an 'onClick' event handler as below

window.datacoral('trackUnstructEvent', {
    name: 'viewed_product',
    data: {
        productId: 'ASO01043',
        category: 'Dresses',
        brand: 'ACME',
        returning: true,
        price: 49.95,
        sizes: ['xs', 's', 'l', 'xl', 'xxl'],
        availableSince: new Date(2013,3,7)
    }
});

The event name will be reflected in the event_name column in redshift and the data field above will be reflected in the ue_data JSON column. You can use JSON_EXTRACT_PATH_TEXT(ue_data, ‘<field>’) to extract a particular field in Redshift.

Forms

Use the enableFormTracking method to add event listeners to turn on form tracking by adding event listeners to all form elements and to all interactive elements inside forms (that is, all input, text area, and select elements).

window.datacoral('enableFormTracking');

This will only work for form elements which exist when it is called. If you are creating a form programmatically, call enableFormTracking again after adding it to the document to track it. (You can call enableFormTracking multiple times without risk of duplicated events.)

Note that events on password fields will not be tracked.

Augmenting events with additional data

Predefined contexts

We currently support the following pre-defined contexts, which you can automatically add to every event you send.To enable them, simply add them to the contexts field of the argmap while instantiating the tracker.

webPage
gaCookies
performanceTiming
geolocation

window.datacoral('newTracker', 'NAMESPACE', 'URL_ENDPOINT',
{
  appId: 'APP_ID',
  platform : 'desktop',
  apiKey : 'API_KEY',
  datacoralEnv: 'ENVIRONMENT',
  forceSecureTracker : true,
  post: true,
  contexts: {
    webPage: true,
    gaCookies: true,
    performanceTiming: true,
    geolocation:true
  }
});

Sending custom context information

Custom contexts can be used to augment any standard event type, including unstructured events, with additional data. Custom contexts can be added as an extra argument to any of Snowplow's track..() methods. Each custom context follows the same structure as unstructured event.

Example:

experiment_context = {
  name: "experiment",
  data: {
    key1: 'value1',
    key2: 'value2',
  }
};

custom_context = {
    name: "custom",
    data: {
        pageType: 'test',
        lastUpdated: new Date(2014,1,26)
    }
};

Even if only one custom context is being attached to an event, it still needs to be wrapped in an array.

All track... calls take a contexts argument which can have multiple contexts.

contexts = [experiment_context, custom_context];

// Track Page View
window.datacoral('trackPageView', null, contexts);

// Track Unstructured Event
window.datacoral('trackUnstructEvent', {
    name: 'viewed_product',
    data: {
        productId: 'ASO01043',
        category: 'Dresses',
        brand: 'ACME',
        returning: true,
        price: 49.95,
        sizes: ['xs', 's', 'l', 'xl', 'xxl'],
        availableSince: new Date(2013,3,7)
    }
}, contexts)

Contexts will be loaded to separate columns in Redshift table as JSON string. You should specify a name - experiment and custom in the above examples - and make sure columns with same names exist in Redshift table.

Testing

Step 1: serve the page through the provided origin (domain)
Step 2: Check the provided metabase dashboard for real-time events.

Troubleshooting

Browser console, in network trace, check response status. It should be 200
If not, under 'resources' tab, check local storage for any unsent events.

References

https://github.com/snowplow/snowplow/wiki/javascript-tracker

Data in Redshift

In the first example, the events data above will appear in raw form in the events_prod schema, the name_tracker column will be datacoral for the tracker above. Use this to identify events re

Important columns in the raw data are:

Redshift column name	Description
`app_id`	`appId`
`dvce_created_tstamp`	UNIX UTC epoch timestamp (milliseconds since Thursday, 1 January 1970). Use TIMESTAMP 'epoch'+ (dvce_created_tstamp/1000)*INTERVAL '1 second' to convert this to a human readable timestamp in Redshift.
`events`	`name` (event name)
`domain_userid`	First party cookie. This will be constant across sessions unless the person deletes their cookies.
`network_userid`	Third party cookie. If a person’s browser accepts them this will be constant across domains.
`domain_sessionid`	Session cookie.
`user_id`	This can be set by a variable when the event is fired using the setUserId method. This should be something that identifies an individual, like an email address or unique user id.
`page_url`	URL of the page on which the event occurred
`page_referrer`	URL of the referrer
`ue_data`	JSON string variable that contains the parameters defined in an unstructured event. Use `JSON_EXTRACT_PATH_TEXT(ue_data, ‘’)`` to extract a particular parameter value.
`se_category`	Category parameter from a structured event.
`se_action`	Action parameter from a structured event.
`se_label`	Label parameter from a structured event.
`se_property`	Property parameter from a structured event.
`se_value`	Value parameter from a structured event.

Datacoral Documentation

API Slices

Database Slices

Events Slices