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'strack..()
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
Data in Redshift
In the first example, the events data above will appear in raw form in theevents_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, ‘ |
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. |