Emarsys stopped supporting the Mobile Engage SDK on December 31, 2020. Please complete your migration to our new Emarsys SDK as soon as possible.
Contents
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.
Kotlin first approach
- We have improved the interoperability of our SDK with Kotlin. Using our SDK from Kotlin 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.
- Android OS: On Android the minimum supported target and compile SDK version is 28. The minimum supported minSDKVersion is 19.
Project Configuration
Android Manifest
Update the manifest so that it uses the EmarsysMessagingService instead of the MobileEngageMessagingService.
Old
<service android:name="com.emarsys.mobileengage.service.MobileEngageMessagingService">
<intent-filter>
<action android:name="com.google.firebase.MESSAGING_EVENT"/>
</intent-filter>
</service>
New
<service android:name="com.emarsys.service.EmarsysMessagingService">
<intent-filter>
<action android:name="com.google.firebase.MESSAGING_EVENT"/>
</intent-filter>
</service>
App Build Gradle
Update the app build gradle dependancy to use the Emarsys SDK instead of the Mobile Engage SDK.
Old
dependencies {
implementation 'com.emarsys:mobile-engage-sdk:+'
}New
dependencies {
implementation 'com.emarsys:emarsys-sdk:+'
}The play store does not allow new apps to target less than 28 API level starting August 2019, nor updates to existing apps starting November 2019. The SDK has been adjusted accordingly. Please ensure the compileSdkVersion and targetSdkVersion are configured to a minimum of level 28.
android {
compileSdkVersion 28
defaultConfig {
...
minSdkVersion 19
targetSdkVersion 28
}
}It is required to migrate to AndroidX. If you have not already done so, please migrate using the official guide.
Class/Function Updates
1. Update library imports
Update the library import to use the new Emarsys SDK.
Old
import com.emarsys.mobileengage.MobileEngage;
import com.emarsys.mobileengage.config.MobileEngageConfig;New
import com.emarsys.Emarsys2. Anonymous and Known Contacts
2.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.
2.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 CompletionListener is optional.
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 Java
MobileEngage.appLogin(contactFieldId, contactFieldvalue)New Java
EmarsysConfig config = new EmarsysConfig.Builder()
...
.contactFieldId(15053)
...
.build();
Emarsys.setup(config)
Emarsys.setContact(String contactFieldValue);
Old Kotlin
MobileEngage.appLogin(contactFieldId, contactFieldvalue)New Kotlin
val config = EmarsysConfig.Builder()
...
.contactFieldId(15053)
...
.build()
Emarsys.setup(config)
Emarsys.setContact(contactFieldValue: String, completionListener: CompletionListener? = null)3. appLogout
To remove the device details from the contact record has changed from appLogout to clearContact.
Old Java
MobileEngage.appLogout();New Java
Emarsys.clearContact();Old Kotlin
MobileEngage.appLogout()New Kotlin
Emarsys.clearContact()With the device details removed from the contact record, the user is still reachable for mobile marketing using the anonymous contact record.
4. setPushToken
The setPushToken call has been updated to reflect the SDK naming convention. The CompletionListener is optional.
Old Java
MobileEngage.setPushToken(String pushToken);New Java
Emarsys.Push.setPushToken(String pushToken,CompletionListener completionListener);Old Kotlin
MobileEngage.setPushToken(pushToken:String)New Kotlin
Emarsys.Push.setPushToken(pushToken: String, completionListener: CompletionListener? = null)5. 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 Java
MobileEngage.setPushToken(null);New Java
Emarsys.Push.removePushToken(CompletionListener completionListener);Old Kotlin
MobileEngage.setPushToken(null)New Kotlin
Emarsys.Push.removePushToken(completionListener: CompletionListener? = null)6. setStatusListener
The MobileEngage.setStatusListener method was removed, instead please use the CompletionListener method.
@Override
public void onCompleted(@Nullable Throwable errorCause) {
if(errorCause != null){
Log.e(TAG, error.getMessage(), error);
}
}