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
⚠️ Batch SDK 3.0 now requires Xcode 16.3 and iOS 15.0 or higher.
To upgrade from v2 to v3, you need to change the SDK version according to your package manager:
Update by using the "update package" option from Xcode or updating your package.swift
.
Copy . package ( url : "https://github.com/BatchLabs/Batch-iOS-SDK" , from : "3.0.1" )
Update your Podfile
as following and run pod update
.
Copy pod 'Batch', ' ~> 3.0 '
Update your Cartfile
if necessary and run carthage update Batch
.
Copy github "BatchLabs/Batch-iOS-SDK" ~> 3.0
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 method batchInAppMessageReady
has been removed from the BatchMessagingDelegate
protocol. Please replace its usage with the new BatchInAppDelegate
protocol.
Use the property access BatchMessaging.inAppDelegate
to set your custom delegate.
So if you were doing:
Copy // Application delegate
var inAppMsgDelegate = InAppMsgDelegate ()
func application ( _ application : UIApplication, didFinishLaunchingWithOptions launchOptions : [UIApplicationLaunchOptionsKey : Any ] ? ) -> Bool {
BatchMessaging.delegate = inAppMsgDelegate
}
// InAppMsgDelegate implementation
@objc
class InAppMsgDelegate : NSObject , BatchMessagingDelegate {
func batchInAppMessageReady ( message : BatchInAppMessage) {
// Your implementation
}
}
Copy // Application delegate
@property InAppMsgDelegate *inAppMsgDelegate
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
self.inAppMsgDelegate = [InAppMsgDelegate new];
BatchMessaging.delegate = self.inAppMsgDelegate;
}
// InAppMsgDelegate implementation
@interface InAppMsgDelegate : NSObject <BatchMessagingDelegate>
@end
@implementation InAppMsgDelegate
- (void)batchInAppMessageReady:(nonnull BatchInAppMessage*)message
{
// Your implementation
}
@end
You should now do:
Copy // Application delegate
var inAppMsgDelegate = InAppMsgDelegate()
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
BatchMessaging.inAppDelegate = inAppMsgDelegate
}
// InAppMsgDelegate implementation
@objc
class InAppMsgDelegate: NSObject, BatchInAppDelegate {
func batchInAppMessageReady(message: BatchInAppMessage) {
// Your implementation
}
}
Copy // Application delegate
@property InAppMsgDelegate *inAppMsgDelegate
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
self.inAppMsgDelegate = [InAppMsgDelegate new];
BatchMessaging.inAppDelegate = self.inAppMsgDelegate;
}
// InAppMsgDelegate implementation
@interface InAppMsgDelegate : NSObject <BatchInAppDelegate>
@end
@implementation InAppMsgDelegate
- (void)batchInAppMessageReady:(nonnull BatchInAppMessage*)message
{
// Your implementation
}
@end
For more information, please see the In-App messaging manual mode section.
Messaging Delegate
The following methods in BatchMessagingDelegate
have been removed:
batchMessageWasCancelledByAutoclose
batchMessageWasCancelledByUserAction
batchMessageWasCancelledByError
batchWebViewMessageDidTriggerAction
Please update your implementation to use the batchMessageDidDisappear:(NSString *_Nullable)messageIdentifier reason:(BatchMessagingCloseReason)reason;
method. The new BatchMessagingCloseReason
enum will provide the context about why the message was closed.
WebView actions will now trigger the updated batchMessageDidTriggerAction
method, with the analyticsID
of the action being passed as the ctaIdentifier
.
The index
(NSInteger) parameter in batchMessageDidTriggerAction
has been replaced by ctaIdentifier
(NSString). The method signature is now
Copy batchMessageDidTriggerAction:(BatchMessageAction *_Nonnull)action
messageIdentifier:(NSString *_Nullable)identifier
ctaIdentifier:(NSString *_Nonnull)ctaIdentifier;
For older MEP (Mobile Engagement Platform) messages, ctaIdentifier
will be a string in the format "mepCtaIndex:" + index
.
The constant BatchMessageGlobalActionIndex
now returns a NSString instead of an NSInteger. Update any comparisons or usage accordingly.
So if you were doing:
Copy // Application delegate
var messagingDelegate = MsgDelegate()
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
BatchMessaging.delegate = inAppMsgDelegate
}
// BatchMessagingDelegate implementation
class SampleBatchMessagingDelegate: NSObject, BatchMessagingDelegate {
public func batchMessageDidAppear(messageIdentifier: String?) {
print("SampleBatchMessagingDelegate - batchMessageDidAppear: \(messageIdentifier)")
}
public func batchMessageDidTriggerAction(_ action: BatchMessageAction, messageIdentifier identifier: String?, actionIndex index: Int) {
print("SampleBatchMessagingDelegate - batchMessageDidTriggerAction: \(messageIdentifier)")
}
public func batchWebViewMessageDidTriggerAction(_ action: BatchMessageAction?, messageIdentifier: String?, analyticsIdentifier: String?) {
print("SampleBatchMessagingDelegate - batchWebViewMessageDidTriggerAction \(String(describing:action)), tracking ID: \(messageIdentifier ?? "<nil>"), analyticsIdentifier: \(analyticsIdentifier ?? "<nil>")")
}
public func batchMessageWasCancelledByAutoclose(_ messageIdentifier: String?) {
print("SampleBatchMessagingDelegate - batchMessageWasCancelledByAutoclose: \(messageIdentifier)")
}
public func batchMessageWasCancelledByUserAction(_ messageIdentifier: String?) {
print("SampleBatchMessagingDelegate - batchMessageWasCancelledByUserAction: \(messageIdentifier)")
}
public func batchMessageWasCancelledByError(_ messageIdentifier: String?) {
print("SampleBatchMessagingDelegate - batchMessageWasCancelledByError: \(messageIdentifier)")
}
public func batchMessageDidDisappear(messageIdentifier: String?) {
print("SampleBatchMessagingDelegate - batchMessageDidDisappear: \(messageIdentifier)")
}
}
Copy // AppDelegate.m
@property SampleBatchMessagingDelegate *messagingDelegate
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
self.messagingDelegate = [SampleBatchMessagingDelegate new];
BatchMessaging.delegate = self.messagingDelegate;
}
// Header file (.h)
@interface SampleBatchMessagingDelegate : NSObject <BatchMessagingDelegate>
@end
// Implementation file (.m)
@implementation SampleBatchMessagingDelegate
- (void)batchMessageDidAppear:(NSString* _Nullable)messageIdentifier
{
NSLog(@"SampleBatchMessagingDelegate - batchMessageDidAppear: %@", messageIdentifier);
}
- (void)batchMessageDidTriggerAction:(BatchMessageAction * _Nonnull)action messageIdentifier:(NSString *)identifier actionIndex:(NSInteger)index
{
NSLog(@"SampleBatchMessagingDelegate - batchMessageDidTriggerAction: %@", messageIdentifier);
}
- (void)batchWebViewMessageDidTriggerAction:(BatchMessageAction * _Nonnull)action messageIdentifier:(NSString *)identifier analyticsIdentifier:(NSString *)analyticsIdentifierex
{
NSLog(@"SampleBatchMessagingDelegate - batchWebViewMessageDidTriggerAction: %@", messageIdentifier);
}
- (void)batchMessageWasCancelledByAutoclose:(NSString * _Nullable)messageIdentifier
{
NSLog(@"SampleBatchMessagingDelegate - batchWebVbatchMessageWasCancelledByAutocloseiewMessageDidTriggerAction: %@", messageIdentifier);
}
- (void)batchMessageWasCancelledByUserAction:(NSString * _Nullable)messageIdentifier
{
NSLog(@"SampleBatchMessagingDelegate - batchMessageWasCancelledByUserAction: %@", messageIdentifier);
}
- (void)batchMessageDidDisappear:(NSString* _Nullable)messageIdentifier
{
NSLog(@"SampleBatchMessagingDelegate - batchMessageDidDisappear: %@", messageIdentifier);
}
@end
You should now do:
Copy // Application delegate
var messagingDelegate = MsgDelegate()
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
BatchMessaging.delegate = messagingDelegate
}
// BatchMessagingDelegate implementation
class SampleBatchMessagingDelegate: NSObject, BatchMessagingDelegate {
public func batchMessageDidAppear(messageIdentifier: String?) {
print("SampleBatchMessagingDelegate - batchMessageDidAppear: \(messageIdentifier)")
}
public func batchMessageDidTriggerAction(_ action: BatchMessageAction, messageIdentifier identifier: String?, ctaIdentifier: String) {
print("SampleBatchMessagingDelegate - batchMessageDidTriggerAction: \(messageIdentifier)")
// For MEP messages, ctaIdentifier might be "mepCtaIndex:0", "mepCtaIndex:1", etc.
}
public func batchMessageDidDisappear(_ messageIdentifier: String?, reason: BatchMessagingCloseReason) {
switch(reason) {
case .action:
print("SampleBatchMessagingDelegate - batchMessageDidDisappear: \(messageIdentifier)")
case .auto:
print("SampleBatchMessagingDelegate - batchMessageWasCancelledByAutoclose: \(messageIdentifier)")
case .user:
print("SampleBatchMessagingDelegate - batchMessageWasCancelledByUserAction: \(messageIdentifier)")
case .error:
print("SampleBatchMessagingDelegate - batchMessageWasCancelledByError: \(messageIdentifier)")
}
}
}
Copy // AppDelegate.m
@property SampleBatchMessagingDelegate *messagingDelegate
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
self.messagingDelegate = [SampleBatchMessagingDelegate new];
BatchMessaging.delegate = self.messagingDelegate;
}
// Header file (.h)
@interface SampleBatchMessagingDelegate : NSObject <BatchMessagingDelegate>
@end
// Implementation file (.m)
@implementation SampleBatchMessagingDelegate
- (void)batchMessageDidAppear:(NSString* _Nullable)messageIdentifier
{
NSLog(@"SampleBatchMessagingDelegate - batchMessageDidAppear: %@", messageIdentifier);
}
- (void)batchMessageDidTriggerAction:(BatchMessageAction * _Nonnull)action messageIdentifier:(NSString *)identifier ctaIdentifier:(NSString *_Nonnull)ctaIdentifier
{
NSLog(@"SampleBatchMessagingDelegate - batchMessageDidTriggerAction: %@", messageIdentifier);
// For MEP messages, ctaIdentifier might be "mepCtaIndex:0", "mepCtaIndex:1", etc.
}
- (void)batchMessageDidDisappear:(NSString* _Nullable)messageIdentifier reason:(BatchMessagingCloseReason)reason
{
switch (reason) {
case BatchMessagingCloseReasonAction:
NSLog(@"SampleBatchMessagingDelegate - batchMessageDidDisappear: %@", messageIdentifier ?: @"<nil>");
break;
case BatchMessagingCloseReasonAuto:
NSLog(@"SampleBatchMessagingDelegate - batchMessageWasCancelledByAutoclose: %@", messageIdentifier ?: @"<nil>");
break;
case BatchMessagingCloseReasonUser:
NSLog(@"SampleBatchMessagingDelegate - batchMessageWasCancelledByUserAction: %@", messageIdentifier ?: @"<nil>");
break;
case BatchMessagingCloseReasonError:
NSLog(@"SampleBatchMessagingDelegate - batchMessageWasCancelledByError: %@", messageIdentifier ?: @"<nil>");
break;
}
}
@end
For more information, please see the listening lifecycle event section.
To see in details what's precisely changed since V2 please consult our changelog or visit the APIs Reference .