Collecting data with Trackers and Webhooks

  1. Home
  2. Docs
  3. Collecting data with Trackers and Webhooks
  4. Trackers – collecting data from your own applications
  5. Mobile Native Trackers
  6. Mobile Trackers v2.0
  7. Tracking Events

Tracking Events

The mobile trackers capture two types of events, automatically captured and manual events.

Auto Tracking

Automatically captured events in the iOS Tracker are:

  • App Lifecycle Tracking
    • Captures application foreground and application background events
  • Screen View Tracking
    • Captures each time a new “screen” is loaded
  • Exception Tracking
    • Captures any unhandled exceptions within the application
  • Installation Tracking
    • Captures an install event which occurs the first time an application is opened

These are enabled in the tracker configuration. In this example, some helpful automatic contexts and all Autotracking is enabled:

let trackerConfig = TrackerConfiguration() .sessionContext(true) .platformContext(true) .screenContext(true) .applicationContext(true) .lifecycleAutotracking(true) .screenViewAutotracking(true) .exceptionAutotracking(true) .installAutotracking(true)
Code language: JavaScript (javascript)

Custom Event Context

Custom context can be used to augment any standard Snowplow event type, including self describing events, with additional data. We refer to this custom context as Event Entities.

Custom context can be added as an extra argument to any of Snowplow’s track..() methods and to addItem and addTrans.

Each custom context is an array of self-describing JSON following the same pattern as an self describing event. As with self describing events, if you want to create your own custom context, you must create a JSON schema for it and upload it to an Iglu repository using the Snowplow Insights UI, Data Structures API, igluctl or one of the other supported Iglu clients. Since more than one (of either different or the same type) can be attached to an event, the context argument (if it is provided at all) should be a non-empty array of self-describing JSONs.

Important: Even if only one custom context is being attached to an event, it still needs to be wrapped in an array.

Here are two example custom context JSONs. One describes a screen:

{ schema: 'iglu:com.example/screen/jsonschema/1-2-1', data: { screenType: 'test', lastUpdated: '2021-06-11' } }
Code language: JSON / JSON with Comments (json)

and the other describes a user on that screen:

{ schema: 'iglu:com.example/user/jsonschema/2-0-0', data: { userType: 'tester' } }
Code language: JSON / JSON with Comments (json)

Tracking events with Custom Context

How to track a screen view with both of these contexts attached:

let event = ScreenView(name: "DemoScreenName", screenId: UUID()) event.contexts.add( SelfDescribingJson(schema: "iglu:com.example/screen/jsonschema/1-2-1", andDictionary: [ "screenType": "test", "lastUpdated": "2021-06-11" ])!) event.contexts.add( SelfDescribingJson(schema: "iglu:com.example/user/jsonschema/2-0-0", andDictionary: [ "userType": "tester" ])!) tracker.track(event)
Code language: JavaScript (javascript)

It is also possible to add contexts globally, so that they are applied to all (or a subset of) events within an application.

Manual Tracking

Self Describing

You may wish to track events in your app which are not directly supported by Snowplow and which structured event tracking does not adequately capture. Your event may have more than the five fields offered by Structured events, or its fields may not fit into the category-action-label-property-value model. The solution is Snowplow’s self-describing events. Self-describing events are a data structure based on JSON Schemas and can have arbitrarily many fields.

To define your own custom event, you must create a JSON schema for that event and upload it to an Iglu Schema Repository using igluctl (or if a Snowplow Insights customer, you can use the Insights UI or Data Structures API). Snowplow uses the schema to validate that the JSON containing the event properties is well-formed.

let data = ["targetUrl": "http://a-target-url.com" as NSObject]; let event = SelfDescribing(schema: "iglu:com.snowplowanalytics.snowplow/link_click/jsonschema/1-0-1", payload: data) tracker.track(event)
Code language: Swift (swift)

A Self Describing event is a self-describing JSON. It has two fields:

  • data field, containing the properties of the event
  • schema field, containing the location of the JSON schema against which the data field should be validated.

Structured

Our philosophy in creating Snowplow is that users should capture important consumer interactions and design suitable data structures for this data capture. You can read more about that philosophy here. Using trackSelfDescribingEvent captures these interactions with custom schemas, as desribed above.

However, as part of a Snowplow implementation there may be interactons where custom Self Describing events are perhaps too complex or unwarranted. They are then candidates to track using Structured, if none of the other event-specific methods outlined below are appropriate.

let event = Structured(category: "Example", action: "my-action") .label("my-label") .property("my-property") .value(5) tracker.track(event)
Code language: Swift (swift)

Timing

Use the Timing events to track user timing events such as how long resources take to load.

let event = Timing(category: "timing-category", variable: "timing-variable", timing: 5) .label("optional-label") tracker.track(event)
Code language: Swift (swift)

Screen View

Track the user viewing a screen within the application. This type of tracking is typically used when automatic screen view tracking is not suitable within your application.

let event = ScreenView(name: "DemoScreenName", screenId: UUID()) tracker.track(event)
Code language: JavaScript (javascript)

Consent

Consent Granted

Use the ConsentGranted event to track a user opting into data collection. A consent document context will be attached to the event using the id and version arguments supplied.

let event = ConsentGranted(expiry: "2022-01-01T00:00:00Z", documentId: "1234abcd", version: "1.2") .name("document-name") .documentDescription("document-description") tracker.track(event)
Code language: Swift (swift)

Consent Withdrawn

Use the ConsentWithdrawn event to track a user withdrawing consent for data collection. A consent document context will be attached to the event using the id and version arguments supplied. To specify that a user opts out of all data collection, all should be set to true.

let event = ConsentWithdrawn() .all(true) .documentId("1234abcd") .version("1.2") .name("document-name") .documentDescription("document-description") tracker.track(event)
Code language: Swift (swift)

Ecommerce Transaction

Modelled on Google Analytics ecommerce tracking capability, Snowplow uses three steps that can be used together to track online transactions:

  1. Create a Ecommerce event. Use Ecommerce to initialize a transaction object. This will be the object that is loaded with all the data relevant to the specific transaction that is being tracked including all the items in the order, the prices of the items, the price of shipping and the order_id.
  2. Add items to the transaction. Create an array of EcommerceItem to pass to the Ecommerce object.
  3. Submit the transaction to Snowplow using the track() method, once all the relevant data has been loaded into the object.
let transactionID = "6a8078be" let itemArray = [ EcommerceItem(sku: "DemoItemSku", price: 0.75, quantity: 1) .name("DemoItemName") .category("DemoItemCategory") .currency("USD") ] let event = Ecommerce(orderId: transactionID, totalValue: 350, items: itemArray) .affiliation("DemoTransactionAffiliation") .taxValue(10) .shipping(15) .city("Boston") .state("Massachisetts") .country("USA") .currency("USD") tracker.track(event)
Code language: Swift (swift)

Push Notification

To track an event when a push notification is used, it is possible to use the PushNotification event which contains a NotificationContent object:

let attachments = [["identifier": "testidentifier", "url": "testurl", "type": "testtype"]] var userInfo = Dictionary<String, Any>() userInfo["test"] = "test" let content = NotificationContent(title: "title", body: "body", badge: 5) .subtitle("subtitle") .sound("sound") .launchImageName("launchImageName") .userInfo(userInfo) .attachments(attachments) let event = PushNotification( date: "date", action: "action", trigger: "PUSH", category: "category", thread: "thread", notification: content) tracker.track(event)
Code language: Swift (swift)

The mobile trackers capture two types of events, automatically captured and manual events.

Auto Tracking

Automatically captured events in the iOS Tracker are:

  • App Lifecycle Tracking
    • Captures application foreground and application background events
  • Screen View Tracking
    • Captures each time a new “screen” is loaded
  • Exception Tracking
    • Captures any unhandled exceptions within the application
  • Installation Tracking
    • Captures an install event which occurs the first time an application is opened

These are enabled in the tracker configuration. In this example, some helpful automatic contexts and all Autotracking is enabled:

TrackerConfiguration trackerConfiguration = new TrackerConfiguration(appId) .sessionContext(true) .platformContext(true) .applicationContext(true) .screenContext(true) .lifecycleAutotracking(true) .screenViewAutotracking(true) .exceptionAutotracking(true) .installAutotracking(true);
Code language: Java (java)

Custom Event Context

Custom context can be used to augment any standard Snowplow event type, including self describing events, with additional data. We refer to this custom context as Event Entities.

Custom context can be added as an extra argument to any of Snowplow’s track..() methods and to addItem and addTrans.

Each custom context is an array of self-describing JSON following the same pattern as an self describing event. As with self describing events, if you want to create your own custom context, you must create a JSON schema for it and upload it to an Iglu repository using the Snowplow Insights UI, Data Structures API, igluctl or one of the other supported Iglu clients. Since more than one (of either different or the same type) can be attached to an event, the context argument (if it is provided at all) should be a non-empty array of self-describing JSONs.

Important: Even if only one custom context is being attached to an event, it still needs to be wrapped in an array.

Here are two example custom context JSONs. One describes a screen:

{ schema: 'iglu:com.example/screen/jsonschema/1-2-1', data: { screenType: 'test', lastUpdated: '2021-06-11' } }
Code language: JSON / JSON with Comments (json)

and the other describes a user on that screen:

{ schema: 'iglu:com.example/user/jsonschema/2-0-0', data: { userType: 'tester' } }
Code language: JSON / JSON with Comments (json)

Tracking events with Custom Context

How to track a screen view with both of these contexts attached:

ScreenView event = new ScreenView("screen", UUID.randomUUID().toString()); event.customContexts.add( new SelfDescribingJson("iglu:com.example/screen/jsonschema/1-2-1", new HashMap<String, String>() {{ put("screenType", "test"); put("lastUpdated", "2021-06-11"); }}) ); event.customContexts.add( new SelfDescribingJson("iglu:com.example/user/jsonschema/2-0-0", new HashMap<String, String>() {{ put("userType", "tester"); }}) ); tracker.track(event);
Code language: Java (java)

It is also possible to add contexts globally, so that they are applied to all (or a subset of) events within an application.

Manual Tracking

Self Describing

You may wish to track events in your app which are not directly supported by Snowplow and which structured event tracking does not adequately capture. Your event may have more than the five fields offered by Structured events, or its fields may not fit into the category-action-label-property-value model. The solution is Snowplow’s self-describing events. Self-describing events are a data structure based on JSON Schemas and can have arbitrarily many fields.

To define your own custom event, you must create a JSON schema for that event and upload it to an Iglu Schema Repository using igluctl (or if a Snowplow Insights customer, you can use the Insights UI or Data Structures API). Snowplow uses the schema to validate that the JSON containing the event properties is well-formed.

Map<String, String> properties = new HashMap<>(); properties.put("targetUrl", "http://a-target-url.com"); SelfDescribingJson sdj = new SelfDescribingJson("iglu:com.snowplowanalytics.snowplow/link_click/jsonschema/1-0-1", attributes); SelfDescribing event = new SelfDescribing(sdj); tracker.track(event);
Code language: Java (java)

A Self Describing event is a self-describing JSON. It has two fields:

  • data field, containing the properties of the event
  • schema field, containing the location of the JSON schema against which the data field should be validated.

Structured

Our philosophy in creating Snowplow is that users should capture important consumer interactions and design suitable data structures for this data capture. You can read more about that philosophy here. Using trackSelfDescribingEvent captures these interactions with custom schemas, as desribed above.

However, as part of a Snowplow implementation there may be interactons where custom Self Describing events are perhaps too complex or unwarranted. They are then candidates to track using Structured, if none of the other event-specific methods outlined below are appropriate.

Structured event = Structured("my-category", "my-action") .label("my-label") .property("my-property") .value(5); tracker.track(event);
Code language: Java (java)

Timing

Use the Timing events to track user timing events such as how long resources take to load.

Timing event = new Timing("timing-category", "timing-variable", 5) .label("optional-label"); tracker.track(event);
Code language: Java (java)

Screen View

Track the user viewing a screen within the application. This type of tracking is typically used when automatic screen view tracking is not suitable within your application.

ScreenView event = new ScreenView("screen", UUID.<em>randomUUID</em>().toString()); tracker.track(event);
Code language: Java (java)

Consent

Consent Granted

Use the ConsentGranted event to track a user opting into data collection. A consent document context will be attached to the event using the id and version arguments supplied.

ConsentGranted event = new ConsentGranted("2018-05-08T18:12:02+00:00", "doc id", "1.2") .documentDescription("doc description") .documentName("doc name"); tracker.track(event);
Code language: Java (java)

Consent Withdrawn

Use the ConsentWithdrawn event to track a user withdrawing consent for data collection. A consent document context will be attached to the event using the id and version arguments supplied. To specify that a user opts out of all data collection, all should be set to true.

ConsentWithdrawn event = new ConsentWithdrawn(true, "doc id", "1.2") .documentDescription("doc description") .documentName("doc name"); tracker.track(event);
Code language: Java (java)

Ecommerce Transaction

Modelled on Google Analytics ecommerce tracking capability, Snowplow uses three steps that can be used together to track online transactions:

  1. Create a Ecommerce event. Use Ecommerce to initialize a transaction object. This will be the object that is loaded with all the data relevant to the specific transaction that is being tracked including all the items in the order, the prices of the items, the price of shipping and the order_id.
  2. Add items to the transaction. Create an array of EcommerceItem to pass to the Ecommerce object.
  3. Submit the transaction to Snowplow using the track() method, once all the relevant data has been loaded into the object.
EcommerceTransactionItem item = new EcommerceTransactionItem("sku-1", 35.00, 1) .name("Acme 1") .category("Stuff") .currency("USD"); List<EcommerceTransactionItem> items = new LinkedList<>(); items.add(item); EcommerceTransaction event = new EcommerceTransaction("order-1", 40.00, items) .shipping(5.00); tracker.track(event);
Code language: Java (java)

If you’d like to learn more about Snowplow Insights you can book a demo with our team, or if you’d prefer, you can try Snowplow technology for yourself quickly and easily.