iOS integration:: Mobile Engage - Migration to Emarsys iOS SDK 3.0.0 – Emarsys

Introduction

Since we have released the current major version of the Emarsys SDK we have received a lot of valuable usage feedback. Also, the development tools of the underlying platforms have improved a lot. We always strive to offer the best possible developer experience and the most up-to-date mobile feature set to our users and this sometimes requires to introduce breaking changes of our API and therefore to release a new major version.

This migration guide leads you through the changes you have to make to your Emarsys iOS SDK integration to start using the 3.0.0, or the latest 3.8.0 version. We estimate that this migration can be done in about 60 minutes. We recommend to do this migration as soon as possible so that you can benefit from these improvements and also prepare your integration to benefit from future Emarsys SDK improvements. If you need any help in the migration please reach out to Emarsys support.

Benefits of migrating to Emarsys iOS SDK 3.0.0

Cleaner and improved API
Generalized eventHandlers, Emarsys SDK now uses blocks as eventHandlers instead of protocols, this improves usage from Swift.
Gave more flexibility to the developers by moving the contactFieldId into the setContact call, so it is not needed at the moment of the SDK setup.

setContactWithContactFieldValue

With Emarsys SDK 3.0.0 we have moved the contactFieldId from the config to setContact call to give more flexibility. So the developer can decide what the contactFieldId is going to be when the contact needs to be identified and not at the setup where it might be an unknown what type of authentication the user might choose.

This also means that the old setContactWithContactFieldValue/setContactWithContactFieldValue:completionBlock methods are not available anymore. To migrate, use the new setContactWithContactFieldId:contactFieldValue: method with the contactFieldId, like this:

Objective-C

[Emarsys setContactWithContactFieldId:<contactFieldId: NSNumber>
                    contactFieldValue:<contactFieldValue: NSString>
                      completionBlock:^(NSError *error) {
                      }];

Click to copy

Swift

Emarsys.setContact(<contactFieldId: NSNumber>, <contactFieldValue: String>) { error in 

}

Click to copy

setAuthenticatedContactWithIdToken

This paragraph is only relevant, if you are using Open Id Connect.

We generalized namings between the iOS and Android Emarsys SDK. Because of this, setAuthenticatedContactWithIdToken was renamed to setAuthenticatedContactWithOpenIdToken. Please change this in your implementation. Nothing changed besides the renaming in the method.

Objective-C

[Emarsys setAuthenticatedContactWithContactFieldId:<contactFieldId: NSNumber>
                                       openIdToken:<openIdToken: NSString>];

[Emarsys setAuthenticatedContactWithContactFieldId:<contactFieldId: NSNumber>
                                       openIdToken:<openIdToken: NSString>
                                   completionBlock:^(NSError *error) {
                         }];

Click to copy

Swift

Emarsys.setAuthenticatedContact(<contactFieldId: NSNumber>, <openIdToken: String>)
Emarsys.setAuthenticatedContact(<contactFieldId: NSNumber>, <openIdToken: String>) { error in
}

Click to copy

changeApplicationCode

changeApplicationCode:contactFieldIdandchangeApplicationCode:contactFieldId:completionBlock method has been removed.

We simplified the changeApplicationCode by removing the methods with the contactFieldId. contactFieldId is now part of the setContact.

Obejctive-C

[Emarsys.config changeApplicationCode:<applicationCode: NSString>
                      completionBlock:^(NSError *error) {
                      }];

Click to copy

Swift

Emarsys.config.changeApplicationCode(<applicationCode: String>) { error in            
}

Click to copy

Inbox

The Device Centric Inbox solution has been discontinued and removed from the SDK, but MessageInbox can be used instead.

Event-handlers

We had mixed usage of eventHandlersProtocols and blocks previously in Emarsys SDK, but from version 3.0.0 we changed all handlers to blocks, which will improve the usage from Swift.

This means that we removed EMSEventHandler from the SDK completely.

EventHandlers can be set like the following example:

Objective-C

Emarsys.geofence.eventHandler = ^(NSString *eventName, NSDictionary<NSString *, id> *payload) {
        
};

Click to copy

or,

[Emarsys.geofence setEventHandler:^(NSString *eventName, NSDictionary<NSString *, id> *payload) {
        
}];

Swift

Emarsys.geofence.eventHandler = { name, payload in
            
}

Click to copy

List of changed items:

Emarsys.push.silentMessageEventHandler
Emarsys.push.notificationEventHandler
Emarsys.inapp.eventHandler
inlineInapp.eventHandler
Emarsys.geofence.eventHandler
Emarsys.onEventAction.eventHandler

Retired MEUserNotificationCenterDelegate

From Emarsys SDK 3.0.0 MEUserNotificationCenterDelegate is not available anymore on the publicEmarsysAPI, everything is handled by Emarsys.push.

This means that, setting the delegate of the UNNotificationCenter in the applicationDidFinishLaunching method changes from Emarsys.notificationCenterDelegate to Emarsys.push.

In case you need to use another UNUserNotificationCenterDelegate solution, you can set that as a delegate to our Emarsys.push.delegate and we call the methods of the delegate when our delegate methods were called.

Predict

trackCartWithCartItems

cartItems parameter name has been simplified to items.

Objective-C

- (void)trackCartWithCartItems:(NSArray<id <EMSCartItemProtocol>> *)cartItems;

--->

- (void)trackCartWithCartItems:(NSArray<id <EMSCartItemProtocol>> *)items;

Click to copy

API method changes

We renamed most of our methods on our Swift API to improve the usage of the SDK. XCode can fix most of the changes, but these 2 cases need extra work.

Swift

Emarsys.trackCustomEvent(<withName: String>, <eventAttributes: [String:String]?>) { error in
}
--->
Emarsys.trackCustomEvent(<eventName: String>, <eventAttributes: [String:String]?>) { error in
}


Emarsys.predict.trackCategoryView(<withCategoryPath: String>)
--->
Emarsys.predict.trackCategory(<categoryPath: String>)

Click to copy