Scala Tracker - OXYGEN-MARKET/oxygen-market.github.io GitHub Wiki

HOME > SNOWPLOW TECHNICAL DOCUMENTATION > Trackers > Scala Tracker

This page refers to version 0.3.0 of the Snowplow Scala Tracker. Documentation for other versions is available:

Version 0.1 Version 0.2

• 1 Overview
• 2 Initialization
  • 2.1 Tracker
  • 2.2 Subject
  • 2.3 EC2 Context
• 3 Sending events
  • 3.1 trackSelfDescribingEvent
  • 3.2 trackStructEvent
  • 3.3 trackPageView
  • 3.4 Setting timestamp
• 4 Subject methods

The Snowplow Scala Tracker allows you to track Snowplow events in your Scala apps and servers.

The tracker should be straightforward to use if you are comfortable with Scala development; any prior experience with Snowplow's Python Tracker, JavaScript Tracker, Android and Java Tracker, Google Analytics or Mixpanel (which have similar APIs to Snowplow) is helpful but not necessary.

There are three main classes which the Scala Tracker uses: subjects, emitters, and trackers.

A subject represents a single user whose events are tracked, and holds data specific to that user.

A tracker always has one active subject at a time associated with it. The default subject only has "platform=server" configured, but you can replace it with a subject containing more data. The tracker constructs events with that subject and sends them to one or more emitters, which sends them on to a Snowplow collector.

Assuming you have completed the Scala Tracker Setup, you are ready to initialize the Scala Tracker.

import com.snowplowanalytics.snowplow.scalatracker._
import com.snowplowanalytics.snowplow.scalatracker.emitters._

val emitter1 = AsyncEmitter.createAndStart("mycollector.com")
val emitter2 = new SyncEmitter("myothercollector.com", port = 8080)
val emitter3 = AsyncBatchEmitter.createAndStart(host = "myothercollector.com", port = 8080, bufferSize = 32)
val tracker = new Tracker(List(emitter1, emitter2, emitter3), "mytrackername", "myapplicationid")

The above code:

• creates a non-blocking emitter, emitter1, which sends events to "mycollector.com" on the default port, port 80
• creates a blocking emitter, emitter2, which sends events to "myothercollector.com" on port 8080
• creates a non-blocking batch emitter3, which will buffer events until buffer size reach 32 events and then send all of them at once in POST request
• creates a tracker which can be used to send events to all emitters

You can configure a subject with extra data and attach it to the tracker so that the data will be attached to every event:

val subject = new Subject()
  .setUserId("user-00035")
  .setPlatform(Desktop)
tracker.setSubject(subject)

Amazon Elastic Cloud can provide basic information about instance running your app. You can add this informational as additional custom context to all sent events by enabling it in Tracker after initializaiton of your tracker:

tracker.enableEc2Context()

Snowplow has been built to enable you to track a wide range of events that occur when users interact with your websites and apps. We are constantly growing the range of functions available in order to capture that data more richly.

Tracking methods supported by the Scala Tracker at a glance:

• trackSelfDescribingEvent
• trackStructEvent
• trackPageView

Use trackSelfDescribingEvent to track a custom Self-describing events (previously known as Unstructured Events) which consists of a name and an unstructured set of properties. This is useful when:

• You want to track event types which are proprietary/specific to your business (i.e. not already part of Snowplow), or
• You want to track events which have unpredictable or frequently changing properties

You can use its alias trackUnstructEvent.

Create a Snowplow unstructured event self-describing JSON using the json4s DSL:

import org.json4s.JsonDSL._

val productViewEvent = SelfDescribingJson(
  "iglu:com.acme/product_view/jsonschema/1-0-0",
  ("userType" -> "tester") ~ ("sku" -> "0000013")
)

Send it using the trackSelfDescribingEvent tracker method:

tracker.trackSelfDescribingEvent(productViewEvent)

You can attach any number of custom contexts to an event:

val pageTypeContext = SelfDescribingJson(
  "iglu:com.acme/page_type/jsonschema/1-0-0",
  ("type" -> "promotional") ~ ("backgroundColor" -> "red")
)

val userContext = SelfDescribingJson(
  "iglu:com.acme/user/jsonschema/1-0-0",
  ("userType" -> "tester")
)

t.trackSelfDescribingEvent(productViewEvent, List(pageTypeContext, userContext))

Use trackStructEvent 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).

Example:

val pageTypeContext = SelfDescribingJson(
  "iglu:com.acme/page_type/jsonschema/1-0-0",
  ("type" -> "promotional") ~ ("backgroundColor" -> "red")
)

val userContext = SelfDescribingJson(
  "iglu:com.acme/user/jsonschema/1-0-0",
  ("userType" -> "tester")
)

t.trackStructEvent("commerce", "order", property=Some("book"), contexts=List(pageTypeContext, userContext))

Use trackPageView to track a user viewing a page within your app. Arguments are:

Example:

t.trackPageView("www.example.com", Some("example"), Some("www.referrer.com"))

By default, Scala Tracker will generate a dvce_created_tstamp and add it to event payload. You also can manually set it using timestamp argument in all tracking methods. It should be in milliseconds since the Unix epoch:

tracker.trackSelfDescribingEvent(productViewEvent, Nil, Some(1432806619000L))

Beside of it, you can set true_tstamp if you have more reliable source about event timestamp. You can tag timstamp as "true" using class TrueTimestamp:

tracker.trackSelfDescribingEvent(productViewEvent, Nil, Some(Tracker.TrueTimestamp(1432806619000L)))

Now event will be sent with ttm parameter instead of dtm.

A list of the methods used to add data to the Subject class.

The default platform is Server. These are the available alternatives, all available in the package com.snowplowanalytics.snowplow.scalatracker:

Server
Web
Mobile
Desktop
Tv
Console
InternetOfThings
General

Example usage

subject.setPlatform(Tv)

You can make the user ID a string of your choice:

subject.setUserId("user-000563456")

If your Scala code has access to the device's screen resolution, you can pass it in to Snowplow. Both numbers should be positive integers; note the order is width followed by height. Example:

subject.setScreenResolution(1366, 768)

Similarly, you can pass the viewport dimensions in to Snowplow. Again, both numbers should be positive integers and the order is width followed by height. Example:

subject.setViewport(300, 200)

If your Scala code has access to the bit depth of the device's color palette for displaying images, you can pass it in to Snowplow. The number should be a positive integer, in bits per pixel.

subject.setColorDepth(24)

If your Scala code has access to the timezone of the device, you can pass it in to Snowplow:

subject.setTimezone("Europe London")

You can set the language field like this:

subject.setLang("en")

If you have access to the user's IP address, you can set it like this:

subject.setIpAddresss("34.634.11.139")

If you have access to the user's useragent (sometimes called "browser string"), you can set it like this:

subject.setUseragent("Mozilla/5.0 (Windows NT 5.1; rv:24.0) Gecko/20100101 Firefox/24.0")

The domain_userid field of the Snowplow event model corresponds to the ID stored in the first party cookie set by the Snowplow JavaScript Tracker. If you want to match up server-side events with client-side events, you can set the domain user ID for server-side events like this:

subject.setDomainUserId("c7aadf5c60a5dff9")

The network_user_id field of the Snowplow event model corresponds to the ID stored in the third party cookie set by the Snowplow Clojure Collector and Scala Stream Collector. You can set the network user ID for server-side events like this:

subject.setNetworkUserId("ecdff4d0-9175-40ac-a8bb-325c49733607")

Back to top