Introduction
Since we have released the current major version of the Emarsys SDK we have received a lot of valuable usage feedback from our users. 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 introducing 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 3.0.0, or the latest 3.8.1 version. We estimate that this migration can be done in about 60 minutes. We recommend doing 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 have 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()The following eventHandlers cannot be set anymore in the Config:
notificationEventHandlerinappEventHandler
To set the eventHandlers, see EventHandlers.
EventHandlers
From version 3.0.0 you can use the following:
Emarsys.push.setNotificationEventHandlerEmarsys.push.setSilentMessageEventHandlerEmarsys.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 have 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.languageCodeWe have converted our config interfaces to Kotlin. Usage from Java has not changed, but from Kotlin all getter-setter functions are now properties instead of functions.
setContact, setAuthenticatedContact
With Emarsys SDK 3.0.0 we have moved the contactFieldId from the setup to the setContact/setAuthenticatedContact call to give more flexibility. 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 -> {}}We renamed contactId parameter to contactFieldValue in the setContact method.
Push Providers in Emarsys SDK 3.0.0
With 3.0.0 we have 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
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, its 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 paragraph 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
changeApplicationCode(<applicationCode: String>, <contactFieldId: Int>)andchangeApplicationCode(<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 has not 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.
Before:
fun recommendProducts(recommendationLogic: Logic,
recommendationFilters: List<RecommendationFilter>,
limit: Int,
availabilityZone: String,
resultListener: ResultListener<Try<List<Product>>>)After:
fun recommendProducts(logic: Logic,
filters: List<RecommendationFilter>,
limit: Int,
availabilityZone: String,
resultListener: ResultListener<Try<List<Product>>>)