Skip to main content

Event Tracking

The Python tracker makes it simple to track a selection of out-of-the-box events as well as the ability to define your own custom events.

To track an event, simply pass the Event object to the tracker.track() method. For example, tracking a page view:

page_view = PageView(
page_url="https://www.snowplow.io",
page_title="Homepage",
)
tracker.track(page_view)

Every tracked event payload has a unique event_id UUID string (eid). Other properties include the name_tracker (namespace) and app_id set when the Tracker was initialized. From version 1 onwards, tracker.track() returns the payload's eid.

Snowplow events have a defined structure and protocol that is identical regardless of the tracker used. Further information on this structure can be found here.

The Python tracker Github repository includes 3 example apps demonstrating different ways to send events to your collector.

Event Tracking

The Python tracker provides classes for tracking different types of events. They are listed below:

EventDescription
SelfDescribingTrack custom events with custom schemas
PageViewTrack views of web pages
PagePingTrack engagement on web pages over time
ScreenViewTrack views of a screen (non-web e.g. in-app)
StructuredEventTrack custom events without schemas

Creating a custom event (SelfDescribing)

To track data using a SelfDescribing event, the data must be structured as a SelfDescribingJson object. These require two fields, a URI for a self-describing JSON schema and the data in the form of a PayloadDict. The data must be valid against the schema.

A simple initialization for a link click event looks like this:

link_click = SelfDescribing(
SelfDescribingJson(
"iglu:com.snowplowanalytics.snowplow/link_click/jsonschema/1-0-1",
{"targetUrl": "https://www.snowplow.io"},
),
)
tracker.track(link_click)

Creating a PageView Event

Track views of a web page with the PageView event.

PropertyDescriptionTypeRequired?
page_urlURL of the viewed pagestringYes
page_titleTitle of the viewed pagestringNo
referrerThe address which linked to the pagestringNo
event_subjectThe subject for the eventSubjectNo
contextCustom context for the eventList(SelfDescribingJson)No
true_timestampWhen the page view occurredint or floatNo

Example:

page_view = PageView(
page_url="https://www.snowplow.io",
page_title="Homepage",
referrer="https://docs.snowplow.io/docs",
)
tracker.track(page_view)

Creating a PagePing Event

Track engagement with a web page over time, via a PagePing event. Each ping represents a single heartbeat.

PropertyDescriptionTypeRequired?
page_urlURL of the viewed pagestringYes
page_titleTitle of the viewed pagestringNo
referrerThe address which linked to the pagestringNo
min_xMinimum page x offset seen in the last ping periodintNo
max_xMaximum page x offset seen in the last ping periodintNo
min_yMinimum page y offset seen in the last ping periodintNo
max_yMaximum page y offset seen in the last ping periodintNo
event_subjectThe subject for the eventSubjectNo
contextCustom context for the eventList(SelfDescribingJson)No
true_timestampWhen the page ping occurredint or floatNo

Example:

page_ping = PagePing(
page_url="https://www.snowplow.io",
page_title="Homepage",
referrer="https://docs.snowplow.io/docs",
)
tracker.track(page_ping)

Creating a ScreenView Event

Use the ScreenView to track a user viewing a screen (or equivalent) within your app.

PropertyDescriptionTypeRequired?
id_Unique identifier for this screen (UUID)stringNo
nameHuman-readable name for this screenNon-empty stringNo
typeThe type of screen that was viewed e.g feed / carousel.stringNo
previous_nameThe name of the previous screenview.stringNo
previous_idThe id of the previous screenview.stringNo
previous_typeThe type of the previous screenview.stringNo
transition_typeThe type of transition that led to the screen being viewed.stringNo
event_subjectThe subject for the eventSubjectNo
contextCustom context for the eventList(SelfDescribingJson)No
true_timestampWhen the screen was viewedint or floatNo

Example:

id = tracker.get_uuid()
screen_view = ScreenView(
id_=id,
name="name",
type="feed"
previous_name="Home Page",
previous_id="1368725287000",
previous_type="feed"
)
tracker.track(screen_view)

Creating a StructuredEvent

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

PropertyDescriptionTypeRequired?
categoryThe grouping of structured events which this action belongs toNon-empty stringYes
actionDefines the type of user interaction which this event involvesNon-empty stringYes
labelA string to provide additional dimensions to the event datastringNo
propertyA string describing the object or the action performed on itstringNo
valueA value to provide numerical data about the eventint or floatNo
event_subjectThe subject for the eventSubjectNo
contextCustom context for the eventList(SelfDescribingJson)No
true_timestampWhen the structured event occurredint or floatNo

Example:

struct_event = StructuredEvent(
category="shop",
action="add-to-basket",
label="web-shop",
property_="pcs",
value=2,
)
tracker.track(struct_event)

Common tracking parameters

All events are tracked with specific event classes on the tracker instance, of the form track(Event). The parameters that are common for all track methods are:

  • event_subject
  • context
  • true_timestamp

Event subject

It is possible to set the Subject per-event, in order to augment the event with extra information without having to change the Subject at the Tracker level. This provides a thread safe way to track multiple subjects.

Event level subjects are combined with any tracker subjects that have been initialized, with the event subject taking priority over tracker subject parameters.

This is supported as an optional keyword argument by all event classes. For example:


event_subject = Subject().set_user_id("1234")
page_view = PageView(
page_url="https://www.snowplow.io",
page_title="Homepage",
event_subject=event_subject
)

tracker.track(page_view)

More detail on the Subject class can be found here.

Custom context

Custom context can be used to augment any standard Snowplow event type, including self describing events, with additional data. You can read more about custom contexts and the possible use cases here.

Custom context can be added as an extra argument to any of Snowplow’s Event classes. The context argument should consist of a list of one or more instances of the SelfDescribingJson class.

For example, if a server-side Python application can determine visitor's geoposition, this can be attached to the event using the geolocation_context that is predefined on Iglu Central:

from snowplow_tracker import SelfDescribingJson

geo_context = SelfDescribingJson(
"iglu:com.snowplowanalytics.snowplow/geolocation_context/jsonschema/1-0-0",
{
"latitude": -23.2,
"longitude": 43.0
}
)

As another example, if a visitor arrives on a page advertising a movie, the context object might look like this (movie_poster is custom context, not predefined):

poster_context = SelfDescribingJson(
"iglu:com.acme_company/movie_poster/jsonschema/2-1-1",
{
"movie_name": "Solaris",
"poster_country": "JP",
"poster_year": "1978-01-01"
}
)

This is how to fire a page view event with both above contexts:

page_view = PageView(
page_url="https://www.snowplow.io",
page_title="Homepage",
context=[poster_context, geo_context]
)

tracker.track(page_view)

Important: Even if only one custom context is being attached to an event, it still needs to be parsed as a list.

Timestamp argument

Each event class supports an optional timestamp as an argument. The timestamp should be in milliseconds since the Unix epoch, the same format as generated by time.time() * 1000.

Generally, according to the Snowplow Tracker Protocol, every event tracked will be recorded with two timestamps:

  • the dvce_created_tstamp, which is the timestamp when the event was created

  • the dvce_sent_tstamp, which is the timestamp when the event was sent

These are going to be used downstream, to calculate the derived_tstamp for the event, which takes also into account the collector timestamp, in order to best approximate the exact time the event occurred.

The optional timestamp argument is for the cases where you might want to set the event timestamp yourself. If this argument is not provided or set to None, then the Python Tracker will use the current time to be the dvce_created_tstamp for the event.

Here is an example tracking a structured event and supplying the optional timestamp argument. We can explicitly supply None for the intervening arguments which are empty:

struct_event = StructuredEvent(
category="shop",
action="add-to-basket",
label="web-shop",
property_="pcs",
value=2,
true_timestamp=1368725287000
)
tracker.track(struct_event)
Was this page helpful?