Snowplow Android and iOS Trackers v3.1 released

We are pleased to announce the release of our mobile trackers: Snowplow iOS Tracker and Android Tracker version 3.1.

This version brings improvements to the session management and a feature that lets the user stop the tracker to emit events.

Callback to inform when the session is renewed

When client session tracking is enabled the tracker appends a client_session context to each event it sends and it maintains this session information as long as the application is installed on the device.

Sessions correspond to tracked user activity. A session expires when no tracking events have occurred for the amount of time defined in a timeout (by default 30 minutes). The session timeout check is executed for each event tracked. If the gap between two consecutive events is longer than the timeout the session is renewed. There are two timeouts since a session can timeout in the foreground (foregroundTimeout) while the app is visible or in the background (backgroundTimeout) when the app has been suspended but not closed.

There is a distinction between session renewed and session expired. The session timeout is checked for each tracked event, so if there aren’t events tracked, the expiration of the session and relative session update can happen after a time longer than the timeout.

The tracker allows the configuration of a callback to inform the app everytime a new session is created.
This can be configured in the SessionConfiguration and it provides the SessionState where can be accessed all the info already tracked in the SessionContext.

Below an example of where the session callback is used to print out the values of session every time a new session is generated by the tracker:

(Example in Swift language)

...
let sessionConfig = SessionConfiguration()
    .onSessionStateUpdate { session in
        print("SessionState: id: \(session.sessionId) - index: \(session.sessionIndex) - userID: \(session.userId) - firstEventID: \(session.firstEventId)")
    }
...
let tracker = Snowplow.createTracker(namespace: kNamespace, network: networkConfig, configurations: [sessionConfig])

Improved session timeout checking

The lifecycle events (application_foreground and application_background events) have a role in the session expiration. The lifecycle events can be enabled in the TrackerConfiguration enabling lifecycleAutotracking. Once enabled they will be fired automatically when the app moves from foreground state to background state and vice versa.

We noticed that the behaviour of the session timeout checking with the lifecycle events could cause bad interpretation of the session in some edge cases.
We can take this configuration (background timeout 15 seconds – foreground timeout 1 hour) as an example:

Scenario 1

SessionConfiguration(
        TimeMeasure(360L, TimeUnit.SECONDS),
        TmeMeasure(15L, TimeUnit.SECONDS)
)

Time	Tracked Event	Session timeout used	Session index
0 sec	screen_view event	foreground timeout check	Session 1
3 sec	background event	background timeout check	Session 1
30 sec	foreground event	foreground timeout check	Session 1

The user expects the session to update because the app has been in background more than 15s.
It happens because when the foreground event is tracked the session checks the timeout using the foreground timeout of 60 mins.

Scenario 2

Time	Tracked Event	Session timeout used	Session index
0 sec	screen_view event	foreground timeout check	Session 1
18 sec	background event	background timeout check	Session 2
22 sec	foreground event	foreground timeout check	Session 2

The user doesn’t expect the session to update because the app has been in background less than 15s.
The session is changed because the background event happens at the beginning of the background app state but it checks the session using the background timeout of 15 secs, even if the app has just moved to background state.

This new version corrects this behaviour.

When the app moves from foreground to background the application_background event is fired. If session tracking is enabled, the session context is attached to the event checking the session expiration using the foreground timeout.
When the app moves from background to foreground the application_foreground event is fired. If session tracking is enabled, the session context is attached to the event checking the session expiration using the background timeout.

Doing that the session correctly expires when the app is backgrounded for more than 15 seconds, like in this example:

Time	Tracked Event	Session timeout used	Session index
0 sec	screen_view event	foreground timeout check	Session 1
3 sec	background event	foreground timeout check	Session 1
30 sec	foreground event	background timeout check	Session 2

In the above example the application_foreground event triggers a new session because the time spent on background (without tracked events) is bigger than the background timeout for the session.

Allow pausing of event emission

The tracker has the pause() method on the TrackerController which would allow the app to suspend tracking. This is useful when we want to suspend completely the tracking of events in the app, but there are cases (low bandwidth or low battery) where the developer prefers to allow the tracking of events sending them in a second moment. That should prevent any impact to the core applications functionality without completely stopping the tracking. The tracker didn’t handle this case.

With the new version we added the pause() and resume() methods to EmitterController in order to suspend the emission of events when desired by the app.

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.1 release.

You can find the full release notes on GitHub as Snowplow Android Tracker v3.1 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.