Batch.com iOS SDK
Batch is the leading mobile engagement & push notification suite engineered for the mobile era.
- Download the SDK
- Drag and drop the xcframework into your project
lzand Batch to
Linked Frameworks and Librariesin your project settings
Other Build Flags
Note: If you can't add
-ObjC, you can use
Importing the framework
If you're in swift:
Describing what Batch can do is a little too big for this README. Read our setup documentation to follow a step by step tutorial for integrating Batch features into your app.
Copyright 2016 - Batch.com
You may find interesting
A migration guide from Batch 1.15 and lower is available here.
BREAKING: This version drops support for iOS 8 and 9 Batch requires Xcode 12 and iOS 10.0 or higher
Batch now depends on libz. This might require a change in your project:
- Cocoapods: The podspec has been updated to add the required linker flag. No action is needed.
- Carthage/Manual integration:
When building, Xcode should automatically link your project with libz. If you get a compilation error, add
-lzto your linker flags, or add
libzto "Frameworks and Libraries" in your app's target.
Batch and Apple Silicon
In order to support Apple Silicon, Batch will adopt the XCFramework format: it is not possible to support the iOS Simulator on Apple Silicon macs in a "fat" framework. What it means for you:
- Cocoapods users will be migrated to the XCFramework automatically
- Carthage users will stay on the old distribution style until Carthage supports XCFrameworks.
- Manual integrations should update to XCFramework as soon as possible. Batch will be distributed in both formats for a couple of versions.
Note that the
armv7s slice is not included in the XCFramework distribution.
BatchExtension isn't distributed with the SDK zip anymore. It will be released on github soon after this release.
- Batch is now compatible with iOS 14's tracking consent and IDFA changes.
- Added UIScene support. If your application uses it, you must add an
UNUserNotificationCenterDelegate, otherwise Direct Opens, Deeplinks and Mobile Landings will not work: UIScene disables legacy push application delegate methods.
- eSIMs are now supported. Phones that only have an eSIM will now properly report back their carrier, if the feature hasn't been disabled.
- More nullability annotations have been added. As those annotations match Apple's own, we do not expect source compatibility to break.
- Support for TLS versions older than 1.2 has been removed.
- Added a new builtin action named
batch.ios_tracking_consent, which requests tracking consent via AppTrackingTransparency. More info in the documentation.
BatchEventDispatcherTypeNotificationOpenis no longer broadcasted when the application is processing a background push.
- Enhanced the way the SDK fetchs notifications from the servers to greatly reduce bandwidth usage. No public API change.
- Add a new method
BatchPush.isBatchPushto check if a received push comes from Batch.
BatchUNUserNotificationCenterDelegate, an UNUserNotificationCenterDelegate implementation that forwards events for Batch. Call
BatchUNUserNotificationCenterDelegate.register()to automatically set it as your delegate. BatchUNUserNotificationCenterDelegate can display notifications when your app is in the foreground using the
- Batch will now emit a warning in the console when your app does not register an
UNUserNotificationCenterDelegateby the time
application:didFinishLaunchingWithOptions:returns. Implementing this delegate improves Batch's handling of various features that rely on notification interaction feedback, such as analytics or deeplinks: it is strongly recommended that you implement it if you don't already.
- Batch now emits the
BatchPushOpenedNotificationNSNotification when a notification has been opened by the user. This deprecates BatchPushReceivedNotification: see
BatchPush.hfor more info.
- In automatic mode,
application:didReceiveRemoteNotification:fetchCompletionHandler:'s completion handler is no longer called on your behalf when a deeplink is opened.
- The "modal" format now correctly triggers actions after it has been dismissed. This will have an impact on when the custom actions are executed, making them more consistent with the Fullscreen format.
- This fixes an issue where deeplinks could not be opened in the application using SFSafariViewController with modal formats.
- The image format is now properly sized when in a freeform window (iPad in Split View, Catalyst)
- Fix a rare race condition with the interstitial format where it would fail to layout properly when the image server could not be reached.
- Modally presented messages will not be allowed to be dismissed unless they're the frontmost view controller. This fix an issue where a message with an autodismiss might dismiss a view controller presented on top of it.
- Improved dismissal logic. While automatic dismissal may fail in some rare occasions due to iOS refusing to dismiss a modal view controller when one is animating, it will not prevent the user from manually dismissing the view anymore.
- Added new strongly typed methods for setting attributes on BatchUserDataEditor. They greatly enhance Swift usage of the API. See
setBooleanAttribute:forKey:errorand similar methods (
set(attribute: Bool, forKey: String)in Swift).
- Those new methods return validation errors: you can now know if your attribute key/value does not pass validation and will be discarded.
- nil values are not supported in the new methods. Use
- Clicking the "share" buttons in the debug views no longer crash on iPads.
Compiled with Xcode 11.5 This minor release is the last one to support iOS 8 and 9.
- Fix an issue where event dispatchers might not be called.
- Fix an issue where events that had not been sent to the server would be lost when the app's process was killed.
Compiled with Xcode 11.5
- Added support for Date in BatchEventData.
- BatchEventData now supports up to 15 attributes (from 10).
Requires Xcode 11
This release has been built using Xcode 11.3.1.
This is the LAST release that support iOS 8 and 9. Future releases will require iOS 10+
- Changed how notification status is reported: The SDK will now tell Batch's servers that notifications are enabled if :
- The app has requested and holds a provisional authorization.
- The user has disabled banners but kept lockscreen or notification center delivery enabled.
- Added support for external analytics using
BatchEventDispatcher. See the documentation for more details.
- New enum property
BatchMessagingContentType contentTypeon class
BatchInAppMessageto help cast to the right content class.
- A new optional delegate method
BatchMessagingDelegate.presentingViewControllerForBatchUIallows to specify which view controller to display Batch messages on.
- Fixed an issue where the last line of a label could be cut.
- Improved accessibility of all message formats
- Added the
BatchInboxFetcher, allowing the deletion of notifications
This release has been built using Xcode 11.1.
- Fix an issue where mobile landings might fail to be shown after opening a push for a backgrounded app on iOS 13
- Fix an issue where BatchDeeplinkDelegate does not fire in certain conditions when opening a push from the lockscreen
- Fix an issue where banners would move more than expected when swiping on them on iOS 13
This release officially supports iOS 13. It has been built using and requires Xcode 11.0 GM 2.
This is the LAST release that support iOS 8 and 9. Apple has already removed their simulators form Xcode 11.
Future releases of the SDK will be distributed as a dynamic framework, as opposed to the current static framework, and will require the Swift runtime in your app.
It will be distributed in the XCFramework format for supported package managers and manual downloads.
- Add UIScene support
- Add an analytics event for iOS 13's modal swipe-to-dismiss
- Bug fix: deeplinks from actions are properly sent to Deeplink delegate method
- High level data (language/region/custom user id) can now be read back.
- User data (attributes and tags) can now be read back. Documentation
Added support for two new UI formats: Modal, and Image. See the documentation for more information.
Added support for GIFs in Mobile Landings and In-App messages
Added support for rich text.
Added support for text scrolling in all formats. Banners will now have a maximum body height of ~160pt, and their text will scroll.
Deeplinks can now be open directly in the app using a SFSafariViewController for Push Notifications, Mobile Landings and In-App Mesasges
Added new methods on the messaging delegate allowing you to track more information such as close/autoclose and button presses. More info in the Mobile Landings documentation.
BatchMessaging.setAutomaticModehas been renamed to
- BatchPushAlertDidResignNotification is sent when user dismissed the Remote notification authorization alert. Notification's userInfo dict contains user's choice in BatchPushNotificationDidAcceptKey
- Fixed a rare race condition crash that could happen when tracking an event while In-App campaigns are fetched from the server.
- Fixed an issue where adding tags would not work with 1.13.1
Re-release of 1.13.0, compiled with Xcode 10.1. Batch now includes an arm64e slice.
Note: This release comes with an update to the included BatchExtension framework.
Batch SDK 1.13.0 Release
Fixed a rare crash that could happen when Batch's internal database failed to initialize in
Opting-out from the SDK now sends an event notifying the server of this. If a data wipe has been asked, the request will also be forwarded to the server. New methods have been introduced to be informed of the status of the request to update your UI accordingly, and possibly revert the opt-out if the network is unreachable.
BatchDeeplinkDelegateprotocol. Adopting it allows you to manually process deeplink open requests from Batch, rather than having to implement
Batch.deeplinkDelegatefor more information.
- The SDK will report whether notifications are allowed, denied, or undecided more accurately on iOS 10 or higher
- Added a method to easily open iOS' settings for the current application's notification settings
+[BatchPush registerForRemoteNotifications]into more explicit methods.
+[BatchPush requestNotificationAuthorization]shows the system notification authorization prompt, and then fetches the push token. Equivalent to calling
+[BatchPush refreshToken]will only ask iOS for a new token. This needs to be called on every application start to handle upgrades from versions without Batch, or if iOS changes the push token.
- Added support for iOS 12's notification changes:
- You can now ask for provisional notification authorization using
+[BatchPush requestProvisionalNotificationAuthorization]. This method does nothing on versions lower than iOS 12.
- You can now ask Batch to tell iOS that your app supports opening an in-app notification settings from the system settings by calling
[BatchPush setsetSupportsAppNotificationSettings:true]Note that this still requires you to implement a UNUserNotificationCenterDelegate, and the appropriate method to open the settings.
- You can now ask for provisional notification authorization using
Event data support has been overhauled. As a result:
BatchEventData. Use this class to attach attributes and tags to an event. See this class' documentation for more information about limits.
+[BatchUser trackEvent:withLabel:data:]has been deprecated
- Calls to this method will log deprecation warnings in the console
- Legacy data (NSDictionary) will be converted to
BatchEventData. Same data format restrictions apply: Any key/value entry that can't be converted will be ignored, and logged. Tags are not supported
+[BatchUser trackEvent:withLabel:associatedData:]which uses
BatchEventData, replacing the deprecated method.
- Swift users: Since Swift allows methods to be overloaded by type, the method and arguments name do not change: simply replace your data dictionary with a
BatchUser.trackEvent("event_name", withLabel: "label", data: BatchEventData())