Documentation > iOS > Advanced

Batch 1.13 migration

Batch 1.13 comes with a number of changes, some of which deprecate old APIs. While deprecated APIs are still supported, it is greatly encouraged to migrate to the new ones.

This migration guide will help you update your implementation.

Batch now supports setting a deeplink delegate.
This allows you to handle deeplinks directly, rather than have it be handled by iOS' openURL. Universal links were not supported, your application had to implement a scheme, and anything that was not a valid NSURL would be ignored.

A workaround was to call [Batch enableAutomaticDeeplinkHandling:false], but it had a couple of limitations:

  • Notifications had to be intercepted using iOS' callbacks, and the deeplink had to be extracted manually
  • It didn't work for mobile landings/in-app messages

If you previously used [Batch enableAutomaticDeeplinkHandling:false], consider using a deeplink delegate.

In order to implement the delegate, you need to make a class that implements that protocol, and set it. Like most delegates, it is weakly retained, so make sure it is retained somewhere else.

Once set, Batch will call you on -openBatchDeeplink: when your app should process a deeplink. iOS' openURL will not be called.

Push methods

In older SDKs, Batch had a single method to enable push notification: [BatchPush registerForRemoteNotifications].
For simplicity, it combined requesting the permission to display notifications and asking iOS for a push token. We also advised to call this method at every app launch to make sure the token is always up to date.

In many cases, this was enough. But if your application followed the good practice to ask the user at some other point in your app than on the first launch, developers had to add their own logic to avoid calling this method unless notifications had already been accepted by the user.
It was also confusing, as it got its name from a method on UIApplication, but behaved very differently.

So, in Batch 1.13, we split this method in two:

  • [BatchPush requestNotificationAuthorization] This method does exactly what [BatchPush registerForRemoteNotifications] used to do: triggers the system notification authorization prompt, and asks for a push token after the user replies.
  • [BatchPush refreshToken] This method only asks iOS to refresh the push token.

Now, developers who don't immediatly ask for notifications can simply call [BatchPush refreshToken] in application:didFinishLaunchingWithOptions, and [BatchPush requestNotificationAuthorization] when they want to trigger the system prompt.

To support iOS 12, Batch 1.13 also introduces:

  • [BatchPush requestProvisionalNotificationAuthorization] to request provisional notifications on iOS 12
  • [BatchPush setSupportsAppNotificationSettings:], allowing you to tell iOS that your application supports supplemental notification settings. This needs to be called BEFORE requestNotificationAuthorization/requestProvisionalNotificationAuthorization.

For more info, see the methods' documentation.

Events

With Batch 1.13.0, we have overhauled how event data works. Even if the deprecated APIs still work, you should migrate to the new format as soon as possible to avoid issues.

If you didn't add data to your events, you can safely skip this documentation.

The new API

Starting with Batch SDK 1.13.0, you can attach custom data to events using BatchEventData. You will then use this event when calling BatchUser.trackEvent(). It is very similar to BatchUserDataEditor.

It supports setting the following data:

  • Tags: a collection of string values
    • They can't be longer than 64 characters, empty or null.
    • The SDK will automatically lowercase them, so two same strings with different casing does not count as two different tags.
  • Attributes: key/value pairs of data
    • Attributes associate values to keys.
    • Keys should be made of letters, numbers or underscores ([a-z0-9_]) and can't be longer than 30 characters.
      They will be lowercased, so trying to use the same key with different casing will overwrite the previously set value.
    • Values can be of the following types:
      • Strings, not longer than 64 characters, can't be empty or null.
      • Booleans
      • Floats/Doubles
      • NSInteger

An event supports at most 10 tags and 10 attributes.

Any attempt to add an invalid tag or attribute will fail. Setting a value for an existing key will overwrite it.

Example:

  • Swift
  • Objective-C
let data = BatchEventData()
data.add(tag: "sports")
data.add(tag: "squash")
data.add(tag: "daily_digest")

data.put(true, forKey: "premium")
data.put("123456", forKey: "id")
BatchUser.trackEvent("read_article", withLabel: nil, data: data)

Compatibility

Event data tracked using the legacy API will be converted to the new format, after logging a warning.

There are a couple of limitations:

  • Any data that can't be represented using BatchEventData will be ignored.
  • Same size limits apply (key naming, string attribute length, number of attributes)

Tags are not migrated from arrays found in the legacy data format.

Migration

In order to use the new API, you will have to rewrite the code putting data in what used to be a NSDictionary to use BatchEventData.

See the class' documentation for the list of the available put methods.
Consider using tags rather than tracking multiple events sharing the same name, but with different labels.

Objective-C users will also to switch from [BatchUser trackEvent:withLabel:data:] to [BatchUser trackEvent:withLabel:associatedData:].

Swift users can continue using BatchUser.trackEvent(, withLabel:, data:), as Swift will recognize data's type.

Platform

Company

Resources

Contact