Migrating from v2

Batch SDK v3 is a major release, which introduces breaking changes from 2.x. This guide describes how to update your application when using a previous version.

Upgrading the SDK version


To upgrade from v2 to v3, you need to change the SDK version in your build.gradle:

implementation("com.batch.android:batch-sdk:3.0.0")

Core migration


Compile and Target SDK

Batch SDK v3 now compiles with Android SDK 36 (Android 16 'Baklava').

Even this is not mandatory we recommend you to ensure your project's compileSdk and targetSdk are updated accordingly in your build.gradle file.

build.gradle.kts
android {
  ...
  compileSdk = 36
  ...
  defaultConfig {
    ...
    targetSdk = 36
  }
}

Internal Kotlin Usage

Batch now uses Kotlin (1.9.0) internally. This should not affect your existing Java-based integrations as public APIs remain in Java. However, be aware of this change if you are inspecting the SDK's internals or if you encounter any unexpected behavior related to Kotlin interoperability.

Push migration


Managing notification display

Methods setNotificationsType and getNotificationsType in Batch.Push have been removed.

Please replace their usage with the following methods:

  • Batch.Push.setShowNotifications(show: boolean): Use this to control whether Batch should display push notifications.

  • Batch.Push.shouldShowNotifications(): Use this to check if Batch is configured to show push notifications.

Batch will preserve your previous settings, and shouldShowNotifications() will reflect them.

So, if you were doing something like this in your application :

// Disable notifications
val set = EnumSet.of(PushNotificationType.NONE) 
Batch.Push.setNotificationsType(set)

// or

// Enable notifications
val set = EnumSet.allOf(PushNotificationType::class.java) 
set.remove(PushNotificationType.NONE)
Batch.Push.setNotificationsType(set)

You should now do:

// Disable notifications
Batch.Push.setShowNotifications(false)

// or

// Enable notifications
Batch.Push.setShowNotifications(true)

For more information, please visit the managing notification display section.

Messaging migration


Batch SDK v3 adds compatibility for Mobile Landings with Push v2 which can be created from the Batch Dashboard's drag & drop composer.

In-App Message Interception

The interface Batch.Messaging.LifecycleListener2 has been removed. Please replace its usage with the new Batch.Messaging.InAppInterceptor interface.

Use the method Batch.Messaging.setInAppInterceptor(Batch.Messaging.InAppInterceptor interceptor) to set your custom interceptor.

So if you were doing:

class SampleApplication : Application(), LifecycleListener2 {
    override fun onCreate() {
        super.onCreate()
        // [...]
        Batch.Messaging.setLifecycleListener(this)
    }
    
    override fun onBatchInAppMessageReady(message: BatchInAppMessage): Boolean {
         // Your implementation
    }
}

You should now do:

class SampleApplication : Application(), InAppInterceptor {
    override fun onCreate() {
        super.onCreate()
        // [...]
        Batch.Messaging.setInAppInterceptor(this)
    }
    
    override fun onBatchInAppMessageReady(message: BatchInAppMessage): Boolean {
         // Your custom implementation
    }
}

For more information, please see the In-App messaging manual mode section.

Messaging Lifecycle Listener

The following methods in Batch.Messaging.LifecycleListener have been removed:

  • onBatchMessageCancelledByAutoclose

  • onBatchMessageCancelledByUser

  • onBatchMessageCancelledByError

  • onBatchMessageWebViewActionTriggered

Please update your implementation to use the new onBatchMessageClosed(String messageIdentifier, MessagingCloseReason reason) method. The new MessagingCloseReason enum will provide the context about why the message was closed.

WebView actions will now trigger the updated onBatchMessageActionTriggered method, with the analyticsID of the action being passed as the ctaIdentifier.

The index (Int) parameter in onBatchMessageActionTriggered has been replaced by ctaIdentifier (String). The method signature is now:

onBatchMessageActionTriggered(String messageIdentifier, String ctaIdentifier, BatchMessagAction actions)

The constant GLOBAL_TAP_ACTION_INDEX now returns a String instead of an int. Update any comparisons or usage accordingly.

So if you were doing:

class SampleApplication : Application(), Batch.Messaging.LifecycleListener {
    
    override fun onCreate() {
        super.onCreate()
        Batch.Messaging.setLifecycleListener(this)
    }
    
    override fun onBatchMessageShown(messageIdentifier: String?) {
        Log.i("App", "onBatchMessageShown $messageIdentifier")
    }
  
    override fun onBatchMessageActionTriggered(
        messageIdentifier: String?,
        index: Int,
        action: BatchMessageAction
    ) {
        Log.i("App", "onBatchMessageActionTriggered $messageIdentifier")
    }
    
    override fun onBatchMessageWebViewActionTriggered(
        messageIdentifier: String?,
        analyticsID: String,
        action: BatchMessageAction
    ) {
        Log.i("App", "onBatchMessageWebViewActionTriggered $messageIdentifier")
    }
    
    override fun onBatchMessageCancelledByAutoclose(messageIdentifier: String?) {
        Log.i("App", "onBatchMessageCancelledByAutoclose $messageIdentifier")
    }
    
    override fun onBatchMessageCancelledByUser(messageIdentifier: String?) {
        Log.i("App", "onBatchMessageCancelledByUser $messageIdentifier")
    }
    
    override fun onBatchMessageCancelledByError(messageIdentifier: String?) {
        Log.i("App", "onBatchMessageCancelledByUser $messageIdentifier")
    }
    
    override fun onBatchMessageClosed(messageIdentifier: String?) {
        Log.i("App", "onBatchMessageClosed $messageIdentifier")
    }
}

You should now do:

class SampleApplication : Application(), Batch.Messaging.LifecycleListener {
    
    override fun onCreate() {
        super.onCreate()
        Batch.Messaging.setLifecycleListener(this)
    }
    
    override fun onBatchMessageShown(messageIdentifier: String?) {
        Log.i("App", "onBatchMessageShown $messageIdentifier")
    }

    
    override fun onBatchMessageActionTriggered(
        messageIdentifier: String?,
        ctaIdentifier: String?,
        action: BatchMessageAction
    ) {
        Log.i("App", "onBatchMessageActionTriggered $messageIdentifier")
        //For MEP messages, ctaIdentifier might be "mepCtaIndex:0", "mepCtaIndex:1", etc.
    }
    
    override fun onBatchMessageClosed(
        messageIdentifier: String?,
        reason: Batch.Messaging.LifecycleListener.MessagingCloseReason?
    ) {
        Log.i("BatchSample", "onBatchMessageClosed $messageIdentifier with reason $reason")
        when(reason) {
            MessagingCloseReason.Auto -> Log.i("App",
                "onBatchMessageCancelledByAutoclose $messageIdentifier"
            )
            MessagingCloseReason.User -> Log.i("App",
                "onBatchMessageCancelledByUser $messageIdentifier"
            )
            MessagingCloseReason.Action -> Log.i("App",
                "onBatchMessageCancelledByAction $messageIdentifier"
            )
            MessagingCloseReason.Error -> Log.i("App",
                "onBatchMessageCancelledByError $messageIdentifier"
            )
        }
    }
}

For more information, please see the listening lifecycle event section.

Manual display mode

The messaging manual display mode has been reworked to better fit Mobile Landing on Push v2.

What's changed:

  • The enum Format and the method getFormat() in BatchMessage have been removed.

  • The methods loadFragment() and loadBanner() in Batch.Messaging have been removed.

  • The class BatchBannerView has been removed.

You should now use the new method Batch.Messaging.loadMessagingView(Context context, BatchMessage message) to load messages.

This method will returns an instance of BatchMessagingView which according to the kind property allows you to use the right method to display it.

So if you were doing something like:

try {
    val message = pushPayload.getLandingMessage()
    when (message.format) {
        BatchMessage.Format.BANNER -> Batch.Messaging.loadBanner(this, message).show(this)
        else -> Batch.Messaging.loadFragment(this, message).show(supportFragmentManager, "batch-landing")
    }
} catch (e: BatchMessagingException) {
    e.printStackTrace()
}

You should now do:

try {
    val message = pushPayload.getLandingMessage()
    val messagingView = Batch.Messaging.loadMessagingView(this, message)
    when (messagingView.kind) {
        BatchMessagingView.Kind.Fragment -> messagingView.showFragment(supportFragmentManager, "batch-landing")
        BatchMessagingView.Kind.View -> messagingView.showView(this)
    }
    return
} catch (e: BatchMessagingException) {
    e.printStackTrace()
}

For more information, please visit the Mobile Landing manual mode section.


To see in details what's precisely changed since V2 please consult our changelog or visit the APIs Reference.

Last updated

Was this helpful?