Tracking specific events

Function	Description
track_struct_event()	Track a Snowplow custom structured event
track_self_describing_event()	Track a Snowplow custom unstructured event
track_screen_view()	Track the user viewing a screen within the application
track_timing()	Track a timing event

Common

All events are tracked with specific methods on the tracker instance, of the form track_xxx(), where xxx is the name of the event to track.

Custom contexts

In short, custom contexts let you add additional information about the circumstances surrounding an event in the form of a vector of SelfDescribingJson objects. Each tracking method accepts an additional optional contexts parameter, which should be a vector of contexts:

vector<SelfDescribingJson> contexts;
Code language: HTML, XML (xml)

If a visitor arrives on a page advertising a movie, the dictionary for a single custom context in the list might look like this:

vector<SelfDescribingJson> contexts;
SelfDescribingJson sdj(
  "iglu:com.acme_company/movie_poster/jsonschema/2-1-1",
  "{\"movie_name\":\"Solaris\",\"poster_country\":\"JP\"}"_json
);
contexts.push_back(sdj);
Code language: JavaScript (javascript)

This is how to fire a structured event with the above custom context:

Tracker::StructuredEvent se("category", "action");
se.contexts = contexts;

Tracker::instance()->track_struct_event(se);
Code language: PHP (php)

Note that even though there is only one custom context attached to the event, it still needs to be placed in a list.

INFO: We use the excellent json library from Github community member Niels (nlohmann) for all JSON parsing. For more information on using this library please visit the Technical information on Github.

Optional timestamp argument

Each track...() method supports an optional timestamp argument; this allows you to manually override the timestamp attached to this event. The timestamp should be in milliseconds since the Unix epoch.

If you do not pass this timestamp in as an argument, then the C++ Tracker will use the current time to be the timestamp for the event.

Here is an example tracking a structured event and supplying the optional timestamp argument:

Tracker::StructuredEvent se("category", "action");
se.timestamp(1368725287000);

Tracker::instance()->track_struct_event(se);
Code language: PHP (php)

Optional true-timestamp argument

Each track...() method supports an optional true-timestamp argument; this allows you to provide the true-timestamp attached to this event to help with the timing of events in multiple timezones. The timestamp should be in milliseconds since the Unix epoch.

Here is an example tracking a structured event and supplying the optional true-timestamp argument:

Tracker::StructuredEvent se("category", "action");

// As it is optional you will need to pass the address for this value
unsigned long long true_tstamp = "1368725287000";
se.true_timestamp = &true_tstamp;

Tracker::instance()->track_struct_event(se);
Code language: PHP (php)

Optional event ID argument

Each track...() method supports an optional event id argument; this allows you to manually override the event ID attached to this event. The event ID should be a valid version 4 UUID string.

Here is an example tracking a structured event and supplying the optional event ID argument:

StructuredEvent se("category", "action");
se.event_id = "ba55081a-a58c-40b4-afb2-4915dd149200";

Tracker::instance()->track_struct_event(se);
Code language: PHP (php)

Track SelfDescribing/Unstructured events with track_self_describing_event()

Use track_self_describing_event() to track a custom event which consists of a name and an unstructured set of properties. This is useful when:

• You want to track event types which are proprietary/specific to your business (i.e. not already part of Snowplow), or
• You want to track events which have unpredictable or frequently changing properties

The arguments are as follows:

Argument	Description	Required?	Validation
event	The properties of the event	Yes	SelfDescribingJson
timestamp	When the event occurred	No	unsigned long long
event_id	The event ID	No	string
true_timestamp	The true time of event	No	*unsigned long long
contexts	Custom contexts for the event	No	vector

Example:

// Create a JSON containing your data
json data = "{\"level\":5,\"saveId\":\"ju302\",\"hardMode\":true}"_json;

// Create a new SelfDescribingJson
SelfDescribingJson sdj("iglu:com.example_company/save-game/jsonschema/1-0-2", data);

Tracker::SelfDescribingEvent sde(sdj);
Tracker::instance()->track_self_describing_event(sde);
Code language: PHP (php)

For more on JSON schema, see the blog post.

Track screen views with track_screen_view()

Use track_screen_view() to track a user viewing a screen (or equivalent) within your app:

Argument	Description	Required?	Type
name	Human-readable name for this screen	No	*string
id	Unique identifier for this screen	No	*string
timestamp	When the event occurred	No	unsigned long long
event_id	The event ID	No	string
true_timestamp	The true time of event	No	*unsigned long long
contexts	Custom contexts for the event	No	vector

Although name and id are not individually required, at least one must be provided or the event will fail validation and subsequently throw an exception.

Example:

string name = "Screen ID - 5asd56";

Tracker::ScreenViewEvent sve;
sve.name = &name;

Tracker::instance()->track_screen_view(sve);
Code language: PHP (php)

Track structured events with TrackStructEvent()

Use TrackStructEvent() to track a custom event happening in your app which fits the Google Analytics-style structure of having up to five fields (with only the first two required):

Argument	Description	Required?	Validation
category	The grouping of structured events which this action belongs to	Yes	string
action	Defines the type of user interaction which this event involves	Yes	string
label	A string to provide additional dimensions to the event data	No	*string
property	A string describing the object or the action performed on it	No	*string
value	A value to provide numerical data about the event	No	*double
timestamp	When the event occurred	No	unsigned long long
event_id	The event ID	No	string
true_timestamp	The true time of event	No	*unsigned long long
contexts	Custom contexts for the event	No	vector

Example:

Tracker::StructuredEvent se("shop", "add-to-basket");
se.property = "pcs";
se.value = 25.6;

Tracker::instance()->track_struct_event(se);
Code language: PHP (php)

4.5 Track timing events with TrackTiming()

Use TrackTiming() to track a timing event.

The arguments are as follows:

Argument	Description	Required?	Validation
category	The category of the event	Yes	*string
variable	The variable of the event	Yes	*string
timing	The timing of the event	Yes	*int64
label	The label of the event	No	*string
timestamp	When the event occurred	No	unsigned long long
event_id	The event ID	No	string
true_timestamp	The true time of event	No	*unsigned long long
contexts	Custom contexts for the event	No	vector

Example:

Tracker::TimingEvent te("category", "variable", 123);
Tracker::instance()->track_timing(te);
Code language: PHP (php)