Snowplow Tracker for Lua event analytics released

03 July 2013  •  Alex Dean

We are very pleased to announce the release of our SnowplowTracker for Lua event analytics. This is our fourth tracker to be released, following on from our JavaScript, Pixel and Arduino Trackers.

As a lightweight, easily-embeddable scripting language, Lua is available in a huge number of different computing environments and platforms, from World of Warcraft through OpenResty to Adobe Lightroom. And now, the Snowplow Lua Tracker lets you collect event data from these Lua-based applications, Lua web servers/frameworks, or from the Lua scripting layer within your games or apps - here’s a taster:

local t = snowplow.newTrackerForCf( "d3rkrsqld9gmqf" )
t:setAppId( "my-warcraft-addon" )
local s, msg = t:trackStructEvent( "shop", "add-to-basket", nil, "armour-vi", 2 )

We are hugely excited about our new event tracker for Lua. The first analytics tracker ever released for the Lua language, SnowplowTracker continues Snowplow’s push into the tracking and analysis of non-Web events. Moreover, as part of our commitment to High-Fidelity Analytics, this tracker:

  1. Is our first to include a full suite of unit and integration tests, built using the excellent Busted
  2. Uses contracts-style argument validation throughout, to prevent incorrectly-structured events from being sent to Snowplow

After the jump we will cover:

  1. Supported events
  2. Usage example
  3. Finding out more

1. Supported events

The Lua Tracker supports three types of event:

  1. trackStructEvent() - for tracking Google Analytics-style custom structured events with five fields (category, action, label, property, value)
  2. trackUnstructEvent() - for tracking Mixpanel-style custom unstructured events, consisting of an event name plus event properties in a Lua table
  3. trackScreenView() - for tracking views of individual screens within a game, app or similar

Please note that currently only trackStructEvent() is supported within the Snowplow ETL and Redshift table definition; adding support for unstructured events and screen views is on our roadmap.

2. Usage example

Using the SnowplowTracker from Lua is really simple.

First require the library and instantiate a new tracker:

local snowplow = require( "snowplow" )
local tracker = snowplow.newTrackerForUri( "snplow.mydomain.com" )

You can adjust the default configuration if you like:

tracker:encodeBase64( false ) -- Default is true

tracker:platform( "tv" ) -- Default is "pc"

Add any additional information about the app, user or device that you know:

tracker:setUserId( "bob@example.com" )
tracker:setAppId( "my-lightroom-plugin" )
tracker:setScreenResolution( 1068, 720 )

Now you are ready to track your events:

tracker:trackUnstructEvent( "save-file", { save_id = "4321",
                                           compression = 98,
                                           description = "Backup without layers",
                                           read_only = false
                                         }
                          )

And that’s it!

3. Finding out more

To read through the complete API for this Lua event tracker, please see the Lua Tracker page on the Snowplow wiki.

For setting up the tracker in various Lua environments (including LuaRocks), please see the Lua Tracker Setup page on the Snowplow wiki.

To check out the code itself, please see our snowplow-lua-tracker repository in GitHub.