Batch 1.16 migration
Batch 1.16 comes with a number of changes regarding the distribution of the SDK and it's extension counterpart.
This migration guide will help you update your implementation.
iOS minimum version
Batch 1.16 requires iOS 10.0 or higher. If your app targets an older version of iOS, please downgrade to 1.15.
Migrating from the older binary BatchExtension
With the 1.16 release, BatchExtension has been rewritten and open-source in two repositories:
- https://github.com/BatchLabs/Batch-iOS-SDK-Extension (Swift version, recommended)
- https://github.com/BatchLabs/Batch-iOS-SDK-Extension-ObjC (Objective-C version, should only be used if you cannot use the Swift one)
This marks the end of the binary distribution of BatchExtension, which used to be bundled with the SDK downloads. The only way to integrate BatchExtension in your application from now on is using the source.
Fortunately, package managers make this easy to deal with!
Migrating to the new BatchExtension is done in three steps:
- Remove the old BatchExtension framework
- Add the new one using a package manager
- Update your code to match the new API signatures, if needed.
Removing the old BatchExtension
Since BatchExtension has never been distributed on a package manager, you had to copy it in your project and add a script phase.
In order to remove the framework, simply find it in the Project Navigator (which is the first tab of the left sidebar), and delete it:
When asked what to do with the deletion, pick
Move To Trash.
Xcode should have automatically removed the framework reference from the
Link Binary With Libraries and
Embed Frameworks build steps.
Now, go in your main target's
Build Steps and find the
Run Script phase that refences a script which path contains
BatchExtension.framework/strip-frameworks.sh. Be careful, as you might have multiple script phases.
BatchExtension has now been fully removed from your project. Now, we have to add it back!
Adding the new BatchExtension using a package manager
Note: If your extension code is written in Objective-C and uses BAENotificationServiceExtension, please use the Objective-C version of the extension.
The extension is available on Swift Package Manager, CocoaPods and Carthage.
Please click here to open the rich push setup guide which will walk you through integrating the extension, and come back here once done.
Updating your code
If the extension builds without issues, you do not have anything to do!
If it doesn't, what you have to do depends on how you integrated the extension and which language you use:
You're using Swift code
BatchExtension 3.0.0 introduces the following source breaking changes for Swift users:
- Classes have been unprefixed (except
BAENotificationServiceExtension). For example, if your Swift code references
BAERichNotificationHelper, you need to change it to
RichNotificationHelper.appendRichData(to: completionHandler:)has been renamed. It is now
RichNotificationHelper.appendRichData(toContent: completionHandler:). Xcode offers a quickfix for this.
You're using Objective-C code
While the public API doesn't change, you might run into the following message:
Cannot subclass a class that was declared with the 'objc_subclassing_restricted' attribute.
This happens if you used the standard version of the extension using Swift PM.
To fix this, use the Objective-C version of the extension as described in the rich push setup guide, or rewrite the extension code in Swift (do not forget to update the extension's Info.plist with the new class name).
If you run into any other issue, please contact our support team to get help on your migration.
Migrating to XCFramework
Batch 1.16 is now distributed as a static XCFramework instead of a legacy fat static framework. While the legacy framework format is still distributed, we encourage you to switch to the XCFramework build as soon as possible.
Batch 1.16.0 and higher are distributed as a XCFramework in CocoaPods. CocoaPods should handle the transition without needing any action on your end.
If you're running into issues, make sure you've updated to the latest CocoaPods version for XCFrameworks support.
As of writing, Carthage (ver 0.36.0) does not support XCFrameworks. Therefore, Batch is still distributed as a fat framework for Carthage.
iOS Simulator for Apple Silicon and Mac Catalyst support are not available with carthage.
Swift Package Manager
We've heard loud and clear that developers would like to use Swift Package Manager to add Batch in their app. Unfortunately due to bugs in Xcode 12's handling of binary frameworks in SPM packages, Batch isn't distributed there yet.
We will reevaluate this decision when a new version of Xcode that fixes the issues is released.
Replacing your manual Batch integration with the XCFramework distribution is quite easy.
Batch.framework) in the Project Navigator. Xcode should remove all of the Framework's reference in the build steps. Pick
Move To Trash when asked.
Then, drag & drop
Batch.xcframework in the Project Navigator where the framework you deleted was.
Unless you manually copied the XCframework folder into your project's directory, check
Copy items if needed. Make sure the only checked target is your Application target: extensions should be unchecked.
Xcode should have added Batch.xcframework in the
Link Binary With Libraries build step. Add it manually if this did not happen.
Your project should now build!