Skip to main content

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 }}")

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)

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

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

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)

An example of the values returned from a successful request:

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

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.

Was this page helpful?