Collecting data with Trackers and Webhooks

  1. Home
  2. Docs
  3. Collecting data with Trackers and Webhooks
  4. Trackers – collecting data from your own applications
  5. C++ Tracker
  6. Tracking specific events

Tracking specific events

FunctionDescription
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;

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);

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);

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);

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);

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);

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:

ArgumentDescriptionRequired?Validation
eventThe properties of the eventYesSelfDescribingJson
timestampWhen the event occurredNounsigned long long
event_idThe event IDNostring
true_timestampThe true time of eventNo*unsigned long long
contextsCustom contexts for the eventNovector

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);

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:

ArgumentDescriptionRequired?Type
nameHuman-readable name for this screenNo*string
idUnique identifier for this screenNo*string
timestampWhen the event occurredNounsigned long long
event_idThe event IDNostring
true_timestampThe true time of eventNo*unsigned long long
contextsCustom contexts for the eventNovector

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);

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):

ArgumentDescriptionRequired?Validation
categoryThe grouping of structured events which this action belongs toYesstring
actionDefines the type of user interaction which this event involvesYesstring
labelA string to provide additional dimensions to the event dataNo*string
propertyA string describing the object or the action performed on itNo*string
valueA value to provide numerical data about the eventNo*double
timestampWhen the event occurredNounsigned long long
event_idThe event IDNostring
true_timestampThe true time of eventNo*unsigned long long
contextsCustom contexts for the eventNovector

Example:

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

4.5 Track timing events with TrackTiming()

Use TrackTiming() to track a timing event.

The arguments are as follows:

ArgumentDescriptionRequired?Validation
categoryThe category of the eventYes*string
variableThe variable of the eventYes*string
timingThe timing of the eventYes*int64
labelThe label of the eventNo*string
timestampWhen the event occurredNounsigned long long
event_idThe event IDNostring
true_timestampThe true time of eventNo*unsigned long long
contextsCustom contexts for the eventNovector

Example:

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