Migrate from Mobile Engage

Why Emarsys SDK over Mobile Engage SDK?

We learned a lot from running Mobile Engage SDK in the past 2 years and managed to apply these learnings and feedbacks in our new SDK.

The workflow for linking/unlinking a contact to a device was too complex:

• 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 was stateful and limited our scalability

• We can scale with our new stateless APIs in the backend We now include anonymous inapp metrics support

• We would like to make sure we understand end to end the experience of your app users and give you some insights through the data platform

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 life time 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

Migrate from Mobile Engage SDK

This is a guide on how to move from the Mobile Engage SDK to the new Emarsys SDK. This guide only covers the actual migration from the Mobile Engage SDK to the Emarsys SDK, please look at the README for more general details on how to get started with the Emarsys SDK.

Project Configuration

AndroidManifest.xml

<service android:name="com.emarsys.mobileengage.service.MobileEngageMessagingService">
  <intent-filter>
    <action android:name="com.google.firebase.MESSAGING_EVENT"/>
  </intent-filter>
</service>

↓

<service android:name="com.emarsys.service.EmarsysMessagingService">
  <intent-filter>
    <action android:name="com.google.firebase.MESSAGING_EVENT"/>
  </intent-filter>
</service>

gradle.build

Emarsys SDK dependency

dependencies {
  implementation 'com.emarsys:mobile-engage-sdk:+'
}

↓

dependencies {
  implementation 'com.emarsys:emarsys-sdk:+'
}

Android Target 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.

android {
  compileSdkVersion 26
  defaultConfig {
    ...
    minSdkVersion 16
    targetSdkVersion 26
  }
}

↓

android {
  compileSdkVersion 28
    defaultConfig {
    ...
    minSdkVersion 19
    targetSdkVersion 28
  }
}

Default Channels

On android, the android notification channels must be set up, there is no longer the functionality of a default android channel: the app developer is expected to setup the appropriate channels instead, and match what the marketers use to send push notifications. This means that enableDefaultChannel should be removed when building the configuration. If you were explicitly disabling the default channel the disableDefaultChannel call when building the config can also be removed.

Methods

appLogin()

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 we never saw this device.

appLogin(contactFieldId, contactFieldvalue)

The workflow for linking a device to a contact was changed slightly. 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 EmarsysSDK.

Java

MobileEngage.appLogin(contactFieldId, contactFieldvalue)

↓

EmarsysConfig config = new EmarsysConfig.Builder()
  ...
  .contactFieldId(3)
  ...
  .build();

  Emarsys.setup(config)

  Emarsys.setContact(String contactFieldValue);

Kotlin

MobileEngage.appLogin(contactFieldId, contactFieldvalue)

↓

val config = EmarsysConfig.Builder()
  ...
  .contactFieldId(3)
  ...
  .build()
  
  Emarsys.setup(config)
  
  Emarsys.setContact(contactFieldValue: String, completionListener: CompletionListener? = null)

appLogout

Java

MobileEngage.appLogout();

↓

Emarsys.clearContact();

Kotlin

MobileEngage.appLogout()

↓

Emarsys.clearContact()

setPushToken

Java

MobileEngage.setPushToken(String pushToken);

↓

Emarsys.Push.setPushToken(String pushToken,CompletionListener completionListener);

Kotlin

MobileEngage.setPushToken(pushToken:String)

↓

Emarsys.Push.setPushToken(pushToken: String, completionListener: CompletionListener? = null)

setPushToken(null)

If you were calling the setPushToken method with null in order to remove the token you need to change those calls to use the dedicated method removePushToken instead.

Java

MobileEngage.setPushToken(null);

↓

Emarsys.Push.removePushToken(CompletionListener completionListener);

Kotlin

MobileEngage.setPushToken(null)

↓

Emarsys.Push.removePushToken(completionListener: CompletionListener? = null)

trackMessageOpen(info)

Java

MobileEngage.trackMessageOpen(Intent intent);

↓

Emarsys.Push.trackMessageOpen(Intent intent, CompletionListener completionListener);

Kotlin

MobileEngage.trackMessageOpen(intent: Intent)

↓

Emarsys.Push.trackMessageOpen(intent: Intent, completionListener: CompletionListener? = null)

setStatusListener

The MobileEngage.setStatusListener method was removed, you can now specify a CompletionListener for each method instead.