Batch 3.0

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:

SPM

Update by using the "update package" option from Xcode or updating your package.swift.

Package.swift

.package(url: "https://github.com/BatchLabs/Batch-iOS-SDK", from: "3.0.1")

CocoaPods

Update your Podfile as following and run pod update.

Podfile

pod 'Batch', '~> 3.0'

Carthage

Update your Cartfile if necessary and run carthage update Batch.

Cartfile

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:

Swift

// 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
    }
}

Objective-C

// 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:

Swift

// 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
    }
}

Objective-C

// 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

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:

Swift

// 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)")
    }
}

Objective-C

// 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:

Swift

// 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)")
        }
    }
}

Objective-C

// 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.