Skip to main content

Sending events

trackSelfDescribingEvent

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.

ArgumentDescriptionRequired?Type
unstructuredEventSelf-describing JSON containing unstructured eventYesSelfDescribingJson
contextsList of custom contexts for the eventNoList[SelfDescribingJson]
timestampDevice created timestamp or true timestampNoOption[Timestamp]

Create a Snowplow unstructured event self-describing JSON:

import com.snowplowanalytics.iglu.core.{SchemaKey, SchemaVer}
import io.circe.Json

val productViewEvent = SelfDescribingJson(
SchemaKey("com.acme", "product_view", "jsonschema", SchemaVer(1,0,0)),
Json.obj(
"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(
SchemaKey("com.acme", "page_type", "jsonschema", SchemaVer(1,0,0)),
Json.obj(
"type" := "promotional",
"backgroundColor" := "red"
)
)

val userContext = SelfDescribingJson(
SchemaKey("com.acme", "user", "jsonschema", SchemaVer(1,0,0)),
Json.obj(
"userType" := "tester"
)
)

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

trackStructEvent

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

ArgumentDescriptionRequired?Type
categoryThe grouping of structured events which this action belongs toYesString
actionDefines the type of user interaction which this event involvesYesString
labelA string to provide additional dimensions to the event dataNoOption[String]
propertyA string describing the object or the action performed on itNoOption[String]
valueA value to provide numerical data about the eventNoOption[Double]
contextsList of custom contexts for the eventNoList[SelfDescribingJson]
timestampDevice created timestamp or true timestampNoOption[Timestamp]

Example:

val pageTypeContext = SelfDescribingJson(
SchemaKey("com.acme", "page_type", "jsonschema", SchemaVer(1,0,0)),
Json.obj(
"type" := "promotional",
"backgroundColor" := "red"
)
)

val userContext = SelfDescribingJson(
SchemaKey("com.acme", "user", "jsonschema", SchemaVer(1,0,0)),
Json.obj(
"userType" := "tester"
)
)

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

trackPageView

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

ArgumentDescriptionRequired?Validation
pageUrlThe URL of the pageYesString
pageTitleThe title of the pageNoOption[String]
referrerThe address which linked to the pageNoOption[String]
contextsCustom contexts for the eventNoList[SelfDescribingJson]
timestampWhen the pageview occurredNoOption[Timestamp]

Example:

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

trackError

Use trackError to track exceptions raised during your app's execution. Arguments are:

ArgumentDescriptionRequired?Validation
errorAny throwable need to be trackedYesThrowable
contextsCustom contexts for the eventNoList[SelfDescribingJson]
timestampWhen the pageview occurredNoOption[Timestamp]

Example:

try {
1 / 0
} catch {
case e: java.lang.ArithmeticException =>
t.trackError(e)
}

Note: this tracker should not be used to track exceptions happening in tracker itself, use callbacks mechanism for that.

trackAddToCart

Use trackAddToCart to track an add-to-cart event.

trackRemoveFromCart

Use trackRemoveFromCart to track a remove-from-cart event.

trackTransaction

Use trackTransaction to record view of transaction. Fire a trackTransaction to register the transaction, and then fire trackTransactionItem to log specific data about the items that were part of that transaction.

trackTransactionItem

To track an ecommerce transaction item. Fire a trackTransaction to register the transaction, and then fire trackTransactionItem to log specific data about the items that were part of that transaction.

Setting timestamp

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.

Setting the subject

By default, each event is associated with the (optional) Subject defined on the tracker instance. You can also send a Subject for each individual event, which overrides the default Subject.

val subject = new Subject()
.setUserId("user-00035")
.setPlatform(Desktop)
t.trackPageView("www.example.com", subject = Some(subject))
Was this page helpful?