Snowplow React Native Tracker 1.0.0 released

We are very happy to announce the v1 release of the Snowplow React Native Tracker. We detail the changes and new features, along with examples, below.

The v1 release of the React Native Tracker is built on top of Mobile Native Trackers v2 and so inherits their enhanced tracking features and reliability. Therefore, the React Native Tracker v1 can now be similarly configured with a set of configuration objects, using the createTracker function.

This release also introduces an amended v_tracker field, that allows the distinguishing of events tracked by the React Native Tracker in the warehouse.

Finally, under the hood, this release now publishes the sourcemaps and not the precompiled source, fixes the versioning of its Pod and also adds automated end-to-end test workflows using Snowplow Micro and Detox.

Read on below for:

1. Tracker configuration API
2. Additional track methods
3. Setting subject information at runtime
4. Global contexts
5. Session data callbacks
6. Managing multiple trackers
7. Migrating from previous version
8. Documentation and help

1. Tracker configuration API

The new API to configure the tracker mirrors as closely as possible the API of the Mobile Native Trackers v2, in order to provide the same default behavior and automatic tracking features.

Once you import the React Native Tracker module into your app, the createTracker function can be used to set up a tracker, which is identified internally by its namespace and is configured by a set of configuration objects. As also described in the Quick start guide, a user can simply create a tracker by providing a tracker namespace and the collector endpoint as: 

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

const tracker = createTracker(
    'sp1',                          // the tracker namespace
    { endpoint: 'collector-url' }   // the NetworkConfiguration
);

The createTracker function accepts three arguments:

1. The tracker namespace (Required)
2. The Network Configuration (Required)
3. The Tracker Controller Configuration (Optional)

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

const tracker = createTracker(
    ‘sp1’,  // tracker namespace
    { endpoint: ‘my-collector-url.com’ }, // NetworkConfiguration
    {}      // TrackerControllerConfiguration - optional
);

TrackerControllerConfiguration

As mentioned above, the Tracker Controller Configuration is a completely optional argument to createTracker. Where applicable, the default values of its properties match the default values of the Mobile Native Trackers v2, which also cover the prerequisites in order to use the official Snowplow Mobile Data model.

The TrackerControllerConfiguration provides the ability for a fine-grained tracker configuration. Its interface is defined as:

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

Each of its configuration properties is optional and represents a different set of parameters for a fine grained configuration of the React Native Tracker:

1. trackerConfig: TrackerConfiguration

Configures the general behaviour of the tracker. Represents the core tracker properties. The TrackerConfiguration can be used to set up the tracker behaviour indicating what should be tracked in terms of automatic tracking and contexts/entities to attach to the events.

const initTrackerConfig: TrackerConfiguration = {
    appId: 'my-app-id',
    devicePlatform: 'mob',
    base64Encoding: true,
    logLevel: 'off',
    applicationContext: true,
    platformContext: true,
    geoLocationContext: false,
    sessionContext: true,
    screenContext: true,
    screenViewAutotracking: true,
    lifecycleAutotracking: false,
    installAutotracking: true,
    exceptionAutotracking: true,
    diagnosticAutotracking: false
};

2. sessionConfig: SessionConfiguration

Configures the session behaviour. The SessionConfiguration represents the configuration of the Session context which gets attached to each event tracked.

const initSessionConfig: SessionConfiguration = {
    foregroundTimeout: 1800,
    backgroundTimeout: 1800
};

3. emitterConfig: EmitterConfiguration

Configures the way the tracker sends events to the collector. The EmitterConfiguration represents the properties that define the emission behavior of the tracker.

const initEmitterConfig: EmitterConfiguration = {
    bufferOption: 'single',
    emitRange: 150,
    threadPoolSize: 15,
    byteLimitPost: 40000,
    byteLimitGet: 40000
};

4. subjectConfig: SubjectConfiguration

Specifies details to send with events about the user. The SubjectConfiguration represents the basic information of the subject being tracked. 

const initSubjectConfig: SubjectConfiguration = {
    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: 'es',
    screenResolution: [123, 456],
    screenViewport: [123, 456],
    colorDepth: 20
};

5. gdprConfig: GdprConfiguration

Configures the GDPR context. The GdprConfiguration, if set, will determine the information of the gdpr context that will be attached to all events sent by the tracker.

const initGdprConfig: GdprConfiguration = {
    basisForProcessing: 'consent',
    documentId: 'my-gdpr-doc-id',
    documentVersion: '1.0.0',
    documentDescription: 'my gdpr document description'
};

6. gcConfig: GCConfiguration

Configures the GlobalContexts feature and represents the static Global Contexts which will be attached to all events.

const initGlobalContextsConfig: GCConfiguration = [
    {
        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'}
            },
        ]
    }
     ];

So, as a final example, to create a tracker with all the example configurations shown in the examples above:

const tracker = createTracker(
    ‘sp1’,
    { endpoint: 'collector-url' },
    {
        trackerConfig: initTrackerConfig,
        sessionConfig: initSessionConfig,
        emitterConfig: initEmitterConfig,
        subjectConfig: initSubjectConfig,
        gdprConfig: initGdprConfig,
        gcConfig: initGlobalContextsConfig
    }
);

2. Additional track methods

The React Native Tracker provides asynchronous track methods for all the common out-of-the-box mobile events. All track methods accept two arguments:

1. The event data: an object with properties specific to the event being tracked.
2. The event contexts: (optional) an array of custom contexts/entities to be attached to that event.

The available track methods are:

• trackSelfDescribingEvent
• trackStructuredEvent
• trackScreenViewEvent 
• trackPageViewEvent

Additionally, this v1 release introduces:

• trackEcommerceTransactionEvent 
• trackTimingEvent
• trackConsentGrantedEvent
• trackConsentWithdrawnEvent 

As a representative example:

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

You can find more information and examples for all the track methods in the documentation.

3. Setting subject information at runtime

Besides the ability to set subject information on tracker initialization through the subjectConfig property of the TrackerControllerConfiguration, you can also set or change the subject information at runtime, as your user’s journey evolves.

This can be done using the available tracker methods. The React Native Tracker provides a dedicated method for each subject property:

• setUserId
• setNetworkUserId
• setDomainUserId
• setIpAddress
• setUseragent
• setTimezone
• setLanguage
• setScreenResolution
• setScreenViewport
• setColorDepth

In addition, the setSubjectData method is also available that accepts as argument a new SubjectConfiguration and so provides an alternative way to set more than one subject property at once.

For example, you can set a userId and ipAddress:

// either through the respective methods
tracker.setUserId(‘my-new-user’);
tracker.setIpAddress(‘123.45.67.89’);

// or, alternatively
tracker.setSubjectData({
    userId: ‘my-new-user’,
    ipAddress: ‘123.45.67.89’
});

4. Global contexts

Besides the option to set static Global Contexts during tracker initialization through the gcConfig property of the TrackerControllerConfiguration, you can also add or remove Global Contexts at runtime.

To do so, you can use the tracker methods:

• removeGlobalContexts
• addGlobalContexts

Global Contexts are static custom contexts/entities that are attached to all events tracked by the tracker. Each set of Global Contexts is identified by a tag, which is also the only argument needed to remove a set of Global Contexts.

For example:

tracker.removeGlobalContexts('my-first-gc-tag');

Similarly, you can add Global Contexts at runtime. The addGlobalContexts tracker method takes as argument the new global contexts object:

For example:

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

5. Session data callbacks

The React Native tracker allows you to retrieve session data back from the tracker at runtime through callbacks. These callbacks are asynchronous and return a Promise that resolves to the respective value when fulfilled.

The available relevant methods, are:

• getSessionUserId
• getSessionId
• getSessionIndex
• getIsInBackground
• getBackgroundIndex
• getForegroundIndex

For example, to get the current session index, in other words, the index of the current user session:

const sessionIdx = await tracker.getSessionIndex();

For more details and examples, check in the corresponding Docs section here.

6. Managing multiple trackers

The React Native Tracker now provides the ability to run multiple trackers in the same app along with functions to remove a tracker (or all of them) at runtime.

Each tracker is identified by its namespace, which is a required argument to createTracker. The createTracker function can be used to create multiple instances of the tracker in the same app. If you call it using a namespace already used, it will reconfigure the tracker with the same namespace. If you call it with a different namespace, the tracker will create a new independent tracker.

Besides createTracker there are other two functions you can import:

• removeTracker: This function removes an existing tracker at runtime given its namespace.
• removeAllTrackers: This function, that takes no arguments, will remove all existing trackers from your React Native app.

For example:

import { 
    removeTracker, 
    removeAllTrackers 
} from ‘@snowplow/react-native-tracker’;

// assuming a tracker with such namespace already exists
removeTracker(‘my-tracker-namespace’);

// or
removeAllTrackers();

7. Migrating from previous version

If you have instrumented the previous version of the React Native Tracker in your app, there are few steps needed to upgrade to v1, that are documented in this Migration guide.

In short, the two main breaking changes concern:

1. The tracker configuration API
2. The tracker methods that changed, namely trackScreenViewEvent, trackPageViewEvent and setSubjectData

After upgrading, you can also consider taking advantage of the new tracking features available in v1 and enhance your tracking and data modeling design.

8. Documentation and help

Information about how to set up and use the tracker can be found in the React Native Tracker Documentation. If you have any questions or run into any problems, please visit our Discourse forum.

If you are interested in the full release notes, you can find them here.

Feedback and contributions are always welcome – if you have identified a bug, please log an issue on GitHub.