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

Tracking events

Creating a Tracker

Creating a tracking instance is as simple as calling snowplow.new_tracker and providing a URL for your collector:

local snowplow = require("snowplow") local tracker = snowplow.new_tracker("{{ collector_url }}")
Code language: Lua (lua)

Tracking methods supported by the Lua Tracker:

MethodEvent type tracked
track_screen_viewView of screen
track_struct_eventSemi-custom structured event
track_self_describing_eventCustom event based on “self-describing” JSON schema

Track structured events with track_struct_event

This method provides a halfway-house between tracking fully user-defined self-describing events and out-of-the box predefined events. This event type can be used to track many types of user activity, as it is somewhat customizable. “Struct” events closely mirror the structure of Google Analytics events, with “category”, “action”, “label”, and “value” properties.

ParameterDescriptionRequired in event?
categoryThe grouping of structured events which this action belongs toYes
actionDefines the type of user interaction which this event involvesYes
labelOften used to refer to the ‘object’ the action is performed onNo
propertyDescribing the ‘object’, or the action performed on itNo
valueProvides numerical data about the eventNo
tracker:track_struct_event("shop", "add-to-basket", "book", "pcs", 2)
Code language: Lua (lua)

Track self-describing events with track_self_describing_event

Use track_self_describing_event to track a custom event. This is the most advanced and powerful tracking method, which requires a certain amount of planning and infrastructure. A guide to understanding Self-Describing events is available here.

ParameterDescriptionRequired in event?
schemaThe schema to useYes
actionThe data to send along with the schemaYes
tracker:track_self_describing_event( "iglu:com.snowplowanalytics.snowplow/add_to_cart/jsonschema/1-0-0", { sku = "ASO01043", unitPrice = 49.95, quantity = 1000 } )
Code language: Lua (lua)

Track screen views with track_screen_view

Use track_screen_view to track a user viewing a screen (or similar) within your app. This is the page view equivalent for apps that are not webpages.

This method uses a self-describing event with the com.snowplowanalytics.snowplow/screen_view schema.

tracker:track_screen_view("Character Creation - Step 1", "c1")
Code language: Lua (lua)

Configuring the Tracker

The new_tracker method has a couple of other parameters that can be used to configure your tracker instance, along with the collector url.

ParameterDescriptionRequiredDefault
urlThe Snowplow Collector URLYes
request_typeThe request type to use (“GET” or “POST”)No“POST”
encode_base64If self-describing event payloads are base64 encodedNotrue

Note: It’s generally recommended to use the default values as encode_base64 = true can reduce the size of payloads and POST will receive more future support (such as batched requests), but you can change these if your use case calls for it.

Tracker Method Return Values

A call to a track_* method will return two values, a boolean if the request was successful, and an optional error message if the request was not successful.

An example of the values returned from a failed request:

local ok, err = tracker:track_screen_view("Character Configuration - Part 1", "c1") -- false, Host [https://test.invalid/com.snowplowanalytics.snowplow/tp2] not found (possible connectivity error)
Code language: Lua (lua)

An example of the values returned from a successful request:

local ok, err = tracker:track_screen_view("Character Configuration - Part 1", "c1") -- true, nil
Code language: Lua (lua)

Adding user and platform data

The tracker can store information about the user associated with the event, such as their user_id, what type of device they used, or what size screen that device had. It also stores which platform the event occurred on – e.g. server-side app, mobile, games console, etc. This is done through the provided set_* methods available on a tracker instance. The stored information is attached to the tracked events using fields described in the Tracker Protocol.

For a full list of setters, check out the Tracker API Documentation.

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