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)