Snowplow Android and iOS Trackers v3.0 released

We are pleased to announce the release of our mobile trackers: Snowplow iOS Tracker and Android Tracker version 3.0. This release completes the transition started with the previous major release v2.0, completely removing support for the old v1.0 API.

This new version doesn't introduce breaking changes with the v2.x API. Instead, it enhances the trackers with some new out-of-the-box events and more data points gathered automatically by the tracker.

Read on below for:

1. Enhanced Mobile Platform Context
2. Out-of-the-box DeepLink Event
3. Out-of-the-box MessageNotification Event
4. Lifecycle status entity on each event
5. Deprecated methods and breaking changes
6. Documentation
7. Getting help

Enhanced Mobile Platform Context

Information about mobile devices of users is an important part of analytics and helps understanding your user base, deciding on what types of devices to support, or debugging problems. Previous versions of mobile trackers already sent mobile platform context along with events that described device properties such as OS version, or device manufacturer. This new release significantly expands the range of mobile platform context that is sent.

The new platform context now includes information about memory, storage, and battery usage. Concretely, the new memory information includes total physical system memory on both Android and iOS, currently available system memory on Android, and currently available memory to the app on iOS. Total size of storage and currently remaining storage size is sent as well. Battery usage information contains the currently remaining battery level, and the battery state (charging, full, unplugged). To prevent adding extra computational overhead to each tracked event, this new platform context is never updated more frequently than every 100ms, which we experimentally found does not incur significant overhead.

Out-of-the-box DeepLink event

In the mobile world the Deep Links are urls that link to a specific content directly in a mobile app. Usually they are used to redirect the user from a website or a banner-ad to the installed app instead of another web page. The Deep Links help the user to go straight inside the app to the content they are interested in, similarly to the navigation on the web.

Usually, the Deep Link is received by the mobile operating system and passed to the related app. It's the responsibility of the developer to parse the received deep-link's url and show the right content to the user. The way the Deep Link is used is strongly dependent on the way the app routing is implemented. For this reason, our mobile tracker can't automatically track the Deep Link, but now we provide an out-of-the-box event that can be used by the developer to manually track it as soon as the Deep Link is received in the app.

It will be the duty of the tracker to automatically attach the information of the Deep Link to the first ScreenView tracked.

In practice, when the app receives a Deep Link the developer can track it through the DeepLinkReceived event. For example (in iOS - AppDelegate.swift):

public func application(_ application: UIApplication,
continue userActivity: NSUserActivity,
restorationHandler: @escaping ([Any]?) -> Void) -> Bool
{
...
if let url = userActivity.webpageURL {
let deepLinkEvent = DeepLinkReceived(url: userActivity.webpageURL.absoluteString)
.referrer(userActivity.referrerURL.absoluteString)
tracker.track(deepLinkEvent)
}
...
}


The tracker keeps memory of the tracked Deep Link event and will attach a Deep Link entity to the first ScreenView tracked in the tracker. This is helpful during the analysis of the data because it will be clear the relation between the content visualized by the user (ScreenView event) and source (DeepLink entity) that originated that visualisation.

This behaviour is enabled by default but it can be disabled from the TrackerConfiguration.

For example:

let trackerConfig = TrackerConfiguration()
...
.deepLinkContext(false)
...


The DeepLinkReceived event can be used in pair with a campaign-attribution-enrichment appropriately enabled in the Snowplow pipeline. It works exactly like PageView events in the Snowplow JavaScript Trackers. When the user touch on an advertising banner or a marketing email or message, it can trigger the launch of the app through the Deep Linking feature. The referral from the advertising campaigns, websites, or other source can be composed by UTM parameters used to attribute the user activity back to the campaign. The Campaign Attribution Enrichment can parse the DeepLinkReceived event extracting the UTM parameters in the deep link url.

Out-of-the-box MessageNotification Event

Push Notifications are a cornerstone of the user experience on mobile. A Push Notification is a message (like an SMS or a mobile alert) that can quickly show information to the user even if an app is closed or the phone is in stand-by. Push Notifications can be used in many different ways: they can notify of a new message in a chat, rather than informing of a news or just notify of an achievement in a fitness app.

The Push Notification feature is available on both iOS and Android but the way it can be instrumented in the app can be very different and it's dependent by the app domain and architecture, the platform (iOS or Android), the use of third-party SDKs.

Therefore, our mobile tracker doesn't automatically track the Push Notification received by the app. We provide an out-of-the-box event that can be used by the developer to manually track it as soon as the Push Notification (or local notification) is received in the app.

As said, Push Notification is a complex feature and the information to track can be varied and different between the two platforms. The new version 3.0 of the mobile tracker provides a single out-of-the-box event called MessageNotification that can be filled with all the data composing the received Push Notification.

In practice, when the app receives a Notification the developer can track it through the MessageNotification event. For example (in iOS - AppDelegate.swift):

public func application(_ application: UIApplication,
didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool
{
...
if let userInfo = launchOptions?[.remoteNotification] as? [String: AnyObject] {
event = MessageNotification(userInfo: userInfo, defaultTitle: nil, defaultBody: nil)
tracker.track(event)
}
...
}


It's also possible to pass directly the fields without to relying on userInfo, especially for Android where there aren't convenient methods available. For example (in Android):

MessageNotification event =
new MessageNotification("title", "body", MessageNotificationTrigger.push)
.notificationTimestamp("2020-12-31T15:59:60-08:00")
.action("action")
.bodyLocKey("loc key")
.bodyLocArgs(Arrays.asList("loc arg1", "loc arg2"))
.sound("chime.mp3")
.notificationCount(9)
.category("category1");
tracker.track(event);


Lifecycle status entity on each event

This new release introduces another important feature that can help a lot during the data modelling phase. The mobile trackers have always been able to track lifecycle events automatically. When the app goes background the tracker tracks a background event (application_background) and similarly when the app is resumed again the tracker tracks a foreground event (application_foreground). Unfortunately, on data modelling it can be useful to know if an event has been tracked when the app was in background or in foreground. From this new version 3.0 this information is tracked as an entity attached to all the event tracked.

Version 3.0 comes with an important bugfix for the tvOS platform. Thanks to the contribution of Mike (@miike) from Poplin Data we have fixed the tracker and it's now able to track lifecycle events correctly in the tvOS platform too.

Deprecated methods and breaking changes

In this release we've marked PageView and PushNotification as deprecated. We don't plan to remove them completely but we suggest to evaluate better alternatives that we provide with this new release.

More details about the deprecated events:

• PageView event: this event has been designed for web tracking. Its role can be replaced on mobile with two different events: ScreenView event and DeepLinkReceived event. The first covers the need of tracking the screen visualized to the user by the app. The latter covers the case where the shown content is referred to an external url referral and we want to track that down, exactly like the PageView does in the web tracker.
• PushNotification event: this event is available only on iOS tracker and it's strongly influenced by the format of push notifications in the iOS platform. It has been replaced with MessageNotification which is usable in both iOS and Android trackers v3.0.

In this release there are some breaking changes:

• The v1 API has been removed from this new version of the trackers, which means the v1 components (Tracker, Emitter, Subject, Session) used to set up the tracker are no longer available. If you have already migrated your instrumentation to the v2 API there aren't breaking changes.
• The events can be built using the constructor and builder methods. The builder classes available with v1 are no longer available. If you have already migrated your event building using events constructor suggested with the v2 API there aren't breaking changes.
• Session callbacks have been removed. They will be reintroduced soon in one of the next minor versions. More details will be provided at the release.
• Utilities or Utils methods, available in v1 API, have been removed.

Documentation

As always, information about how to use the tracker can be found in the Mobile Tracker documentation.

You can find the full release notes on GitHub as Snowplow iOS Tracker v3.0 release.

You can find the full release notes on GitHub as Snowplow Android Tracker v3.0 release.

Getting Help

For help on integrating the tracker please have a look at the setup guide. If you have any questions or run into any problems, please visit our Discourse forum. Please raise any bugs in the iOS Tracker’s issues or Android Tracker’s issues on GitHub.