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. React Native Tracker
  6. Tracking events

Tracking events

Tracker Maintenance Classification
Latest tracker version
Supported React Native versions



The React Native tracker captures two types of events, automatically captured and manual events.

Auto Tracking Features

Many of the automatic tracking options available on iOS and Android are also available in React Native – these can be enabled or disabled in the TrackerConfiguration passed to createTracker as part of the TrackerController configuration object.

Events

The React Native Tracker can be configured to automatically track the following events:

  • 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

Contexts

The contexts that can be set to be automatically attached to all events are:

  • Application context
  • Platform context
  • Geolocation context
  • Session context
  • Screen context

For more information on the enabled autotracking features by default, see also the Tracker Configuration section.

Manual tracking

All tracker’s track methods take two arguments: An object of key-value pairs for the event’s properties, and an optional array of custom event contexts.

Custom event contexts

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

Custom contexts can be optionally added as an extra argument to any of the Tracker’s track..() methods as an array of self-describing JSON following the same pattern as a 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 can be attached to an event, the context’s argument (if it is provided at all) should be a non-empty array of self-describing JSONs.

Note: Even if only one custom context is being attached to an event, it still needs to be wrapped in an array. Also an empty array is acceptable, which will attach no entities to the event.

For example, a custom context to describe a screen could be:

const myScreenContext: EventContext = { schema: 'iglu:com.example/screen/jsonschema/1-2-1', data: { screenType: 'test', lastUpdated: '2021-06-11' } };
Code language: JavaScript (javascript)

Another example custom context to describe a user on a screen could be:

const myUserEntity: EventContext = { schema: 'iglu:com.example/user/jsonschema/2-0-0', data: { userType: 'tester' } };
Code language: JavaScript (javascript)

Then, to track, for example, a screenViewEvent with both of these contexts attached:

tracker.trackScreenViewEvent( { name: 'myScreenName' }, [ myScreenContext, myUserEntity ] );
Code language: JavaScript (javascript)

It is also possible to add custom contexts globally, so that they are applied to all events within an application. For more information, see the Global Contexts section below.

Events

Self-describing events

You may wish to track events, which do not fit into the out-of-the box ones described below. 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.

Just like with custom event entities, to define your own custom self-describing 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 Console UI or Data Structures API). Snowplow uses the schema to validate that the JSON containing the event properties is well-formed.

A Self Describing event is a self-describing JSON.

Required properties

  • schema: (string) – A valid Iglu schema path. This must point to the location of the custom event’s schema, of the format: iglu:{vendor}/{name}/{format}/{version}.
  • data: (object) – The custom data for your event. This data must conform to the schema specified in the schema argument, or the event will fail validation and land in bad rows.

To track a custom self-describing event, use the trackSelfDescribingEvent method of the tracker.

For example, to track a link-click event, which is one whose schema is already published in Iglu Central:

tracker.trackSelfDescribingEvent({ schema: 'iglu:com.snowplowanalytics.snowplow/link_click/jsonschema/1-0-1', data: {targetUrl: 'http://a-target-url.com'} });
Code language: JavaScript (javascript)

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 trackStructuredEvent, if none of the other event-specific methods outlined below are appropriate.

For example:

tracker.trackStructuredEvent({ category: 'my-category', action: 'my-action', label: 'my-label', property: 'my-property', value: 50.00 });
Code language: JavaScript (javascript)

Required properties

  • category: The name you supply for the group of objects you want to track e.g. ‘media’, ‘ecomm’
  • action: A string which defines the type of user interaction for the web object e.g. ‘play-video’, ‘add-to-basket’

Optional properties

  • label: (string) – identifies the specific object being actioned e.g. ID of the video being played, or the SKU or the product added-to-basket
  • property: (string) – describes the object or the action performed on it. This might be the quantity of an item added to basket
  • value: (number) – quantifies or further describes the user action. This might be the price of an item added-to-basket, or the starting time of the video where play was just pressed

Timing

Use the trackTimingEvent tracker method to track user timing events such as how long resources take to load.

For example:

tracker.trackTimingEvent({ category: 'timing-category', variable: 'timing-variable', timing: 5, label: 'optional-label' });
Code language: JavaScript (javascript)

Required properties

  • category: (string) – Defines the timing category
  • variable: (string) – Define the timing variable measured
  • timing: (number) – Represent the time

Optional properties

  • label: An optional string to further identify the timing event

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.

To track a ScreenViewEvent, use the trackScreenViewEvent tracker method. For example:

tracker.trackScreenViewEvent({ name: 'my-screen-name', id: '5d79770b-015b-4af8-8c91-b2ed6faf4b1e', type: 'carousel', previousName: 'previous-screen', previousId: '00d71340-342e-4f3d-b9fd-4de728ffba7a', previousType: 'feed', transitionType: 'basic' });
Code language: JavaScript (javascript)

Required properties

  • name: (string) – The name of the screen viewed

Optional properties

  • id: (string) – The id(UUID) of screen that was viewed
  • type: (string) – The type of screen that was viewed
  • previousName: (string) – The name of the previous screen that was viewed
  • previousId: (string) – The id(UUID) of the previous screen that was viewed
  • previousType: (string) – The type of screen that was viewed
  • transitionType: (string) – The type of transition that led to the screen being viewed

Page View

Track a page view event with the trackPageViewEvent() method. Typically this is uncommon in apps, but is sometimes used where fitting data into an existing page views model is required. To track page views from an in-app browser, it is advisable to use the javascript tracker in-browser.

An example:

tracker.trackPageViewEvent({ pageUrl: 'https://my-url.com', pageTitle: 'My page title', referrer: 'http://some-other-url.com' });
Code language: JavaScript (javascript)

Required properties

  • pageUrl: (string) – Page Url for the page view event. Must be a valid url.

Optional properties

  • pageTitle: (string) – Page Title for the page view event.
  • referrer: (string) – Url for the referring page to the page view event. Must be a vaild url.

Consent Granted

Use the trackConsentGrantedEvent method 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.

For example:

tracker.trackConsentGrantedEvent({ expiry: '2022-01-01T00:00:00Z', documentId: 'doc-id', version: '1.2', name: 'doc-name', documentDescription: 'consent doc description' });
Code language: JavaScript (javascript)

Required properties

  • expiry: (string) – The expiry (date-time string, e.g.: ‘2022-01-01T00:00:00Z’)
  • documentId: (string) – The consent document id
  • version: (string) – The consent document version

Optional properties

  • name: (string) – The consent document name
  • documentDescription: (string) – The consent document description

Consent Withdrawn

Use the trackConsentWithdrawnEvent method 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.

For example:

tracker.trackConsentWithdrawnEvent({ all: true, documentId: 'doc-id', version: '1.2', name: 'doc-name', documentDescription: 'consent doc description' });
Code language: JavaScript (javascript)

Required properties

  • all: (boolean) – Whether user opts out of all data collection
  • documentId: (string) – The consent document id
  • version: (string) – The consent document version

Optional properties

  • name: (string) – The consent document name
  • documentDescription: (string) – The consent document description

Ecommerce Transaction

Modelled on Google Analytics ecommerce tracking capability, an ecommerce-transaction event can be tracked as follows:

  1. Create a EcommerceTransaction event object. This will be the object that is loaded with all the properties relevant to the specific transaction that is being tracked including all the items (see EcommerceItem right below) in the order, the prices of the items, the price of shipping and the order_id.
  2. Track the transaction using the trackEcommerceTransaction method.

The procedured outlined above will result in the following events being tracked:

  1. An EcommerceTransaction event
  2. As many as EcommerceItem events as the items passed to the EcommerceTransaction object, that will also inherit the orderId from the parent transaction event
EcommerceItem

More specifically, to start with, the properties of an EcommerceItem are:

Required properties

  • sku: (string) – The item sku
  • price: (number) – The item price
  • quantity: (number) – The quantity purchased

Optional properties

  • name: (string) – The item name
  • category: (string) – The item category
  • currency: (string) – The item currency

For example:

const ecomItem: EcommerceItem = { sku: 'DD44', name: 'T-Shirt', category: 'Green Medium', price: 15, quantity: 1, currency: 'USD' };
Code language: JavaScript (javascript)
EcommerceTransaction

An ecommerce transaction object has the following properties:

Required properties

  • orderId: (string) – The order ID of the transaction
  • totalValue: (number) – The total value of the transaction
  • items: (array of EcommerceItem) – The ecommerce items purchased in the transaction.

Optional properties

  • affiliation: (string)
  • taxValue: (number)
  • shipping: (number)
  • city: (string)
  • state: (string)
  • country: (string)
  • currency: (string)
const ecomTransaction: EcommerceTransactionProps = { orderId: '1234', totalValue: 15, items: [ ecomItem ], affiliation: 'Womens Apparel', taxValue: 1.5, shipping: 2.99, city: 'San Jose', state: 'California', country: 'USA', currency: 'USD' };
Code language: JavaScript (javascript)
trackEcommerceTransaction

Then, to track the ecommerce transaction as described in the above examples:

tracker.trackEcommerceTransactionEvent(ecomTransaction);
Code language: JavaScript (javascript)

Setting the Subject data

The subject is a persistent object containing global data that applies to all events, such as a manually set userId. As also described in the SubjectConfiguration section, you can set properties of the subject on tracker initailization.

It is also possible to set or change the subject properties at runtime, using the set.. methods of the React Native Tracker. The available methods are:

  1. setUserId

With this method you can set the userId to a new string. To unset the userId, pass a null value as an argument.

tracker.setUserId('newUser');
Code language: JavaScript (javascript)

2. setNetworkUserId

With this method you can set the network_userid to a new string(UUIDv4). To unset, pass a null value as an argument.

tracker.setNetworkUserId('44df44bc-8844-4067-9a89-f83c4fe1e62f');
Code language: JavaScript (javascript)

3. setDomainUserId

With this method you can set the domain_userid to a new string(UUIDv4). To unset, pass a null value as an argument.

tracker.setDomainUserId('0526be47-32cb-44b2-a9e6-fefeaa5ec6fa');
Code language: JavaScript (javascript)

4. setIpAddress

With this method you can set the user_ipaddress to a new string. To unset, pass a null value as an argument.

tracker.setIpAddress('123.45.67.89');
Code language: JavaScript (javascript)

5. setUseragent

With this method you can set the useragent to a new string. To unset, pass a null value as an argument.

tracker.setUseragent('some-useragent-string');
Code language: JavaScript (javascript)

6. setTimezone

With this method you can set the os_timezone to a new string. To unset, pass a null value as an argument.

tracker.setTimezone('Africa/Cairo');
Code language: JavaScript (javascript)

7. setLanguage

With this method you can set the br_lang to a new string. To unset, pass a null value as an argument.

tracker.setLanguage('fr');
Code language: JavaScript (javascript)

8. setScreenResolution

With this method you can set the dvce_screenwidth and dvce_screenheight fields to new integer values. The argument to this method is an array that represents the ScreenSize as [width, height]. For example:

tracker.setScreenResolution([123, 456]);
Code language: JavaScript (javascript)

9. setScreenViewport

With this method you can set the br_viewwidth and br_viewheight fields to new integer values. The argument to this method is an array that represents the ScreenSize as [width, height]. For example:

tracker.setScreenViewport([123, 456]);
Code language: JavaScript (javascript)

10. setColorDepth

With this method you can set the br_colordepth to a new value. For example:

tracker.setColorDepth(20);
Code language: JavaScript (javascript)

Finally, there is an extra “wrapper” method to set may subject properties at once:

  • setSubjectData

This method accepts as an argument a SubjectConfiguration, with the new values as needed. For example:

tracker.setSubjectData({ userId: 'tester', domainUserId: '5d79770b-015b-4af8-8c91-b2ed6faf4b1e', language: 'es', colorDepth: 50, screenResolution: [300, 300], });
Code language: JavaScript (javascript)

Global Contexts

As mentioned in the GCConfiguration section, you can set global contexts when initializing the tracker.

However, as the user journey evolves, you may need to remove or add global contexts at runtime.

Removing Global Contexts

A set of global contexts is identified by its tag, which was set when the global contexts was added, either as part of tracker initial configuration or manually (see below).

To remove the global contexts associated with a tag, you can use the removeGlobalContexts tracker method, which takes as argument the tag. For example:

tracker.removeGlobalContexts('my-old-tag');
Code language: JavaScript (javascript)

Adding Global Contexts

Similarly, you can add global contexts at runtime using the addGlobalContexts tracker method. This method takes as argument the GlobalContext to add.

For example:

tracker.addGlobalContexts({ tag: 'my-new-tag', globalContexts: [ { schema: 'iglu:com.snowplowanalytics.snowplow/ad_impression/jsonschema/1-0-0', data: {impressionId: 'my-ad-impression-id'}, }, ] });
Code language: JavaScript (javascript)

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.