Skip to main content

Event tracking

Event Types

Track page views with Track(PageView)

You can use Track(PageView) to track a user viewing a web page within your app.

Arguments are:

ArgumentDescriptionRequired?Type
pageUrlThe URL of the pageYesstring
pageTitleThe title of the pageNostring
referrerThe address which linked to the pageNostring
customContextsOptional custom contextNoList<IContext>
timestampOptional timestampNolong
eventIdOptional custom event idNostring

Examples:

t1.Track(new PageView()
.SetPageUrl("www.example.com")
.SetPageTitle("example")
.SetReferrer("www.referrer.com")
.Build());

t1.Track(new PageView()
.SetPageUrl("www.example.com")
.SetPageTitle("example")
.SetReferrer("www.referrer.com")
.SetCustomContext(contextList)
.SetTimestamp(1423583655000)
.SetEventId("uid-1")
.Build());

Track screen views with Track(MobileScreenView)

Use Track(MobileScreenView) to track a user viewing a screen (or equivalent) within your app. You must provide a name property. The id of the screen view will be automatically assigned (as an UUID) but you may also provide it manually. Arguments are:

ArgumentDescriptionRequired?Type
nameHuman-readable name for this screenYesstring
idUnique identifier for this screen view (can be auto-generated)Yesstring
typeThe type of screen that was viewed e.g feed / carouselNostring
previousNameThe name of the previous screenNostring
previousIdThe screen view ID of the previous screen viewNostring
previousTypeThe screen type of the previous screen viewNostring
previousTypeThe screen type of the previous screen viewNostring
customContextsOptional custom contextNoList<IContext>
timestampOptional timestampNolong
eventIdOptional custom event idNostring

Examples:

t1.Track(new MobileScreenView("HUD > Save Game")
.SetType("dialog")
.SetPreviousName("HUD > Menu")
.SetPreviousId(previousScreenId)
.SetTransitionType("pop-up")
.Build());

t1.Track(new MobileScreenView("HUD > Save Game")
.SetCustomContext(contextList)
.SetTimestamp(1423583655000)
.SetEventId("uid-1")
.Build());
note

In tracker versions 0.7.0 and earlier, screen views were tracked using the ScreenView class. However, this class used the older schema for screen views and has been deprecated in favour of the MobileScreenView in the 0.8.0 release of the tracker.

Track structured events with Track(Structured)

Use Track(Structured) 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 dataNostring
propertyA string describing the object or the action performed on itNostring
valueA value to provide numerical data about the eventNodouble
customContextsOptional custom contextNoList<IContext>
timestampOptional timestampNolong
eventIdOptional custom event idNostring

Examples:

t1.Track(new Structured()
.SetCategory("shop")
.SetAction("add-to-basket")
.Build());

t1.Track(new Structured()
.SetCategory("shop")
.SetAction("add-to-basket")
.SetLabel("Add To Basket")
.SetProperty("pcs")
.SetValue(2.00)
.SetCustomContext(contextList)
.SetTimestamp(1423583655000)
.SetEventId("uid-1")
.Build());

Track timing events with Track(Timing)

Use Track(Timing) to track an event related to a custom timing.

ArgumentDescriptionRequired?Type
categoryThe category of the timed eventYesstring
labelThe label of the timed eventNostring
timingThe timing measurement in millisecondsYesint
variableThe name of the timed eventYesstring
customContextsOptional custom contextNoList<IContext>
timestampOptional timestampNolong
eventIdOptional custom event idNostring

Examples:

t1.Track(new Timing()
.SetCategory("category")
.SetVariable("variable")
.SetTiming(1)
.Build());

t1.Track(new Timing()
.SetCategory("category")
.SetVariable("variable")
.SetTiming(1)
.SetLabel("label")
.SetCustomContext(contextList)
.SetTimestamp(1423583655000)
.SetEventId("uid-1")
.Build());

Track self-describing events with Track(SelfDescribing)

Custom self-describing events are a flexible tool that enable Snowplow users to define their own event types and send them into Snowplow.

When a user sends in a custom self-describing event, they do so as a JSON of name-value properties, that conforms to a JSON schema defined for the event earlier.

Use Track(SelfDescribing) to track a custom event which consists of a name and a self-describing 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

The arguments are as follows:

ArgumentDescriptionRequired?Type
eventDataThe properties of the eventYesSelfDescribingJson
customContextsOptional custom contextNoList<IContext>
timestampOptional timestampNolong
eventIdOptional custom event idNostring

Example event json to track:

{
"schema": "iglu:com.acme/save_game/jsonschema/1-0-0",
"data": {
"levelName": "Barrels o' Fun",
"levelIndex": 23
}
}

How to set it up?

// Create a Dictionary of your event data
Dictionary<string, object> eventDict = new Dictionary<string, object>();
eventDict.Add("levelName", "Barrels o' Fun");
eventDict.Add("levelIndex", 23);

// Track your event with your custom event data
t1.Track(new SelfDescribing("iglu:com.acme/save_game/jsonschema/1-0-0", eventDict)
.Build();

// OR

t1.Track(new SelfDescribing("iglu:com.acme/save_game/jsonschema/1-0-0", eventDict)
.SetCustomContext(contextList)
.SetTimestamp(1423583655000)
.SetEventId("uid-1")
.Build();

For more on JSON schema, see the blog post.

note

In versions 0.7.0 and earlier, the Unstructured class was used to track self-describing events. This was deprecated in version 0.8.0 in favour of the SelfDescribing class.

Track ecommerce transactions with Track(EcommerceTransaction)

Use Track(EcommerceTransaction) to track an ecommerce transaction.

Arguments:

ArgumentDescriptionRequired?Type
orderIdID of the eCommerce transactionYesstring
totalValueTotal transaction valueYesdouble
affiliationTransaction affiliationNostring
taxValueTransaction tax valueNodouble
shippingDelivery cost chargedNodouble
cityDelivery address cityNostring
stateDelivery address stateNostring
countryDelivery address countryNostring
currencyTransaction currencyNostring
itemsItems in the transactionYesList<EcommerceTransactionItem>
customContextsOptional custom contextNoList<IContext>
timestampOptional timestampNolong
eventIdOptional custom event idNostring

The items argument is a List of individual EcommerceTransactionItem elements representing the items in the e-commerce transaction. Note that Track(EcommerceTransaction) fires multiple events: one transaction event for the transaction as a whole, and one transaction item event for each element of the items List.

Each transaction item event will have the same timestamp, orderId, and currency as the main transaction event.

EcommerceTransactionItem

To instantiate a EcommerceTransactionItem in your code, simply use the following constructor signature:

EcommerceTransactionItem item = new EcommerceTransactionItem ()
.SetSku ("sku")
.SetPrice (10.2)
.SetQuantity (1)
.SetName ("name")
.SetCategory ("category")
.Build ()

These are the fields that can appear as elements in each EcommerceTransactionItem element of the transaction item's List:

FieldDescriptionRequired?Type
skuItem SKUYesstring
priceItem priceYesdouble
quantityItem quantityYesint
nameItem nameNostring
categoryItem categoryNostring
customContextsOptional custom contextNoList<IContext>
eventIdOptional custom event idNostring

Example of tracking a transaction containing two items:

// Create some Transaction Items
EcommerceTransactionItem item1 = new EcommerceTransactionItem ()
.SetSku ("item_sku_1")
.SetPrice (10.2)
.SetQuantity (1)
.SetName ("item_name_1")
.SetCategory ("item_category")
.Build ();

EcommerceTransactionItem item2 = new EcommerceTransactionItem()
.SetSku("item_sku_2")
.SetPrice(1.00)
.SetQuantity(1)
.SetName("item_name_2")
.SetCategory("item_category")
.Build();

// Add these items to a List
List<EcommerceTransactionItem> items = new List<EcommerceTransactionItem>();
items.Add(item1);
items.Add(item2);

// Now Track the Transaction by using this list of items as an argument
tracker.Track(new EcommerceTransaction()
.SetOrderId("order_id_1")
.SetTotalValue(300.00)
.SetAffiliation("my_affiliate")
.SetTaxValue(30.00)
.SetShipping(10.00)
.SetCity("Boston")
.SetState("Massachusetts")
.SetCountry("USA")
.SetCurrency("USD")
.SetItems(items)
.Build());

Custom Contexts

Custom contexts are Self Describing Jsons with extra descriptive information that can be optionally attached to any Snowplow event with SetCustomContexts(...). We provide several builders for Snowplow custom contexts as well as a generic builder if you wish to define and send your own custom context!

For ease of development you are also able to extend the IContext interface or the AbstractContext class for your own contexts if you so wish.

All of these contexts will need to be combined into a List<IContext> before being attachable to Snowplow Events.

DesktopContext

The following arguments can be used in a DesktopContext:

FieldDescriptionRequired?Type
osTypeThe Operating System TypeYesstring
osVersionThe Version of the Operating SystemYesstring
osServicePackService Pack informationNostring
osIs64BitIf the OS is 32 or 64 bitNobool
deviceManufacturerWho made the deviceNostring
deviceModelWhat is the device modelNostring
processorCountHow many cores does the device haveNoint

An example of a DesktopContext construction:

DesktopContext context = new DesktopContext ()
.SetOsType("OS-X")
.SetOsVersion("10.10.5")
.SetOsServicePack("Yosemite")
.SetOsIs64Bit(true)
.SetDeviceManufacturer("Apple")
.SetDeviceModel("Macbook Pro")
.SetDeviceProcessorCount(4)
.Build ();

MobileContext

The following arguments can be used in a MobileContext:

FieldDescriptionRequired?Type
osTypeThe Operating System TypeYesstring
osVersionThe Version of the Operating SystemYesstring
deviceManufacturerWho made the deviceYesstring
deviceModelWhat is the device modelYesstring
carrierThe name of the carrierNostring
networkTypeThe type of networkNoNetworkType
networkTechnologyThe networks technlogyNostring
openIdfaAn OpenIDFA UUIDNostring
appleIdfaAn Apple IDFA UUIDNostring
appleIdfvAn Apple IDFV UUIDNostring
androidIdfaAn Android IDFA UUIDNostring

An example of a MobileContext construction:

MobileContext context = new MobileContext ()
.SetOsType("iOS")
.SetOsVersion("9.0")
.SetDeviceManufacturer("Apple")
.SetDeviceModel("iPhone 6S+")
.SetCarrier("FREE")
.SetNetworkType(NetworkType.Mobile)
.SetNetworkTechnology("LTE")
.Build ();

GeoLocationContext

The following arguments can be used in a GeoLocationContext:

FieldDescriptionRequired?Type
latitudeThe user latitudeYesdouble
longitudeThe user longitudeYesdouble
latitudeLongitudeAccuracyThe user lat-long accuracyNodouble
altitudeThe user altitudeNodouble
altitudeAccuracyThe user alt accuracyNodouble
bearingThe user bearingNodouble
speedThe user speedNodouble
timestampA timestamp in msNolong

An example of a GeoLocationContext construction:

GeoLocationContext context = new GeoLocationContext ()
.SetLatitude(123.564)
.SetLongitude(-12.6)
.SetLatitudeLongitudeAccuracy(5.6)
.SetAltitude(5.5)
.SetAltitudeAccuracy(2.1)
.SetBearing(3.2)
.SetSpeed(100.2)
.SetTimestamp(1234567890000)
.Build ();

GenericContext

The GenericContext is a simple builder with three functions:

  • SetSchema(string) : Sets the Context Schema Path
  • Add(string, object) : Adds a single key-pair value to the data packet of this context
  • AddDict(string, object) : Adds a dictionary of key-pair values to the data packet

You must set a schema string or a RuntimeException will be thrown.

An example of a GenericContext construction:

GenericContext context = new GenericContext()
.SetSchema("iglu:com.acme/acme_context/jsonschema/1-0-0")
.Add("context", "custom")
.Build();

SelfDescribingJson

SelfDescribingJson is used as a wrapper around a Dictionary<string, object>. After creating the Dictionary you want to wrap you can create a SelfDescribingJson using the following:

// Data as a Dictionary
Dictionary<string, object> data = new Dictionary<string, object>();
data.Add("Event", "Data")

// We then create a new SelfDescribingJson
SelfDescribingJson json = new SelfDescribingJson("iglu:com.acme/example/jsonschema/1-0-0", data);

This object is now ready to be Tracked within a SelfDescribing Event.

You can create a SelfDescribingJson with the following arguments:

ArgumentDescriptionRequired?Type
schemaJsonSchema that describes the dataYesstring
dataData that will be validated by the schemaNoDictionary<string,object>