Batch 2.0

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

Upgrading the SDK version

⚠️ Batch SDK 2.0 now requires Xcode 15.3 and iOS 13.0 or higher.

To upgrade from v1 to v2, 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: "2.0.0")

CocoaPods

Update your Podfile as following and run pod update.

Podfile

pod 'Batch', '~> 2.0'

Carthage

Update your Cartfile if necessary and run carthage update Batch.

Cartfile

github "BatchLabs/Batch-iOS-SDK" ~> 2.0

Linking the SDK

Batch is now distributed as a dynamic framework. This mean you can now safely link Batch between multiple framework targets!

Since Batch is now a mergeable dynamic library, the additional metadata induced by this feature makes the XCFramework distribution heavier, but has no effect in the final size of Batch in your app once compiled.

Vision OS

This version introduced the visionOS support but some features are still unsupported like:

• In-App messaging and mobile landings are unavailable.

• In-App rating is not supported on visionOS due to an OS limitation.

Core migration

Renaming default module

This version introduced an important change since the default Batch module has been renamed into BatchSDK. This mean you have to replace all your calls to this module like when starting the SDK.

Swift

BatchSDK.start(withAPIKey: "YOUR_API_KEY")

Objective-C

[BatchSDK startWithAPIKey:@"MY_API_KEY"];

Advertising Identifier

The iOS Batch SDK 1.21 had removed automatic collection of IDFA (Identifier For Advertisers). This version has totally dropped the support of the IDFA and you can no longer set an advertising id to Batch since all related APIs have been removed.

Advanced Information

The Batch SDK V1 allowed you to disable advanced information generally with setUseAdvancedDeviceInformation(false). This has been removed and replaced with a more fine-tuning control of what you want to enable with:

Swift

BatchSDK.updateAutomaticDataCollection { config in
    config.setGeoIPEnabled(true) // Enable GeoIP resolution on server side
    config.setDeviceModelEnabled(true) // Enable automatic collection of the device model information
}

Objective-C

[BatchSDK updateAutomaticDataCollection:^(BatchDataCollectionConfig * _Nonnull config) {
  [config setGeoIPEnabled:true];  // Enable GeoIP resolution on server side
  [config setDeviceModelEnabled:true]; // Enable automatic collection of the device model information
}];

All data configurable with this API are now disabled by default and should be enabled if you want to use it.

For more information, please visit our automatic data collection guide.

Deprecated APIs

All deprecated APIs in the SDK v1 have been removed. Some other APIs have been renamed/reworked to feel Swift native. To see in details the differences, please visit our changelog.

Project migration

This version follows Batch's pivot to being an omnichannel platform. It allows you to collect data for your Projects and Profiles. If you are not familiar with these two concepts, please see this guide beforehand.

Profile Attributes

First of all, most of the user-related write APIs have been removed. Reading methods are still usable since we do not provide yet a way to get synced data for a Profile, but keep in mind that the data returned is only about your installation and not your Profile.

To interacts with our user-centered model, you should now use the BatchProfile module. Let's see a migration example.

If you were previously doing something like that:

Swift

let editor = BatchUser.editor()
editor.setIdentifier("john.doe")
editor.setLanguage("en")
editor.setRegion("US")
try? editor.setEmail("[email protected]")
editor.setEmailMarketingSubscriptionState(BatchEmailSubscriptionState.subscribed)
editor.setAttribute(26, forKey:"age")
editor.removeAttribute(key:"firstname")
editor.addTag("has_bought", inCollection: "actions") 
editor.removeTag("has_bought", fromCollection: "actions") 
editor.clearTagCollection("actions")
editor.save()

Objective-C

BatchUserDataEditor *editor = [BatchUser editor];
[editor setIdentifier:@"john.doe"];
[editor setLanguage:@"en"]; 
[editor setRegion:@"US"]; 
[editor setEmail:@"[email protected]" error:nil]; 
[editor setEmailMarketingSubscriptionState:BatchEmailSubscriptionStateSubscribed]; 
[editor setIntegerAttribute:@26 forKey:@"age" error:nil];
[editor removeAttributeForKey:@"firstname"];
[editor addTag:@"has_bought" inCollection:@"actions"];
[editor removeTag:@"has_bought" fromCollection:@"actions"];
[editor clearTagCollection:@"actions"]; 
[editor save];

You should now do:

Swift

BatchProfile.identify("john.doe")
BatchProfile.editor { editor in
    try? editor.setLanguage("en")
    try? editor.setRegion("US")
    try? editor.setEmailAddress("[email protected]")
    editor.setEmailMarketingSubscriptionState(BatchEmailSubscriptionState.subscribed)
    try? editor.set(attribute: 26, forKey: "age")
    try? editor.removeAttribute(key:"firstname")
    try? editor.addToStringArray(item: "has_bought", forKey: "actions")
    try? editor.removeFromStringArray(item: "has_bought", forKey: "actions")
    try? editor.removeAttribute(key:"actions")
    // Don't forget to use `editor.save()` if you use the editor in a local variable and not a closure like here.
}

Objective-C

[BatchProfile identify:@"john.doe"];
[BatchProfile editWithBlock:^(BatchProfileEditor * _Nonnull editor) {
    [editor setLanguage:@"en" error:nil];
    [editor setRegion:@"US" error:nil];
    [editor setEmailAddress:@"[email protected]" error:nil];
    [editor setEmailMarketingSubscriptionState:BatchEmailSubscriptionStateSubscribed];
    [editor setIntegerAttribute:26 forKey:@"age" error:nil];
    [editor removeAttributeForKey:@"firstname" error:nil];
    [editor addItemToStringArrayAttribute:@"has_bought" forKey:@"has_bought" error:nil];
    [editor removeItemFromStringArrayAttribute:@"has_bought" forKey:@"has_bought" error:nil];
    [editor removeAttributeForKey:@"actions" error:nil];
     // Don't forget to use `[editor save]' if you use the editor in a local variable and not a closure like here.
}];

For more information, please see the following sections :

• Custom user id

• Custom region/language

• Custom user attributes

• Email subscription

Profile Data migration

To make it easier to collect data to a Profile, Batch has added two automatic ways to migrate old installation's data on a Profile. So the first time a user will launch your application running on v2 :

• He will be automatically identified (logged-in) if he had a Batch custom_user_id set on the local storage.

• Its natives (language/region) and customs data will be automatically migrate to a Profile if your app is attached to a Project.

These migrations are enabled by default, but you may want to disable them, to do so add the following before starting the SDK:

Swift

import Batch

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    
    // Disable profile's migration
    BatchSDK.setDisabledMigrations([
     
       // Whether Batch should automatically identify logged-in user when running the SDK for the first time.
       // This mean user with a custom_user_id will be automatically attached a to a Profile and could be targeted within a Project scope.
       .customID,
       
       // Whether Batch should automatically attach current installation's data (language/region/customDataAttributes...)
       // to the User's Profile when running the SDK for the first time.
       .customData
     ])
    // Then start Batch SDK.
    BatchSDK.start(withAPIKey: "YOUR_API_KEY")
}

Objective-C

@import Batch;

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
      // Disable profile's migration
      [BatchSDK setDisabledMigrations: 
        // Whether Batch should automatically identify logged-in user when running the SDK for the first time.
        // This mean user with a custom_user_id will be automatically attached a to a Profile and could be targeted within a Project scope.
        BatchMigrationCustomID |
        // Whether Batch should automatically attach current installation's data (language/region/customDataAttributes...)
        // to the User's Profile when running the SDK for the first time.
        BatchMigrationCustomData
      ];
  
  // Then start Batch SDK.
  [BatchSDK startWithAPIKey:@"MY_API_KEY"];

  return YES;
}

For more information, please visit our profile data migration guide

Event data

Android Batch SDK v2 introduced two new types of attribute that can be attached to an event : Array and Object.

What's change:

• BatchEventData has be renamed into BatchEventAttributes.

• addTag API is no longer available and has been replaced by putStringArray with the $tags reserved key.

• Optional withLabel parameter is no longer available and has been replaced by a $label reserved key under BatchEventAttributes.

Note: Limits are unchanged and still 200 chars max for $label and 10 items max for $tags .

So if you were previously doing something like:

Swift

let data = BatchEventData()
data.add(tag: "squash")
data.add(tag: "daily_digest")
data.put(true, forKey: "premium")
data.put("123456", forKey: "id")
BatchUser.trackEvent("read_article", withLabel: "sports", data: data)

Objective-C

BatchEventData *data = [BatchEventData new];
[data addTag:@"squash"];
[data addTag:@"daily_digest"];
[data putBool:@(YES) forKey:@"premium"];
[data putString:@"123456" forKey:@"id"];
[BatchUser trackEvent:@"read_article" withLabel:@"sports" associatedData:data];

You should now do:

Swift

let attributes = BatchEventAttributes { data in
    data.put("sports", forKey: "$label")
    data.put(["squash", "daily_digest"], forKey: "$tags")
    data.put("123456", forKey: "id")
    data.put(true, forKey: "premium")
}
BatchProfile.trackEvent(name: "read_article", attributes: attributes)

Objective-C

BatchEventAttributes *attributes = [BatchEventAttributes new];
[attributes putString:@"sports" forKey:@"$label"];
[attributes putStringArray:@[@"squash", @"daily_digest"] forKey:@"$tags"];
[attributes putString:@"123456" forKey:@"id"];
[attributes putBool:YES forKey:@"premium"];
[BatchProfile trackEventWithName:@"read_article" attributes:attributes];

For more information, please visit our custom event guide.

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