Quick start guide

In order to start sending events using the Snowplow React Native Tracker, the following steps are involved:

Installation

To install the tracker, add it as a dependency to your React Native app:

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

You will also need to add the FMDB dependency to you ios/Podfile (unless using Expo Go) with modular_headers enabled. Add this line to the end of the file:

pod 'FMDB', :modular_headers => true

Instrumentation

Next, in your app create a new tracker using the createTracker method. As a minimal example:

import { createTracker } from '@snowplow/react-native-tracker';

const tracker = createTracker(
    'appTracker',
    {
      endpoint: COLLECTOR_URL,
    },
);

The createTracker function takes as arguments:

1. Required: The tracker namespace, which identifies each tracker
2. Required: The Network configuration
3. Optional: The Tracker Controller configuration

The optional Tracker Controller configuration has as type definition:

interface TrackerControllerConfiguration {
  trackerConfig?: TrackerConfiguration,
  sessionConfig?: SessionConfiguration,
  emitterConfig?: EmitterConfiguration,
  subjectConfig?: SubjectConfiguration,
  gdprConfig?: GdprConfiguration,
  gcConfig?: GCConfiguration
}

In other words, it provides a way for a fine grained tracker configuration.

As an example to create a tracker with all configurations provided (wherever applicable, the default values are shown):

const tracker = createTracker(
    'appTracker',
    {
      endpoint: COLLECTOR_URL,
      method: 'post',
      customPostPath: 'com.snowplowanalytics.snowplow/tp2', // A custom path which will be added to the endpoint URL to specify the complete URL of the collector when paired with the POST method.
      requestHeaders: {} // Custom headers for HTTP requests to the Collector
    },
    {
        trackerConfig: {
            appId: 'my-app-id',
            devicePlatform: 'mob',
            base64Encoding: true,
            logLevel: 'off',
            applicationContext: true,
            platformContext: true,
            geoLocationContext: false,
            sessionContext: true,
            deepLinkContext: true,
            screenContext: true,
            screenViewAutotracking: true,
            lifecycleAutotracking: false,
            installAutotracking: true,
            exceptionAutotracking: true,
            diagnosticAutotracking: false,
            userAnonymisation: false // Whether to anonymise client-side user identifiers in session and platform context entities
        },
        sessionConfig: {
            foregroundTimeout: 1800,
            backgroundTimeout: 1800
        },
        emitterConfig: {
            bufferOption: 'single',
            emitRange: 150,
            threadPoolSize: 15,
            byteLimitPost: 40000,
            byteLimitGet: 40000,
            serverAnonymisation: false // Whether to anonymise server-side user identifiers including the `network_userid` and `user_ipaddress`
        },
        subjectConfig: {
            userId: 'my-user-id',
            networkUserId: '5d79770b-015b-4af8-8c91-b2ed6faf4b1e',
            domainUserId: '7cdd5ea8-b0f5-47ea-a8bb-5ec8e98cdbd6',
            useragent: 'some-useragent-string',
            ipAddress: '123.45.67.89',
            timezone: 'Europe/London',
            language: 'en',
            screenResolution: [123, 456],
            screenViewport: [123, 456],
            colorDepth: 20
        },
        gdprConfig: {
            basisForProcessing: 'consent',
            documentId: 'my-gdpr-doc-id',
            documentVersion: '1.0.0',
            documentDescription: 'my gdpr document description'
        },
        gcConfig: [
            {
                tag: 'my-first-gc-tag',
                globalContexts: [
                    {
                        schema: 'my-gc-schema-01',
                        data: {gcData: 'some data'}
                    },
                    {
                        schema: 'my-gc-schema-02'
                        data: {moreGCData: 'some more data'}
                    },
                ]
            },
            {
                tag: 'another-gc-tag',
                globalContexts: [
                    {
                        schema: 'my-gc-schema-03'
                        data: {gcProp: 'some value'}
                    },
                ]
            }
        ]
    }
);

Track events

Once the tracker is initialized, you can use the tracker methods to track events, about which you can find out more in the following Tracking events section.