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 methods for tracking:

FunctionDescription
track_page_view()Track views of web pages
track_page_ping()Track engagement on web pages over time
track_link_click()Track link clicks
track_form_change()Track form changes
track_form_submit()Track that a form was submitted
track_site_search()Track when a user searches your site
track_screen_view()Track screen views (non-web e.g. in-app)
track_ecommerce_transaction()Track ecommerce transaction
track_ecommerce_transaction_item()Track an item of an ecommerce transaction
track_add_to_cart()Track an add to cart event
track_remove_from_cart()Track a remove from cart event
track_struct_event()Track a Snowplow custom structured event

Common tracking parameters

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. The parameters that are common for all track methods are:

  • context
  • tstamp
  • event_subject (**New to v0.9.0)

1. Custom context

Custom context can be used to augment any standard Snowplow event type, including self describing events, with additional data.

Custom context can be added as an extra argument to any of Snowplow’s track..() methods.

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 context parameter after all the parameters specific to that method:

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.

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 } )
Code language: JavaScript (javascript)

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" } )
Code language: JavaScript (javascript)

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])
Code language: JavaScript (javascript)

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.

2. Timestamp argument

Each track...() method 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 occured.

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:

t.track_struct_event("some cat", "save action", None, None, None, 1368725287000)
Code language: JavaScript (javascript)

Alternatively, we can use the argument name:

t.track_struct_event("some cat", "save action", tstamp=1368725287000)
Code language: JavaScript (javascript)

**Prior to v0.9.0

Before version 0.9.0 of the Python Tracker, 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))
Code language: JavaScript (javascript)

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.

**New to v0.9.0

Since version 0.9.0, providing the optional timestamp argument will only set the true timestamp (true_tstamp) of the event. The type of this argument can only be the unix time in milliseconds. If you migrate from previous version, make sure to replace any references to Timestamp objects, since the Timestamp class (along with the TrueTimestamp and DeviceTimestamp subclasses) do not exist.

t.track_struct_event("some cat", "save action", tstamp=1368725287000)
Code language: JavaScript (javascript)

3. Event subject (since v0.9.0)

Since version 0.9.0, 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.

This is supported as an optional keyword argument by all track methods. For example:

evSubject = Subject().set_user_id("1234") t.track_page_view("www.example.com", event_subject=evSubject)
Code language: JavaScript (javascript)

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
Code language: JavaScript (javascript)

Track self-describing event

Use track_self_describing_event() to track an event types that you have defined yourself.

This method’s arguments are:

ArgumentDescriptionRequired?Validation
event_jsonThe properties of the eventYesSelfDescribingJson
contextCustom context for the eventNoList(SelfDescribingJson)
tstampWhen the unstructured event occurredNoPositive integer
event_subject (since v0.9.0)The subject for the eventNoSubject

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 } ))
Code language: JavaScript (javascript)

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 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
event_subject (since v0.9.0)The subject for the eventNoSubject

Example:

t.track_page_view("www.example.com", "example", "www.referrer.com")
Code language: CSS (css)

Track page pings

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
event_subject (since v0.9.0)The subject for the eventNoSubject

Example:

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

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
event_subject (since v0.9.0)The subject for the eventNoSubject

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", None, 1368725287000)
Code language: JavaScript (javascript)

Track ecommerce transactions

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
event_subject (since v0.9.0)The subject for the eventNoSubject

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, currency (and event_subject, since v0.9.0) 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 }])
Code language: JavaScript (javascript)

Track ecommerce transaction items

Use track_ecommerce_transaction_item() to track an individual line item.

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
event_subject (since v0.9.0)The subject for the eventNoSubject

Example:

t.track_ecommerce_transaction_item("order-789", "2001", 49.99, 1, "Green shoes", "clothing")
Code language: JavaScript (javascript)

Track structured events

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
event_subject (since v0.9.0)The subject for the eventNoSubject

Example:

t.track_struct_event("shop", "add-to-basket", None, "pcs", 2)
Code language: JavaScript (javascript)

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
event_subject (since v0.9.0)The subject for the eventNoSubject

Basic example:

t.track_link_click("http://my-target-url2/path")
Code language: JavaScript (javascript)

Advanced example:

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

Track add-to-cart events

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
event_subject (since v0.9.0)The subject for the eventNoSubject

Example:

t.track_add_to_cart("123", 2, "The Devil's Dance", "Books", 23.99, "USD", None )
Code language: JavaScript (javascript)

Track remove-from-cart events

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
event_subject (since v0.9.0)The subject for the eventNoSubject

Basic example:

t.track_remove_from_cart("123", 1)
Code language: JavaScript (javascript)

Advanced example:

t.track_remove_from_cart("123", 2, "The Devil's Dance", "Books", 23.99, "USD")
Code language: JavaScript (javascript)

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
event_subject (since v0.9.0)The subject for the eventNoSubject

Basic example:

t.track_form_change("signupForm", "ageInput", "age", "24")
Code language: JavaScript (javascript)

Advanced example:

t.track_form_change("signupForm", "ageInput", "age", "24", "number", ["signup__number", "form__red"])
Code language: JavaScript (javascript)

Track submitted forms

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
event_subject (since v0.9.0)The subject for the eventNoSubject

Basic example:

t.track_form_submit("registrationForm")
Code language: JavaScript (javascript)

Advanced example:

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

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
event_subject (since v0.9.0)The subject for the eventNoSubject

Basic example:

t.track_site_search(["analytics", "snowplow", "tracker"])
Code language: CSS (css)

Advanced example:

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

truck_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.

If you’d like to learn more about Snowplow Insights you can book a demo with our team, or if you’d prefer, you can try Snowplow technology for yourself quickly and easily.