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

HOME > SNOWPLOW TECHNICAL DOCUMENTATION > Trackers > .NET Tracker

This page refers to version 1.0.0 of the Snowplow .NET Tracker. For previous releases up to 0.1.2, please see here.

• 1 Overview
  • 1.1 Snowplow Demo Application
• 2 Initialization
  • 2.1 Importing the library
  • 2.2 Creating a tracker
• 3 Tracker
  • 3.1 Constructor
  • 3.2 Functions
    • 3.2.1 StartEventTracking()
    • 3.2.2 StopEventTracking()
    • 3.2.3 Track(IEvent)
• 4 Emitter
  • 4.1 Emitter Constructor
  • 4.2 Endpoint Constructor
  • 4.3 Storage Constructor
  • 4.4 Queue Constructor
  • 4.5 Payload Serializer Constructor
• 5 Subject
  • 5.1 SetUserId
  • 5.2 SetScreenResolution
  • 5.3 SetViewport
  • 5.4 SetColorDepth
  • 5.5 SetTimezone
  • 5.6 SetLang
  • 5.7 SetIpAddress
  • 5.8 SetUseragent
  • 5.9 SetNetworkUserId
  • 5.10 SetDomainUserId
  • 5.11 SetPlatform
• 6 Client Session
  • 6.1 Constructor
  • 6.2 Functions
    • 6.2.1 SetBackground(bool)
• 7 Event Tracking
  • 7.1 Events Types
    • 7.1.1 PageView
    • 7.1.2 ScreenView
    • 7.1.3 Structured
    • 7.1.4 Timing
    • 7.1.5 SelfDescribing
    • 7.1.6 EcommerceTransaction
      • 7.1.6.1 EcommerceTransactionItem
  • 7.2 Custom Contexts
    • 7.2.1 DesktopContext
    • 7.2.2 MobileContext
    • 7.2.3 GeoLocationContext
    • 7.2.4 GenericContext
  • 7.3 SelfDescribingJson
• 8 Platform Specific Functions
  • 8.1 GetMobileContext
  • 8.2 GetGeoLocationContext
  • 8.3 GetDesktopContext
  • 8.4 GetLocalFilePath
  • 8.5 IsDeviceOnline

The Snowplow .NET Tracker allows you to track Snowplow events from your .NET websites and desktop applications. It's split into two libraries:

This is a fully functional .NET Standard 1.4 tracking library - it'll work on any platform that supports .NET Standard 1.4+ (including .NET 461+).

This is a Portable Class Library (PCL) wrapper around the core Snowplow.Tracker library that extends functionality in platform specific ways, for example to provide geo-location information when tracking users in a Xamarin mobile application. If you're using Xamarin we encourage you to use this library.

Back to top

The Xamarin demo application can be deployed on Android and iOS. Simply launch the Snowplow.Demo.App.sln solution file with Visual Studio and deploy to either emulators or actual test devices. The .NET Core Console demo application can also be loaded with Visual Studio using Snowplow.Demo.Console.sln.

Back to top

Assuming you have completed the .NET Tracker Setup for your project, you are now ready to initialize the .NET Tracker.

Back to top

Add the following using lines to the top of your .cs scripts to access the Tracker:

using Snowplow.Tracker.Emitters;
using Snowplow.Tracker.Endpoints;
using Snowplow.Tracker.Logging;
using Snowplow.Tracker.Models;
using Snowplow.Tracker.Models.Events;
using Snowplow.Tracker.Models.Adapters;
using Snowplow.Tracker.Queues;
using Snowplow.Tracker.Storage;

You should now be able to setup the Tracker!

Back to top

To use the Tracker in your code simply instantiate the Tracker interface with the following:

// Create logger
var logger = new ConsoleLogger();

// Controls the sending of events
var endpoint = new SnowplowHttpCollectorEndpoint(emitterUri, method: method, port: port, protocol: protocol, l: logger);

// Controls the storage of events
// NOTE: You must dispose of storage yourself when closing your application!
var storage = new LiteDBStorage("events.db");

// Controls queueing events
var queue = new PersistentBlockingQueue(storage, new PayloadToJsonString());

// Controls pulling events of the queue and pushing them to the sender
var emitter = new AsyncEmitter(endpoint, queue, l: logger);

// Contains information about who you are tracking
var subject = new Subject().SetPlatform(Platform.Mob).SetLang("EN");

Tracker.Tracker.Instance.Start(emitter: emitter, subject: subject, trackerNamespace: "some namespace", appId: "some appid", l: logger);

This starts a global singleton Tracker which can be accessed anywhere via the Tracker.Tracker.Instance.{{ method }} chain.

For more information please review the Tracker and Emitter specific sections.

Back to top

The Tracker object is responsible for co-ordinating the saving and sending of events as well as managing the optional Session object.

Back to top

A full Tracker construction should look like the following:

var logger = new ConsoleLogger();
var endpoint = new SnowplowHttpCollectorEndpoint(emitterUri, method: method, port: port, protocol: protocol, l: logger);
var storage = new LiteDBStorage("events.db");
var queue = new PersistentBlockingQueue(storage, new PayloadToJsonString());
var emitter = new AsyncEmitter(endpoint, queue, l: logger);
var subject = new Subject().SetPlatform(Platform.Mob).SetLang("EN");
var session = new ClientSession("client_session.dict", l: logger);

Tracker.Tracker.Instance.Start(emitter: emitter, subject: subject, clientSession: session, trackerNamespace: "some namespace", appId: "some appid", encodeBase64: true, l: logger);

The Tracker.Start(...) and Tracker.Stop() methods take full responsibility for starting and stopping the threads required for processing everything asynchronously. Do not use any other Start and Stop functions other than the ones directly for the Tracker to prevent unknown behaviours.

WARNING: The LiteDBStorage object must be disposed of manually after stopping the Tracker so you will need to maintain a reference to this object.

NOTE: The Subject variables can all be altered directly from the Tracker via replicated setter methods.

Back to top

The Tracker contains several critical functions that must be used to start Tracking.

Back to top

This function must be called before any events will start being stored or sent. This is due to the fact that we do not want to start any background processing from the constructors so it is left up to the developer to choose when to start everything up.

If you attempt to access the Tracker singleton before Starting it an exception will be thrown.

This function:

• Starts the background emitter thread
• Starts the background session check timer (Optional)

Once this is run everything should be in place for asynchronous event tracking.

Back to top

If you need to halt the Tracker from tracking events you can run this function. This will bring all event processing, sending and collection to a halt and nothing will be started again until Start(...) is fired again.

WARNING: If you are using Client Sessionization stopping and then restarting the Tracker will result in the session index incrementing.

Back to top

This is the function used for Tracking all events. You can pass any of these event types to this function.

Tracker.Tracker.Instance.Track(IEvent newEvent);

Back to top

The Emitter object is responsible for sending and storing all events.

We have one emitter available currently:

• AsyncEmitter : Fully asynchronous operation which uses threads to perform all of its operations.

The Emitter however depends on four other objects being built:

• IEndpoint
• IStorage
• IPersistentBlockingQueue
• IPayloadToString

Back to top

A full Emitter construction should look like the following:

var endpoint = new SnowplowHttpCollectorEndpoint(emitterUri, method: method, port: port, protocol: protocol, l: logger);
var storage = new LiteDBStorage("events.db");
var queue = new PersistentBlockingQueue(storage, new PayloadToJsonString());

AsyncEmitter emitter = new AsyncEmitter(endpoint, queue, l: logger);

NOTE: The send limit can impact performance greatly as it determines how often we need to perform I/O to the disk and how big the POSTed event batches can be.

WARNING: If you are sending events via GET note that each event is sent as its own task, so this has the potential to launch 100 outbound tasks in parallel. It is recommended to lower this range if using GET to 10-15 as a maximum.

Back to top

This is a container for information about how to reach your collector.

We have one endpoint available currently:

• SnowplowHttpCollectorEndpoint

A full Endpoint construction should look like the following:

SnowplowHttpCollectorEndpoint endpoint = new SnowplowHttpCollectorEndpoint("com.acme-collector", protocol: HttpProtocol.HTTPS, method: HttpMethod.GET, l: logger);

NOTE: If any individual event exceeds the byte limits set then this event will be sent - but it will be assumed to have succeeded. This is to prevent constanstly attempting to send overly large events.

Back to top

We have one storage target available currently:

• LiteDBStorage

A full Storage construction should look like the following:

LiteDBStorage storage = new LiteDBStorage("events.db");

NOTE: When using the Tracker within Xamarin you will need to fetch a correct path for internal storage. Some example code for fetching this path:

// Android
public string GetLocalFilePath(string filename)
{
  string path = Environment.GetFolderPath(Environment.SpecialFolder.Personal);
  return Path.Combine(path, filename);
}

// iOS
public string GetLocalFilePath(string filename)
{
  string docFolder = Environment.GetFolderPath(Environment.SpecialFolder.Personal);
  string libFolder = Path.Combine(docFolder, "..", "Library", "Databases");

  if (!Directory.Exists(libFolder))
  {
    Directory.CreateDirectory(libFolder);
  }

  return Path.Combine(libFolder, filename);
}

Back to top

We have one queue available currently:

• PersistentBlockingQueue

A full queue construction should look like the following:

PersistentBlockingQueue queue = new PersistentBlockingQueue(storage, new PayloadToJsonString());

Back to top

We have one payload serializer available currently:

• PayloadToJsonString

A full queue construction should look like the following:

PayloadToJsonString serializer = new PayloadToJsonString();

This controls how we queue information for internal use.

Back to top

You may have additional information about your application's environment, current user and so on, which you want to send to Snowplow with each event.

The Subject class has a set of Set...() methods to attach extra data relating to the user to all tracked events:

• SetUserId
• SetScreenResolution
• SetViewport
• SetColorDepth
• SetTimezone
• SetLang
• SetIpAddress
• SetUseragent
• SetNetworkUserId
• SetDomainUserId
• SetPlatform

Here are some examples:

Subject s1 = new Subject();
s1.SetUserId("Kevin Gleason");
s1.SetLang("en-gb");
s1.SetScreenResolution(1920, 1080);

Back to top

You can set the user ID to any string:

s1.SetUserId( "{{USER ID}}" )

Example:

s1.SetUserId("alexd")

Back to top

If your C# code has access to the device's screen resolution, then you can pass this in to Snowplow too:

s1.SetScreenResolution( {{WIDTH}}, {{HEIGHT}} )

Both numbers should be positive integers; note the order is width followed by height. Example:

s1.SetScreenResolution(1366, 768)

Back to top

If your C# code has access to the viewport dimensions, then you can pass this in to Snowplow too:

s1.SetViewport( {{WIDTH}}, {{HEIGHT}} )

Both numbers should be positive integers; note the order is width followed by height. Example:

s1.SetViewport(300, 200)

Back to top

If your C# code has access to the bit depth of the device's color palette for displaying images, then you can pass this in to Snowplow too:

s.SetColorDepth( {{BITS PER PIXEL}} )

The number should be a positive integer, in bits per pixel. Example:

s.SetColorDepth(32)

Back to top

This method lets you pass a user's timezone in to Snowplow:

s.SetTimezone( {{TIMEZONE}} )

The timezone should be a string:

s.SetTimezone("Europe/London")

Back to top

This method lets you pass a user's language in to Snowplow:

s.SetLang( {{LANGUAGE}} )

The language should be a string:

s.SetLang('en')

Back to top

This method lets you pass a user's IP Address in to Snowplow:

s.SetIpAddress( {{IP ADDRESS}} )

The IP address should be a string:

s.SetIpAddress("127.0.0.1");

Back to top

This method lets you pass a useragent in to Snowplow:

s.SetUseragent( {{USERAGENT}} )

The useragent should be a string:

s.SetUseragent("Agent Smith");

Back to top

This method lets you pass a Network User ID in to Snowplow:

s.SetNetworkUserId( {{NUID}} )

The network user id should be a string:

s.SetNetworkUserId("network-id");

Back to top

This method lets you pass a Domain User ID in to Snowplow:

s.SetDomainUserId( {{DUID}} )

The domain user id should be a string:

s.SetDomainUserId("domain-id");

Back to top

This method lets you set the Platform that the Tracker is running on:

s.SetPlatform( Platform.{{ option }} )

The Platform should be an enum:

s.SetPlatform(Platform.Mob);

Available platforms:

• Web
• Mob
• Pc
• Srv
• App
• Tv
• Cnsl
• Iot

Back to top

The Session object is responsible for maintaining persistent data around user sessions over the life-time of an application.

Back to top

A full ClientSession construction should look like the following:

ClientSession session = new ClientSession ("save_file_path.xml");

The timeout's refer to the length of time the session remains active after the last event is sent. As long as events are sent within this limit the session will not timeout.

NOTE: When using the Tracker within Xamarin you will need to fetch a correct path for internal storage. Some example code for fetching this path:

// Android
public string GetLocalFilePath(string filename)
{
  string path = Environment.GetFolderPath(Environment.SpecialFolder.Personal);
  return Path.Combine(path, filename);
}

// iOS
public string GetLocalFilePath(string filename)
{
  string docFolder = Environment.GetFolderPath(Environment.SpecialFolder.Personal);
  string libFolder = Path.Combine(docFolder, "..", "Library", "Databases");

  if (!Directory.Exists(libFolder))
  {
    Directory.CreateDirectory(libFolder);
  }

  return Path.Combine(libFolder, filename);
}

Back to top

Back to top

Will set whether or not the application is in the background. It is up to the developer to set this metric if they wish to have a different timeout for foreground and background.

NOTE: If a timeout occurs while the application has been backgrounded the SessionChecker will be stopped automatically. Session checking will resume on Foregrounding or on an event being tracked.

Back to top

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.

Events supported by the .NET Tracker at a glance:

Back to top

Back to top

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

Arguments are:

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)
    .SetTrueTimestamp(1423583655000)
    .SetEventId("uid-1")
    .Build());

Back to top

Use Track(ScreenView) to track a user viewing a screen (or equivalent) within your app. You must use either name or id. Arguments are:

Examples:

t1.Track(new ScreenView()
    .SetName("HUD > Save Game")
    .SetId("screen23")
    .Build());

t1.Track(new ScreenView()
    .SetName("HUD > Save Game")
    .SetId("screen23")
    .SetCustomContext(contextList)
    .SetTrueTimestamp(1423583655000)
    .SetEventId("uid-1")
    .Build());

Back to top

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

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)
    .SetTrueTimestamp(1423583655000)
    .SetEventId("uid-1")
    .Build());

Back to top

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

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)
    .SetTrueTimestamp(1423583655000)
    .SetEventId("uid-1")
    .Build());

Back to top

Custom unstructured 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 unstructured 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 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

The arguments are as follows:

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

// Create your event data
SelfDescribingJson eventData = new SelfDescribingJson("iglu:com.acme/save_game/jsonschema/1-0-0", eventDict);

// Track your event with your custom event data
t1.Track(new SelfDescribing()
    .SetEventData(eventData)
    .Build();

// OR

t1.Track(new SelfDescribing()
    .SetEventData(eventData)
    .SetCustomContext(contextList)
    .SetTrueTimestamp(1423583655000)
    .SetEventId("uid-1")
    .Build();

For more on JSON schema, see the blog post.

Back to top

Use Track(EcommerceTransaction) to track an ecommerce transaction.

Arguments:

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 device created timestamp, true timestamp, orderId, and currency as the main transaction event.

Back to top

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:

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());

Back to top

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 contexts!

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.

Back to top

The following arguments can be used in a DesktopContext:

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 ();

Back to top

The following arguments can be used in a MobileContext:

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 ();

Back to top

The following arguments can be used in a GeoLocationContext:

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 ();

Back to top

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();

Back to top

A 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 an SelfDescribing Event.

You can create a SelfDescribingJson with the following arguments:

Back to top

To support multiple platforms we provide several utility functions for fetching platform specific information.

Back to top

Platforms:

• Xamarin.Android API 15+
• Xamarin.iOS 8+

NOTE: These mobile contexts do not currently fetch any advertising identifiers.

Back to top

Platforms:

• Xamarin.Android API 15+
• Xamarin.iOS 8+

NOTE: To make the GeoLocation context work on iOS you will need to add the following to your Info.plist:

<key>UIBackgroundModes</key>
<array>
  <string>location</string>
</array>
<key>NSLocationAlwaysUsageDescription</key>
<string></string>

When you send your first event a prompt will be fired asking the user for permission to use their location.

Back to top

Platforms:

• .NET Framework 4.6.1+

Back to top

Platforms:

• Xamarin.Android API 15+
• Xamarin.iOS 8+

Back to top

Platforms:

• Xamarin.Android API 15+
• Xamarin.iOS 8+
• .NET Framework 4.6.1+

Back to top