Snowplow React Native Tracker 0.2.0 released

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

Version 0.2.0 has ported the React Native Tracker to TypeScript in order to publish accurate types and to make it easier for TypeScript users to integrate it with their React Native apps. 

In addition, the asynchronous nature of the native calls is now managed internally, so that users don’t need to handle themselves.

This release introduces a breaking API change, which we detail in the “Migrating from v0.1.x” section below, and also includes some under-the-hood changes, paving the way for v1.

Read on below for:

1. New API
2. Port to TypeScript
3. Handling asynchronous issues internally
4. Migrating from v0.1.x
5. Documentation and help

1. New API

With release 0.2.0, the tracker is now created using the createTracker function, which is a breaking change from v0.1.x. This function accepts 2 arguments:

1. The tracker namespace
2. The tracker configuration object

For example, to initialize the tracker:

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

const tracker = createTracker('my-tracker-namespace', {
  endpoint: 'my-endpoint.com',
  appId: 'my-app-id'
});

For details on the tracker configuration option, you can also read more here.

Then, in your React Native app you can use the tracking methods to track the behavior of your users.

For example:

tracker.trackScreenViewEvent({
  screenName: 'initial-screen',
  screenType: 'carousel'
});

2. Port to TypeScript

TypeScript users can now integrate the Snowplow React Native Tracker easily to their apps using the types published (see also issue 115). These types are namely:

1. ReactNativeTracker
2. TrackerConfig
3. SubjectData
4. ScreenViewProps
5. SelfDescribingProps
6. StructuredProps
7. PageViewProps
8. EventContext
9. HttpMethod
10. HttpProtocol

For example:

import {
  createTracker,
  TrackerConfig,
  ScreenViewProps,
  SubjectData
} from '@snowplow/react-native-tracker';

const myTrackerConfig: TrackerConfig = {
  endpoint: 'my-endpoint',
  appId: 'my-app-id',
  method: 'post',
  protocol: 'http'
};
const tracker = createTracker('sp1', myTrackerConfig);

const testSubject: SubjectData = {
  userId: 'test-userId',
  useragent: 'some-user-agent-string'
};
tracker.setSubjectData(testSubject);

const firstScreenView: ScreenViewProps = {screenName: 'best-screen'};
tracker.trackScreenViewEvent(firstScreenView);

3. Handling async issues internally

The React Native Tracker is based upon the Mobile Native Snowplow trackers, which are imported as native modules. Due to the asynchronous nature of the native calls, it is essential that, for example, a tracking method is called after the tracker is initialized.

Versions prior to v0.2.0, were already providing a Promises API to guard against asynchronous issues, but the users had themselves to await the asynchronous tracker initialization (see also: issue 78). The v0.2.0 release builds upon the Promises API to manage the async issues internally: The tracker initialization does not return a Promise anymore, but a concrete tracker object that needs not be awaited in order to call its tracking methods.

4. Migrating from v0.1.x

In the previous 0.1.x releases, initializing the tracker was done differently. If you are migrating from those versions, you only need to take into account that:

1. The previous Tracker class has been removed. Instead of Tracker.initialize, use the createTracker function instead.
2. The tracker namespace is now a required initialization parameter outside the tracker configuration object.
3. In v0.2.0 there is no need to await tracker initialization, since async issues are now handled internally.
4. The track.. methods are now properties of the tracker object instead of static class methods.

As a quick migration example:

Previous API (v0.1.x)

import Tracker from '@snowplow/react-native-tracker';                       // (1)

const initPromise = Tracker.initialize({                                    // (2)
  endpoint: 'my-endpoint.com',
  namespace: 'my-namespace',
  appId: 'my-app-id'
});
initPromise                                                                 // (3)
  .then(() => Tracker.trackScreenViewEvent({screenName: 'myScreenName'}));  // (4)

Current API (v0.2.0)

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

const tracker = createTracker('namespace', {
  endpoint: 'my-endpoint.com',
  appId: 'my-app-id'
});
tracker.trackScreenViewEvent({screenName: 'myScreenName'});

5. 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 welcome – if you have identified a bug, please log an issue on GitHub.