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. Python Tracker
  6. Tracking specific events

Tracking specific events

As a Snowplow user, you have the ability to define your own event types, upload the associated schemas for those types to your own Iglu schema registry and then track those events in Snowplow using the track_self_describing_event() method.

In addition, Snowplow has a wide selection of pre-defined events and associated and associated methods for tracking:

FunctionDescription
track_page_view()Track views of web pages
track_page_ping()Track engagement on web pages over time
track_screen_view()Track screen views (non-web e.g. in-app)
track_ecommerce_transaction()Track ecommerce transaction
track_struct_event()Track a Snowplow custom structured 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

When you track an event, some of the data that you track will be specific to that event. A lot of the data you want to record, however, will describe entities that are tracked across multiple events. For example, a media company might want to track the following events:

  • User views video listing
  • User plays video
  • User pauses video
  • User shares video
  • User favorites video
  • User reviews video

Whilst each of those events is a different type, all of them involve capturing data about the user and the video. Both the ‘user’ and ‘video’ are entities that are tracked across multiple event types. Both are candidates to be “custom context”. You as a Snowplow user can define your own custom contexts (including associated schemas) and then send data for as many custom contexts as you wish with any Snowplow event. So if you want, you can define your own “user context”, and then send additional user data in that object with any event. Other examples of context include:

  • articles
  • videos
  • products
  • categories
  • pages / page_types
  • environments

Each tracking method accepts an additional optional contexts parameter after all the parameters specific to that method:

def track_page_view(self, page_url, page_title=None, referrer=None, context=None, tstamp=None):

The context argument should consist of an array of one or more instances of SelfDescribingJson class. This class isomorphic to self-describing JSON, to be more precisely – it has Iglu URI attribute and data itself.

If server-side Python application can determine visitor’s geoposition – it can be attached to the event, using following context (geolocation_context 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 } )

If a visitor arrives on a page advertising a movie, the context object might look like this (movie_poster is custom context):

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:

t.track_page_view("http://www.films.com", "Homepage", context=[poster_context, geo_context])

Important: Even if only one custom context is being attached to an event, it still needs to be wrapped in an array.

Note also that you should not pass in an empty array of contexts as this will fail validation. Instead of an empty array, you can pass in None.

Optional timestamp argument

Each track...() method supports an optional timestamp as its final 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 Python 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. We can explicitly supply Nones for the intervening arguments which are empty:

t.track_struct_event("some cat", "save action", None, None, None, 1368725287000)

Alternatively, we can use the argument name:

t.track_struct_event("some cat", "save action", tstamp=1368725287000)

Timestamp is counted in milliseconds since the Unix epoch – the same format as generated by time.time() * 1000.

As of version 0.8.0, providing a snowplow_tracker.timestamp.TrueTimestamp object as the timestamp argument will attach a true timestamp to the event, replacing the device timestamp. For example:

from snowplow_tracker.tracker import TrueTimestamp t.track_struct_event("some cat", "save action", tstamp=TrueTimestamp(1368725287000))

Above will attach ttm(true_tstamp) parameter instead of default dtm. You can also use, plain integer, DeviceTimestamp or None to send device_sent_timestamp.

Tracker method return values

All tracker methods will return the tracker instance, allowing tracker methods to be chained:

e = AsyncEmitter("d3rkrsqld9gmqf.cloudfront.net") t = Tracker(e) t.track_page_view("http://www.example.com").track_screen_view("title screen")x

Track self-describing events with track_self_describing_event()

Use track_self_describing_event() to track an event types that you have defined yourself. The arguments are as follows:

ArgumentDescriptionRequired?Validation
event_jsonThe properties of the eventYesSelfDescribingJson
contextCustom context for the eventNoList(SelfDescribingJson)
tstampWhen the unstructured event occurredNoPositive integer

Example:

from snowplow_tracker import SelfDescribingJson t.track_self_describing_event(SelfDescribingJson( "iglu:com.example_company/save-game/jsonschema/1-0-2", { "save_id": "4321", "level": 23, "difficultyLevel": "HARD", "dl_content": True } ))

The event_json is represented using the SelfDescribingJson class. It has two fields: schema and datadata is a dictionary containing the properties of the unstructured event. schema identifies the JSON schema against which data should be validated. This schema should be available in your Iglu schema registry and your Snowplow pipeline configured so that that that registry is included in your Iglu resolver.

For more on JSON schema, see the blog post.

Many Snowplow users use the above method to track all their events i.e. only record event types that they have defined. However, there are a number of “out of the box” events that have dedicated tracking methods. These are detailed below:

Track pageviews with track_page_view()

Use track_page_view() to track a user viewing a page within your app or website. The arguments are:

ArgumentDescriptionRequired?Validation
page_urlThe URL of the pageYesNon-empty string
page_titleThe title of the pageNoString
referrerThe address which linked to the pageNoString
contextCustom context for the eventNoList(SelfDescribingJson)
tstampWhen the pageview occurredNoPositive integer

Example:

t.track_page_view("www.example.com", "example", "www.referrer.com")

Track page pings with track_page_ping()

Use track_page_ping() to track engagement with a web page over time, via a heartbeat event. (Each ping represents a single heartbeat.)

Arguments are:

ArgumentDescriptionRequired?Validation
page_urlThe URL of the pageYesNon-empty string
page_titleThe title of the pageNoString
referrerThe address which linked to the pageNoString
min_xMinimum page X offset seen in the last ping periodNoPositive integer
max_xMaximum page X offset seen in the last ping periodNoPositive integer
min_yMinimum page Y offset seen in the last ping periodNoPositive integer
max_yMaximum page Y offset seen in the last ping periodNoPositive integer
contextCustom context for the eventNoList(SelfDescribingJson)
tstampWhen the pageview occurredNoPositive integer

Example:

t.track_page_ping("http://mytesturl/test2", "Page title 2", "http://myreferrer.com", 0, 100, 0, 500, None)

Track screen views with track_screen_view()

Use track_screen_view() to track a user viewing a screen (or equivalent) within your app. This is an alternative to the track_page_view method which is less web-centric. The arguments are:

ArgumentDescriptionRequired?Validation
nameHuman-readable name for this screenNoNon-empty string
id_Unique identifier for this screenNoString
contextCustom context for the eventNoList(SelfDescribingJson)
tstampWhen the screen was viewedNoPositive integer

Although name and id_ are not individually required, at least one must be provided or the event will fail validation.

Example:

t.track_screen_view("HUD > Save Game", "screen23", null, 1368725287000)

Track ecommerce transactions with track_ecommerce_transaction()

Use track_ecommerce_transaction() to track an ecommerce transaction. Arguments:

ArgumentDescriptionRequired?Validation
order_idID of the eCommerce transactionYesNon-empty string
total_valueTotal transaction valueYesInt or Float
affiliationTransaction affiliationNoString
tax_valueTransaction tax valueNoInt or Float
shippingDelivery cost chargedNoInt or Float
cityDelivery address cityNoString
stateDelivery address stateNoString
countryDelivery address countryNoString
currencyTransaction currencyNoString
itemsItems in the transactionYesList
contextCustom context for the eventNoList(SelfDescribingJson)
tstampWhen the transaction event occurredNoPositive integer

The items argument is an array of Python dictionaries representing the items in the transaction. track_ecommerce_transaction fires multiple events: one “transaction” event for the transaction as a whole, and one “transaction item” event for each element of the items array. Each transaction item event will have the same timestamp, order_id, and currency as the main transaction event.

These are the fields that can appear in a transaction item dictionary:

FieldDescriptionRequired?Validation
"sku"Item SKUYesNon-empty string
"price"Item priceYesInt or Float
"quantity"Item quantityYesInt
"name"Item nameNoString
"category"Item categoryNoString
"context"Custom context for the eventNoList

Example of tracking a transaction containing two items:

t.track_ecommerce_transaction("6a8078be", 35, city="London", currency="GBP", items= [{ "sku": "pbz0026", "price": 20, "quantity": 1 }, { "sku": "pbz0038", "price": 15, "quantity": 1 }])

Track ecommerce transactions with track_ecommerce_transaction_item()

Use track_ecommerce_transaction_item() to track an individual line item within an ecommerce transaction.

Arguments:

ArgumentDescriptionRequired?Validation
idOrder IDYesNon-empty string
skuItem SKUYesNon-empty string
priceItem priceYesInt or Float
quantityItem quantityYesInt
nameItem nameNoString
categoryItem categoryNoString
contextCustom context for the eventNoList(SelfDescribingJson)
tstampWhen the transaction event occurredNoPositive integer

Example:

t.track_ecommerce_transaction_item("order-789", "2001", 49.99, 1, "Green shoes", "clothing")

Track structured events with track_struct_event()

Use track_struct_event() 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 toYesNon-empty string
actionDefines the type of user interaction which this event involvesYesNon-empty string
labelA string to provide additional dimensions to the event dataNoString
propertyA string describing the object or the action performed on itNoString
valueA value to provide numerical data about the eventNoInt or Float
contextCustom context for the eventNoList(SelfDescribingJson)
tstampWhen the structured event occurredNoPositive integer

Example:

t.track_struct_event("shop", "add-to-basket", None, "pcs", 2)

track_link_click

Use track_link_click() to track individual link click events. Arguments are:

ArgumentDescriptionRequired?Validation
target_urlThe URL of the pageYesNon-empty string
element_idID attribute of the HTML elementNoString
element_classesClasses of the HTML elementNoList(string)
element_targetTarget elementNoString
element_contentThe content of the HTML elementNoString
contextCustom context for the eventNoList(SelfDescribingJson)
tstampWhen the pageview occurredNoPositive integer

Basic example:

t.track_link_click("http://my-target-url2/path")

Advanced example:

t.track_link_click("http://my-target-url2/path", "element id 2", None, "element target", "element content")

track_add_to_cart

Use track_add_to_cart() to track adding items to a cart on an ecommerce site. Arguments are:

ArgumentDescriptionRequired?Validation
skuItem SKU or IDYesNon-empty string
quantityNumber of items added to cartYesInteger
nameItem’s nameNoString
categoryItem’s categoryNoString
unit_priceItem’s priceNoInt or Float
currencyCurrencyNoString
contextCustom context for the eventNoList(SelfDescribingJson)
tstampWhen the pageview occurredNoPositive integer

Example:

t.track_add_to_cart("123", 2, "The Devil's Dance", "Books", 23.99, "USD", None )

track_remove_from_cart

Use track_remove_from_cart() to track removing items from a cart on an ecommerce site. Arguments are:

ArgumentDescriptionRequired?Validation
skuItem SKU or IDYesNon-empty string
quantityNumber of items added to cartYesInteger
nameItem’s nameNoString
categoryItem’s categoryNoString
unit_priceItem’s priceNoInt or Float
currencyCurrencyNoString
contextCustom context for the eventNoList(SelfDescribingJson)
tstampWhen the pageview occurredNoPositive integer

Basic example:

t.track_remove_from_cart("123", 1)

Advanced example:

t.track_remove_from_cart("123", 2, "The Devil's Dance", "Books", 23.99, "USD")

track_form_change

Use track_from_change() to track changes in website form inputs over session. Arguments are:

ArgumentDescriptionRequired?Validation
form_idID attribute of the HTML formYesNon-empty string
element_idID attribute of the HTML elementYesString
node_nameType of input elementYesValid node_name
valueValue of input elementYesString
type_Type of data the element representsNoNon-empty string
element_classesClasses of the HTML elementNoList(string)
contextCustom context for the eventNoList(SelfDescribingJson)
tstampWhen the pageview occurredNoPositive integer

Basic example:

t.track_form_change("signupForm", "ageInput", "age", "24")

Advanced example:

t.track_form_change("signupForm", "ageInput", "age", "24", "number", ["signup__number", "form__red"])

track_form_submit

Use track_form_submit() to track sumbitted forms. Arguments are:

ArgumentDescriptionRequired?Validation
form_idID attribute of the HTML formYesNon-empty string
form_classesClasses of the HTML formNoList(str)
elementsValue of input elementNoList(dict)
contextCustom context for the eventNoList(SelfDescribingJson)
tstampWhen the pageview occurredNoPositive integer

Basic example:

t.track_form_submit("registrationForm")

Advanced example:

t.track_form_submit("signupForm", ["signup__warning"], {"name": "email", "value": "tracker@example.com", "nodeName": "INPUT", "type": "email"})

track_site_search

Use track_site_search() to track a what user searches on your website. Arguments are:

ArgumentDescriptionRequired?Validation
termsSearch termsYesList(str)
filtersFilters applied to searchNoList(dict{str:str
total_resultsTotal number of resultsNoInteger
page_resultsNumber of pages of resultsNoInteger
contextCustom context for the eventNoList(SelfDescribingJson)
tstampWhen the pageview occurredNoPositive integer

Basic example:

t.track_site_search(["analytics", "snowplow", "tracker"])

Advanced example:

t.track_site_search(["pulp fiction", "reviews"], {"nswf": true}, 215, 22)

Track unstructured events with track_unstruct_event()

This functionally is equivalent to track_self_describing_event. We believe that the method name is misleading: this method is used to track events that are structured in nature (they have an associated schema), which is why we believe referring to them as self-describing events makes more sense than referring to them as unstructured events.

The method is provided for reasons of backwards compatibility.