Breaking Changes in Android (Kotlin) SDK 2.0.0

This guide lists the breaking changes in the Android (Kotlin) SDK 2.0.0 and the device mode integrations released with it. Review them before you upgrade from an Android (Kotlin) SDK 1.x version.

Overview

Android (Kotlin) SDK 2.0.0 has the following breaking changes:

• The SDK starts automatic sessions and sends Application Installed or Application Updated when the user first opens the app. Before 2.0.0, it did this when it initialized.
• By default, background events no longer carry sessionId or sessionStart.
• One session configuration parameter has a new name.
• All device mode integrations have a new major version that requires SDK 2.0.0.
• The CleverTap integration requires a newer CleverTap Android SDK and a higher minSdk.

Upgrade the SDK and integrations together

The device mode integrations released with SDK 2.0.0 require SDK 2.0.0 or later. Upgrade the SDK and all integrations in the same app release:

Session tracking

A background event is an event that your app sends while it has no visible screen. Events sent from Application.onCreate before the first screen opens are also background events. A foreground service, for example in a music player, sends background events too.

Parameter renamed

The updateSessionOnBackgroundEvents parameter of SessionConfiguration is now includeBackgroundEventsInSession. The old name no longer exists. Code that uses it does not compile. The default value stays false. Its behavior also changes, as the next sections describe.

// 1.7.0 to 1.8.0
SessionConfiguration(updateSessionOnBackgroundEvents = true)

// 2.0.0 and later
SessionConfiguration(includeBackgroundEventsInSession = true)

// 1.7.0 to 1.8.0
new SessionConfigurationBuilder().setUpdateSessionOnBackgroundEvents(true).build();

// 2.0.0 and later
new SessionConfigurationBuilder().setIncludeBackgroundEventsInSession(true).build();

Sessions start when the user opens the app

Impact: When includeBackgroundEventsInSession is false, a background app start no longer creates a session. Your session count can decrease after the upgrade.

Background events when includeBackgroundEventsInSession is false (default)

These rules apply to automatic sessions. In a manual session, background events carry sessionId as before.

The SDK’s lifecycle events (Application Installed, Application Updated, Application Opened, and Application Backgrounded) carry sessionId in the background. They do not extend the session. The SDK matches these events by name. A track event from your app with one of these names also carries sessionId.

Action: If your app tracks user activity from the background or from a foreground service, set includeBackgroundEventsInSession to true.

Background events when includeBackgroundEventsInSession is true

From 2.0.0, a background event also starts a new session when no session exists. For example, your app can send an event when a push notification arrives. If the user has not opened the app yet, that event starts a session. When the user opens the app within the timeout, the same session continues.

sessionStart can be on any event

The SDK sets context.sessionStart on the first event that carries the ID of a new session. Before 2.0.0, this was usually Application Installed or Application Opened. From 2.0.0, this is more often an app event, for example a background event that starts a session.

Action: Some reports or transformations find new sessions by sessionStart on one event name. Change them to read sessionStart on any event.

See Session Tracking in Mobile SDKs for the full session rules.

Lifecycle events

If a user installs your app and never opens it, the SDK does not send Application Installed. If Android starts the app in the background first, the SDK sends the event later, when the user opens the app.

See Application Lifecycle Tracking in Mobile SDKs for more information.

CleverTap integration

The CleverTap integration 2.0.0 has the following breaking changes:

Note the following:

• If your app declares an older CleverTap Android SDK version, Gradle replaces it with the newest version in the range [8.4.1, 9.0.0).
• If your app pins an older version with strictly, the build fails. Do not force an older version with force.
• If your app calls the CleverTap SDK directly, review the CleverTap Android SDK changelog for the changes up to your new version.
• If your app creates the CleverTap instance itself before RudderStack initializes the destination, for example by calling ActivityLifecycleCallback.register or CleverTapAPI.getDefaultInstance, add your CleverTap credentials to the manifest. Without them, RudderStack cannot create the CleverTap destination.

See CleverTap for the setup steps.

Upgrade checklist

1. Upgrade the SDK and all device mode integrations to the versions in Upgrade the SDK and integrations together.
2. In Kotlin, rename updateSessionOnBackgroundEvents to includeBackgroundEventsInSession. In Java, rename setUpdateSessionOnBackgroundEvents to setIncludeBackgroundEventsInSession.
3. Set includeBackgroundEventsInSession to true if your app tracks user activity from the background or from a foreground service.
4. Review reports and transformations that count sessions, use sessionStart, or expect sessionId on background events.
5. If you use the CleverTap integration, set minSdk to 23 or higher. Then read the notes in CleverTap integration.