Skip to content

Migrate from Mobile Engage

Jump to bottom
szabist edited this page Mar 2, 2020 · 11 revisions

Contents

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

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 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 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 set up 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 can also be removed when building the config.

Methods

enableExperimentalFeatures

The Emarsys SDK integrates InApp by default, there is no need for any additional settings.

credentials

Java
EmarsysConfig config = new EmarsysConfig.Builder()
  ...
  .credentials(applicationCode, applicationPassword)
  ...
  .build();

  Emarsys.setup(config);

↓

EmarsysConfig config = new EmarsysConfig.Builder()
  ...
  .mobileEngageApplicationCode(applicationCode)
  ...
  .build();

  Emarsys.setup(config);
Kotlin
EmarsysConfig config = EmarsysConfig.Builder()
  ...
  .credentials(applicationCode, applicationPassword)
  ...
  .build()

  Emarsys.setup(config)

↓

EmarsysConfig config = EmarsysConfig.Builder()
  ...
  .mobileEngageApplicationCode(applicationCode)
  ...
  .build()

  Emarsys.setup(config)

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 Emarsys SDK. The contactFieldId is the Field ID in the Emarsys contact database of the field created for identifying mobile users. Check out this guideline for more details.

Java
MobileEngage.appLogin(contactFieldId, contactFieldvalue)

↓

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

  Emarsys.setup(config)

  Emarsys.setContact(String contactFieldValue);
Kotlin
MobileEngage.appLogin(contactFieldId, contactFieldvalue)

↓

val config = EmarsysConfig.Builder()
  ...
  .contactFieldId(contactFieldId)
  ...
  .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.

Clone this wiki locally