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.3.1 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) {
}];Swift
Emarsys.setContact(<contactFieldId: NSNumber>, <contactFieldValue: String>) { error in
}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) {
}];Swift
Emarsys.setAuthenticatedContact(<contactFieldId: NSNumber>, <openIdToken: String>)
Emarsys.setAuthenticatedContact(<contactFieldId: NSNumber>, <openIdToken: String>) { error in
}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) {
}];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.silentMessageEventHandlerEmarsys.push.notificationEventHandlerEmarsys.inapp.eventHandlerinlineInapp.eventHandlerEmarsys.geofence.eventHandlerEmarsys.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;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>)