Migration guide for Emarsys SDK 3.0.0

Introduction

We released the current major version of the Emarsys SDK two years ago. In the meantime we have received a lot of valuable usage feedback from our users and 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 SDK integration to start using the latest 3.0.0 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 SDK 3.0.0

Huawei Push Kit can be integrated through the Emarsys SDK which makes it possible to send push notification from Emarsys to users of newer Huawei devices while working simultaneously also with Firebase to reach Google Android phones
Updated dependencies
Java 8 usage
Cleaner and improved API
Improved the usage of callbacks in Kotlin and Java as well
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

Updated dependencies

Emarsys SDK 3.0.0 forces Java 1.8 usage and we’ve upgraded our Kotlin runtime to the latest version (1.5.x)

If your application does not use Kotlin or Java 1.8 add the following code to your build.gradle.

compileOptions {
    sourceCompatibility JavaVersion.VERSION_1_8
    targetCompatibility JavaVersion.VERSION_1_8
}
kotlinOptions {
    jvmTarget = JavaVersion.VERSION_1_8
}

Lambda functions

In Emarsys SDK we always pay attention to keep the API as easy to use as possible, with 3.0.0 we made every callback we use a Functional Interface so you can use them as lambda functions from both Java 8 and Kotlin.

Before:

Emarsys.trackCustomEvent(eventName, attributes, CompletionListener(){
  @Override
  public void onCompleted(Throwable throwable){
  
  }
});

After:

Emarsys.trackCustomEvent(eventName, attributes,(throwable)->{});

This also means that all Kotlin lambda-based methods have been removed from our API since Functional Interfaces can be used as Kotlin lambda out of the box.

Setup

EmarsysConfig got support for a constructor with default named parameters for a more convenient Kotlin experience. Java users should still use our Builder-based solution.

The Builder has been also modified, mobileEngageApplicationCode was renamed to applicationCode while predictMerchantId is now called merchantId. We have also moved the contactFieldId from the setup to the setContact call.

Also, all the deprecated methods have been removed from our Config-like setters for our EventHandlers.

EmarsysConfig(application=application,
        applicationCode=APP_CODE,
        merchantId=MERCHANT_ID,
        sharedSecret=SHARED_SECRET,
        sharedPackageNames=SHARED_PACKAGE_NAMES,
        enableVerboseConsoleLogging=true)

EmarsysConfig.Builder()
                .application(this)
                .applicationCode(APP_CODE)
                .sharedSecret(SHARED_SECRET)
                .sharedPackageNames(SHARED_PACKAGE_NAMES)
                .enableVerboseConsoleLogging()
              .build()

This means that the following eventHandlers cannot be set anymore in the Config:

notificationEventHandler
inappEventHandler

To set the eventHandlers follow the guide in the next section.

EventHandlers

From 3.0.0 you can use

Emarsys.push.setNotificationEventHandler
Emarsys.push.setSilentMessageEventHandler
Emarsys.inApp.setEventHandler

instead of setting these eventHandlers during the setup.

Since the SDK now uses Java 8, these eventHandlers can be set as lambda functions in Java as well, just like in Kotlin.

Example in Java:

Emarsys.inapp.setEventHandler((context, name, payload) -> {});

Config

We’ve generalized the naming between the Android and iOS SDK so language has changed to languageCode. This means a minor change in accessing this property:

Emarsys.getConfig.getLanguageCode();

Emarsys.config.languageCode

We’ve converted our config interfaces to Kotlin. Usage from Java hasn’t changed, but from Kotlin all getter-setter functions are now properties instead of functions.

setContact, setAuthenticatedContact

With Emarsys SDK 3.0.0 we’ve moved the contactFieldId from the setup to the setContact/setAuthenticatedContact call to give more flexibility into the developer’s hand 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 setContact/setAuthenticatedContact methods are not available anymore. To migrate, please extend the setContact/setAuthenticatedContact call with the contactFieldId, like this:

Emarsys.setContact(<contactFieldId: Int>,
                   <contactFieldValue: String>) {throwable -> {}}

Emarsys.setAuthenticatedContact(<contactFieldId: Int>,
                                <openIdToken: String>) {throwable -> {}}

Also, we renamed contactId parameter to contactFieldValue in the setContact method.

Push Providers in Emarsys SDK 3.0.0

With 3.0.0 we've added Huawei Push Kit as a new Push Provider to the SDK. From now on developers can freely choose between these providers or use both at the same time. Because of this, we've made some changes on how to integrate Firebase with our SDK.

Firebase

Note: This is an additional dependency, which points to a new module for the Emarsys SDK, to work with Firebase.

Since Firebase is not a mandatory dependency anymore, it’s needed to be added explicitly so please include emarsys-firebase like the example below:

implementation 'com.emarsys:emarsys-firebase:<latest-version>'
implementation 'com.emarsys:emarsys-sdk:<latest-version>'

EmarsysMessagingService is renamed to EmarsysFirebaseMessagingService, EmarsysMessagingServiceUtils to EmarsysFirebaseMessagingServiceUtils.

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

Huawei

For information about the Huawei integration, please check the related pharagraph in our readme.

Push

OnMessageOpen

Emarsys.push.onMessageOpen has been removed since creating a MessagingService and calling into our EmarsysFirebaseMessagingServiceUtils was already the recommended solution for a while now to intercept incoming push messages, while tracking is automatically handled by the SDK.

changeApplicationCode

Note

changeApplicationCode(<applicationCode: String>, <contactFieldId: Int>) and changeApplicationCode(<applicationCode: String>, <contactFieldId: Int>, <completionListener: CompletionListener>) method has been removed

We simplified the changeApplicationCode by removing the methods with the contactFieldId. contactFieldId is now part of the setContact.

Java

Emarsys.getConfig().changeApplicationCode(<applicationCode: String>, <completionListener: CompletionListener> )

Kotlin

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.

Predict

Our Predict API has been converted to Kotlin which might break your implementation.

Usage from Java hasn’t changed(except the parameter renaming), but from Kotlin all getter-setter functions are now properties instead of functions.

Recommendation function parameter renamings:

We renamed some of the parameters of the recommendation functions. recommendationLogic is shortened to logic, recommendationFilters is shortened to filters.