Migration guide for Emarsys SDK 3.0.0

Introduction

We released the current major version of the Emarsys SDK two years ago. In the meantime we have received a lot of valuable usage feedback from our users and 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 SDK integration to start using the latest 3.0.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 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’ve moved the contactFieldId from the config to setContact call to give more flexibility into the developer’s hand 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) {
                      }];

Swift

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

}

setAuthenticatedContactWithIdToken

Note

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) {
                         }];

Swift

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

changeApplicationCode

Note

changeApplicationCode:contactFieldId and changeApplicationCode:contactFieldId:completionBlock method has been removed

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

Objective-C

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

Swift

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

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) {
        
};

or

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

Swift

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

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 public Emarsys API, 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;

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>)