Emarsys stopped supporting the Mobile Engage SDK on December 31, 2020. Please complete your migration to our new Emarsys SDK as soon as possible.
Introduction
We learned a substantial amount from developing Mobile Engage SDK. We managed to apply these learnings and feedbacks to the new Emarsys SDK. We want to make sure we understand end to end the experience of your app users and give you some insights through the data platform.
The workflow for linking/unlinking a contact to a device was too complicated:
- We removed anonymous contacts from our API. This way, you can always send behaviour events, opens without having the complexity to login first with an identified contact or use hard-to-understand anonymous contact concept.
The API is stateless
- We can scale with our new stateless APIs in the backend. We now include anonymous in-app metrics support.
Swift first approach
- We have improved the interoperability of our SDK with Swift. Using our SDK from Swift is now more convenient.
Repetition of arguments
- We have improved the implementation workflow, so the energy is spent during the initial integration, but not repeated during the lifetime of the app.
Unification of GitHub projects
- The Predict SDK, The Emarsys core SDK, the Mobile Engage SDK and the corresponding sample app are all now in a single repository. You can now find up-to-date and tested usage examples easily.
Differences between Mobile Engage SDK and Emarsys SDK
- Library:The library is now called EmarsysSDK and no longer MobileEngageSDK. The Singleton instance is called Emarsys instead of Mobile Engage.
- Languages/frameworks:To improve the ease of integrating the native calls into other languages/frameworks, the signature of functions now is still asynchronous. Please do provide a callback parameter rather than return a handle to the async completion. Status delegates no longer exist.
- iOS OS: On iOS the minimum supported target is iOS 11 or higher.
Project Configuration
Pod File
Update the Pod file so that it uses the new Emarsys SDK instead of the old Mobile Engage SDK.
Old
pod 'MobileEngageSDK'
pod 'CoreSDK'
New
pod 'EmarsysSDK'
You will need to run pod install via terminal from the project directory after the update.
Classes Update
1. Update Library Import
Update the library import to use the new Emarsys SDK.
Old
import MobileEngageSDKNew
import EmarsysSDK2. Protocol Renamed
The MEEventHandler interface has been renamed to EMSEventHandler.
Old
class AppDelegate: UIResponder, UIApplicationDelegate, MEEventHandler {
...
}New
class AppDelegate: UIResponder, UIApplicationDelegate, EMSEventHandler {
...
}3. AppDelegate Window Property
The window property must exists in AppDelegate. For the window property please check the official Apple documentation.
Method Updates
1. Anonymous and Known Contacts
1.1. Anonymous Contacts
A call of MobileEngage.appLogin without parameters is no longer necessary. You no longer login anonymously, instead upon registering your device, we will automatically create an anonymous contact if the device has not been registered before. Duplication of anonymous contacts is avoided by matching the hardware ID or push token, which is handled by Emarsys.
1.2. Known Contacts
The workflow for linking a device to contact was changed. Instead of passing both the contactFieldId and the contactFieldValue when the user logs in, you now only need to send the contactFieldValue. The contactFieldId is set once during the configuration of the Emarsys SDK.
The setContact call only has to be placed once to connect the device to the contact record in Emarsys. It does not need to be placed for every time the app starts. However, if the contact has been logged out using the clearContact method, the setContact call should be placed the next time the contact logs into the account to reconnect the device with the contact record.
Old
MobileEngage.appLogin(contactFieldId, contactFieldvalue)New
let config = EMSConfig.make { builder in
...
builder.setContactFieldId(contactFieldId)
...
}
Emarsys.setContactWithContactFieldValue(contactFieldValue)
2. appLogout
To remove the device details from the contact record has changed from appLogout to clearContact.
Old
MobileEngage.appLogout()New
Emarsys.clearContact();With the device details removed from the contact record, the user is still reachable for mobile marketing using the anonymous contact record.
3. setPushToken
The setPushToken call has been updated to reflect the SDK naming convention. The CompletionListener is optional.
Old
MobileEngage.setPushToken(deviceToken);New
Emarsys.push.setPushToken(deviceToken)4. setPushToken(null)
If you were calling the setPushToken method with null in order to remove the token, it is required to update the call to use the dedicated method removePushToken. The CompletionListener is optional.
Old
MobileEngage.setPushToken(null);New
Emarsys.Push.removePushToken();5. statusDelegate
The MobileEngage.statusDelegate property was removed, you can now specify a completion block for each method instead.
Old
MobileEngage.statusDelegate = self
New
Emarsys.push.setPushToken(token) { (err) in
...
}6. Rich Media
Push notification could show media content and action buttons besides the title and body. Push notifications with these types of contents are called Rich Notifications.
Requirements
- Mobile Engage backend is setup for sending push notifications already
- Application is setup for receiving push notifications already
- Use Emarsys SDK notification extension as mentioned in documentation
Only HTTPS image URLs are supported.
- Add a new Notification Service Extension target to your project.
- Add the
EmarsysNotificationServiceto this target in the Podfile.
target "Emarsys Sample" do
pod 'EmarsysSDK'
end
target "EMSNotificationService" do
pod 'EmarsysNotificationService'
end- Install pods with the pod install command in the workspace directory via terminal.
- If your selected language is Swift, then create a Bridging-Header for your new target.
<NameOfYourExtension-Bridging-Header.h>#import <EmarsysNotificationService/EMSNotificationService.h>Open the NotificationService class in the target, then:
- Import the
EmarsysNotificationService. - Extend the class
EMSNotificationServiceinstead ofUNNotificationServiceExtension.
import EmarsysNotificationService
class NotificationService: EMSNotificationService {
}- Request authorization for push notifications in the AppDelegate
application:didFinishLaunchingWithOptions:method.
application.registerForRemoteNotifications()
var options: UNAuthorizationOptions = [.alert, .sound, .badge]
UNUserNotificationCenter.current().requestAuthorization(options: options) { [unowned self] granted, error in
print(granted, error ?? "no error")
if (granted) {
Emarsys.notificationCenterDelegate.eventHandler = self
UNUserNotificationCenter.current().delegate = Emarsys.notificationCenterDelegate
}
}