Migrate from an earlier version

This page details breaking changes from previous versions, so you understand the development effort required to update your app and take advantage of the latest features.


We try to limit breaking or significant changes to major version increments. The three digits in our versioning scheme represent major, minor, and patch increments respectively.

sdk versioning scheme
sdk versioning scheme
  • Major: may include breaking changes, and generally introduces significant feature updates.
  • Minor: may include new features and fixes, but won’t include breaking changes. You may still need to do some development to use new features in your app.
  • Patch: Increments represent minor fixes that should not require development effort.

Upgrade from 2.x to 3.x

Android 12 changes the way the operating system resolves deep links. We’ve resolved the issue in our 3.x release, involving the following behavioral changes.

If your app is open or you send a data notification with a non-app link:

  • Android 12 or later: Your notification will launch the host app first, and then a matching app on top of it.
  • Android 11 or earlier: Your notification will launch the matching app without launching the host app.

By default, you You can now disable the ability to open links outside the app from your SDK configuration.

CustomerIOPushNotificationCallback replaces CustomerIOUrlHandler

The new CustomerIOPushNotificationCallback class handles deep links with Android 12 or later that otherwise would not have worked with the previous CustomerIOUrlHandler class.

The ModuleMessagingPushFCM now has a config object that contains this notificationCallback and an optional redirectDeepLinksToOtherApps boolean (defaults to true).

class MainApplication : Application(), CustomerIOPushNotificationCallback {

    override fun onCreate() {
        val builder = CustomerIO.Builder(
            siteId = "YOUR-SITE-ID",
            apiKey = "YOUR-API-KEY",
            appContext = this
                    config = MessagingPushModuleConfig.Builder().apply {

    override fun createTaskStackFromPayload(
        context: Context,
        payload: CustomerIOParsedPushPayload
    ): TaskStackBuilder? {
        // return TaskStackBuilder of your choice if you plan to handle the deep link yourself
        // return null if you want CustomerIO SDK to do it for you
        TODO("Pass the link to your Deep link managers")

Upgrade from 1.x to 2.x

Remove .enqueue()

The Android SDK 2.0 release introduces a queue system, making it easier to integrate with the SDK.

All of the SDK functions that previously required a .enqueue() call, no longer do. Simply delete that code in your app to migrate to using the queue.

// Before
CustomerIO.instance().track(...).enqueue {...}
// After

This impacts the following functions:

  • CustomerIO.instance().identify(...)
  • CustomerIO.instance().track(...)
  • CustomerIO.instance().screen(...)
  • CustomerIO.instance().registerDeviceToken(...)
  • CustomerIO.instance().deleteDeviceToken(...)
  • CustomerIO.instance().trackMetric(...)

If you use the optional FCM Push notification SDK, you’ll also benefit from the queue.

// Before
CustomerIOFirebaseMessagingService.onMessageReceived(context, remoteMessage, errorCallback = { ... })
// After 
CustomerIOFirebaseMessagingService.onMessageReceived(context, remoteMessage)

// Before
CustomerIOFirebaseMessagingService.onNewToken(token) { ... }
// After 

Initialize optional SDKs

To keep your app size as small as possible, the Customer.io SDK is broken up into optional SDKs that you install only when you need them. In version 1.0, you only needed to install a dependency with Gradle to use an optional SDK.

Version 2.0 introduces a breaking change that requires you to initialize optional SDKs after you install them via Gradle.

For example, if you have the optional FCM Push notifications SDK installed, you need to add 1 new line to the CustomerIO.Builder:

// Before 

// After

The FCM Push notifications SDK is the currently only optional SDK module. When we release additional SDKs in the future, you can expect to initialize these SDKs as well.

Copied to clipboard!
Current release
Is this page helpful?