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

React Native Tracker

Early Release

The Snowplow React Native Tracker is a module which imports the Native Snowplow iOS and Android trackers as native modules, available for use in React Native projects.

Getting Started

Installation

Install the tracker with:

npm install @snowplow/react-native-tracker --save

Quickstart Guide

Minimal setup – initialise the tracker and track a screen view:

import Tracker from '@snowplow/react-native-tracker'; initialize({ endpoint: 'my-endpoint.com', namespace: 'namespace', appId: 'my-app-id' }); trackScreenViewEvent({screenName: 'myScreenName'})

What’s next?

Automatic Tracking Features

Many of the automatic tracking options available on iOS and Android are also available in react-native – these are enabled in the initialize() configuration. For example, to set up tracking of lifecycle events, with the mobile context and session context enabled:

import Tracker from '@snowplow/react-native-tracker'; initialize({ endpoint: 'my-endpoint.com', namespace: 'namespace', appId: 'my-app-id', lifecycleEvents: true, platformContext: true, sessionContext: true });

See the configuration section below for a full list of options.

Examples

Tracking custom events

Custom events may be tracked using the trackSelfDescribingEvent() method:

trackSelfDescribingEvent({ schema: 'iglu:com.acme/example/jsonschema/1-0-0', data: {someExampleField: 'Hello World'} });

See Custom Event Tracking Section below for more detail

Attaching Entities to events

All track methods take two arguments: A JSON of key-value pairs, and an optional array of self-describing JSON to be attached as entities. For example:

trackScreenViewEvent({ screenName: 'myScreenName'}, [{ schema: 'iglu:com.acme/example_entity/jsonschema/1-0-0', data: {someOtherExampleField: 'Foo Bar Baz'} }] ) trackSelfDescribingEvent({ schema: 'iglu:com.acme/example_event/jsonschema/1-0-0', data: {someExampleField: 'Hello World'} }, [{ schema: 'iglu:com.acme/example_entity/jsonschema/1-0-0', data: {someOtherExampleField: 'Foo Bar Baz'} }] );

An empty array is acceptable, which will attach no entities to the event.

Features

Configuration

Initialisation Options

initialize() takes a json of configuration options for the initilisation of the This will instantiate an Emitter and Tracker instance of the native tracker in the app.

The initialize() method returns a promise, and so can be chained or awaited, however this promise is returned immediately, so it is not strictly necessary to do so.

The tracker must be initialised before any other methods are called.

initialize({ // required endpoint: 'my-endpoint.com', namespace: 'my-namespace', appId: 'my-app-id', // optional method: 'post', protocol: 'https', platformContext: true, base64Encoded: true, applicationContext: true, lifecycleEvents: true, screenContext: true, sessionContext: true, foregroundTimeout: 600, backgroundTimeout: 300, checkInterval: 15, installTracking: true } );

Required properties

endpoint: Collector endpoint – omit the protocol.

Takes a string. Must be a valid Snowplow collector endpoint.

namespace: Tracker namespace – can be set to any string.

Takes a string.

appId: App ID – can be set to any string. Used to identify the environment being tracked.

Takes a string.

Optional properties

method: Http method for requests.

Takes a string enum – ‘get’ or ‘post’ – defaults to ‘post’.

protocol: Http protocol for requests.

Takes a string enum – ‘http’ or ‘https’ – defaults to ‘https’.

base64Encoded: base64 encodes custom events and contexts before sending.

Takes a boolean – defaults to true.

platformContext: Attach the platform context to all events – aka mobile context. The platform context contains operating system and device information, as well as the IDFV/IDFA values, if the app is configured to collect these.

Takes a boolean – defaults to true.

applicationContext: Attach the application context to all events. The application context contains app version and build number.

Takes a boolean – defaults to false.

screenContext: Attach the screen context to all events. The screen context contains information about the current and previous screen, along with a screen view id, which is incremented on every screen view event, and can be used to aggregate events to a screen view level in modeling. It is a similar concept to the page view id on web.

Takes a boolean – defaults to true.

sessionContext: Attach the client session context to all events. The client session context contains session ID and session index, which can be used to aggregate events to session level in modeling. This context also contains tracker-generated UUID for user identification. This UUID is generated on install of the app.

Takes a boolean – defaults to true.

foregroundTimeout: Where sessionContext is enabled, configure the period of inactivity while the app is in the foreground before a new session (ie a new session ID) is created.

Takes an integer value, indicating number of seconds. Defaults to 600 (ten minutes).

backgroundTimeout: Where sessionContext is enabled, configure the period of inactivity while the app is in the background before a new session (ie a new session ID) is created.

Takes an integer value, indicating number of seconds. Defaults to 300 (five minutes).

checkInterval: Where sessionContext is enabled, configure the frequency with which the tracker performs a check for whether or not the foreground or background timeout has elapsed.

Takes an integer value, indicating number of seconds. Defaults to 15.

lifecycleEvents: Track app lifecycle events, such as foreground and background events.

Takes a boolean – defaults to false.

installTracking: Track app install events.

Takes a boolean – defaults to false.

Setting the Subject

The subject is a persistent object containing global data that applies to all events, such as a manually set userId. Set the subject data using the setSubjectData() method. All parameters are optional.

setSubjectData({ userId: 'my-user-id', screenWidth: 123, screenHeight: 456, colorDepth: 20, timezone: 'Europe/London', language: 'en', ipAddress: '123.45.67.89', useragent: '[some-user-agent-string]', networkUserId: '5d79770b-015b-4af8-8c91-b2ed6faf4b1e', domainUserId: '5d79770b-015b-4af8-8c91-b2ed6faf4b1e', viewportWidth: 123, viewportHeight: 456 });

userId: Manually defined userId. Commonly used for user self-identification – for example after sign in. To unset the userid, pass a null value to this argument.

Takes a string.

screenWidth: Overwrites the dvce_screenwidth field. Must be accompanied by screenHeight.

Takes an integer.

screenHeight: Overwrites the dvce_screenheight field. Must be accompanied by screenWidth.

Takes an integer.

viewportWidth: Overwrites the br_viewwidth field. Must be accompanied by viewportHeight.

Takes an integer.

viewportHeight: Overwrites the br_viewheight field. Must be accompanied by viewportWidth.

Takes an integer.

colorDepth: Populates the br_colordepth field.

Takes an integer.

timezone: Overwrites the os_timezone field. Should contain a valid database timezone code.

Takes a string.

language: Overwrites the br_lang field. Should contain a valid ISO standard language code.

Takes a string

ipAddress: Overwrites the user_ipaddress field. Should contain a valid IP address.

Takes a string.

useragent: Overwrites the useragent field. Should be a valid useragent string.

Takes a string.

networkUserId: Populates the network_userid field. Typically used to link native tracking to in-app browser events tracked using the javascript Normally one would retrieve the network userid from the browser and pass it to the app. Should contain a valid UUID4 string.

Takes a string.

domainUserId: Populates the domain_userid field. Typically used to link native tracking to in-app browser events tracked using the javascript Normally one would retrieve the domain userid from the browser and pass it to the app. Should contain a valid UUID4 string.

Takes a string.

Tracking Methods

Screen View Tracking

Track a screen view with the trackScreenViewEvent() method. Screen view events will auotomatically be populated with a screen view ID (UUID4), which increments each time a new screen view event fires. This id is also attached to the screen view context if enabled, which enables users to tie screen view events to all other events which happen on the screen, and to aggregate data per screen view.

trackScreenViewEvent({ screenName: 'my-screen', screenType: 'my-type', transitionType: 'my-transition'});

Required properties

screenName: Developer-defined screen name.

Takes a string.

Optional properties

screenType: Developer-defined screen type.

Takes a string.

transitionType: Developer-defined transition type.

Takes a string.

To attach custom contexts, pass argument to the function, containing an array of self-describing JSON.

trackScreenViewEvent({ screenName: 'myScreenName'}, [{ schema: 'iglu:com.acme/example_entity/jsonschema/1-0-0', data: {someExampleField: 'Foo Bar Baz'} }] )

Custom event tracking

Track Custom events using the trackSelfDescribingEvent() method.

trackSelfDescribingEvent({ schema: 'iglu:com.acme/example/jsonschema/1-0-0', data: {someExampleField: 'Hello World'} });

Required properties:

schema: 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}.

Takes a string.

data: 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.

Takes a JSON.

To attach custom contexts, pass argument to the function, containing an array of self-describing JSON.

trackSelfDescribingEvent({ schema: 'iglu:com.acme/example_event/jsonschema/1-0-0', data: {someExampleField: 'Hello World'} }, [{ schema: 'iglu:com.acme/example_entity/jsonschema/1-0-0', data: {someOtherExampleField: 'Foo Bar Baz'} }] );

Structured event tracking

Track a structured event with the trackStructuredEvent() method.

trackStructuredEvent({ category: 'my-category', action: 'my-action', label: 'my-label', property: 'my-property', value: 50.00 });

Required properties

category: Structured event category.

Takes a string.

action: Structured event action.

Takes a string.

Optional properties

label: Structured event label.

Takes a string.

property: Structured event property.

Takes a string.

value: Structured event value.

Takes a number.

To attach custom contexts, pass argument to the function, containing an array of self-describing JSON.

trackStructuredEvent({ category: 'my-category', action: 'my-action', label: 'my-label', property: 'my-property', value: 50.00 }, [{ schema: 'iglu:com.acme/example_entity/jsonschema/1-0-0', data: {someOtherExampleField: 'Foo Bar Baz'} }] );

Page View Tracking

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.

trackPageViewEvent({ pageUrl: 'https://my-url.com', pageTitle: 'My page title', pageReferrer: 'http://some-other-url.com'});

Required properties

pageUrl: Page Url for the page view event. Must be a vaild url string.

Takes a string.

Optional properties

pageTitle: Page Title for the page view event.

Takes a string.

pageReferrer: Url for the referring page to the page view event. Must be a vaild url string.

Takes a string.

Data Modelling

Important features for Data Modelling

For most use cases, the recommended setup is to enable at least the session context, screen context, and platform context. These will enable most of the common information in modeling mobile events in a standard way.

initialize({ endpoint: 'my-endpoint.com', namespace: 'my-namespace', appId: 'my-app-id', platformContext: true, screenContext: true, sessionContext: true } );

User identification

The session context contains a UUID format userid, which is generated on app install. This can be used to easily identify individual installations of the app. If it is necessary to handle cases where users share an app, or uninstall/reinstall an app, this ID should be supplemented with additional logic.

The setSubjectData() method offers the ability to set or unset a custom userid. This is typically used to track logged in users, and can be used to handle cases of multiple users. Normally this self-identified user id is treated as the primary identifier, and modeling logic stitches across the other ids to give this one priority.

The platform context will contain the device and advertising identifiers, if the app has permission to track this.

Where an app contains an embedded browser, typically in-app events are tracked using the Javascript tracker, and cookie values are passed to the application. The setSubjectData() method offers the ability to set these fields.

Aggregation

To follow a similar model of aggregation to that of a web model, one can:

  • aggregate to screen view level using the screen view ID from the screen view context
  • aggregate to the session level the session id from the client session context
  • aggregate to a user level the user_id from the client session context.

The screen view and session context is attached to all events and so these can be used to attribute events to their screen views and sessions.

These contexts also contain identifiers for the previous screens and sessions, to facilitate easier user journey mapping.

The session context contains the first event id for the session in order to make it easier to identify the start time for a given session.