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.
If your application is still using Batch SDK v1 please follow our migration guide from V1 beforehand.
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.
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.
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)
For older MEP (Mobile Engagement Platform) messages, ctaIdentifier
will be a string in the format "mepCtaIndex:" + index
.
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 methodgetFormat()
inBatchMessage
have been removed.The methods
loadFragment()
andloadBanner()
inBatch.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?