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:

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:

Xcode Project Navigator extension deletion

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/ Be careful, as you might have multiple script phases.
Delete it.

Xcode script phase deletion

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

Related Swift forum thread.

Manual Integration

Replacing your manual Batch integration with the XCFramework distribution is quite easy.

First, delete Batch.embeddedframework (or 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.

Xcode Project Navigator framework deletion

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 add framework to project

Xcode should have added Batch.xcframework in the Link Binary With Libraries build step. Add it manually if this did not happen.

Xcode Link with libraries build step

Your project should now build!