Skip to main content

Migration Steps

Follow these steps to migrate from the SAP Emarsys SDKs to the SAP Engagement Cloud SDK. Where relevant, the SAP Emarsys SDK's approach is shown for comparison.

1. Installing and Removing Dependencies​

Install the SAP Engagement Cloud SDK by adding it as a dependency:

// Ensure required repositories in settings.gradle.kts
pluginManagement {
    repositories {
        google()
        mavenCentral()
    }
}

// module build.gradle.kts
dependencies {
  implementation("com.sap.engagement-cloud:engagement-cloud-sdk-android:<latest-version>")
}

Remove the com.emarsys:android-emarsys-sdk dependency and any related artifact lines.

Simplified setup

The SAP Engagement Cloud SDK's FCM and HMS library modules include push messaging service declarations in their AndroidManifest.xml files. These are merged into your app automatically — you can remove any manual *MessagingService or <service> entries from your AndroidManifest.xml. The SDK also ships consumer ProGuard rules in the AAR, so no manual keep rules are needed.

2. Initializing the SDK​

On Android, EngagementCloud.initialize() is called automatically. There is no need to call it manually.

class MyApp: Application() {
  override fun onCreate() {
    super.onCreate()
    // Enable tracking once consent is given and the application code is available
    EngagementCloud.setup.enable(AndroidEngagementCloudSDKConfig(
      applicationCode = "ABCDE-12345",
      launchActivityClass = MainActivity::class.java
    ))
  }
}

3. Identifying Contacts​

The SAP Emarsys SDK's setContact, setAuthenticatedContact, and clearContact methods are replaced by link, linkAuthenticated, and unlink in the SAP Engagement Cloud SDK.

EngagementCloud.contact.link(contactFieldValue)
EngagementCloud.contact.linkAuthenticated(openIdToken)
EngagementCloud.contact.unlink()
info
  • Linking after enable() ensures events are associated correctly.
  • OpenID linking for contact authentication behaves the same as before.

4. Handling Push Tokens​

The SAP Emarsys SDK's setPushToken, clearPushToken, and getPushToken methods are replaced by registerToken, clearToken, and getToken in the SAP Engagement Cloud SDK.

// In FirebaseMessagingService
override fun onNewToken(token: String) {
  EngagementCloud.push.registerToken(token)
}

EngagementCloud.push.clearToken()

If required, retrieve the current token:

  val token = EngagementCloud.push.getToken().getOrNull()

5. Sending Custom Events​

The SAP Emarsys SDK's trackCustomEvent method is replaced by constructing a CustomEvent and passing it to EngagementCloud.event.track in the SAP Engagement Cloud SDK.

  EngagementCloud.event.track(CustomEvent(name, attributes))

6. Controlling In-App Messaging​

The pause, resume, and isPaused methods for in-app messaging work the same way in both SDKs.

// Identical use for both SDKs, just update dependency
if (!EngagementCloud.inApp.isPaused) {
  EngagementCloud.inApp.pause()
}
// Later, when you're ready
EngagementCloud.inApp.resume()

Inline In-App Callbacks​

The SAP Emarsys SDK provided callbacks for inline in-app messages to track lifecycle events. The SAP Engagement Cloud SDK supports similar callbacks with updated naming.

SAP Emarsys SDK Callbacks​

The SAP Emarsys SDK used onCompletion, onClose, and onEvent callbacks:

// SAP Emarsys SDK
InlineInAppView(context).apply {
  loadInApp(inApp)
  this.onCompletionListener {
    /* message loaded */
  }
  this.onCloseListener = {
    /* message closed */
  }
  this.onAppEventListener = { property, json ->
    /* handling AppEvents */
  }
}

SAP Engagement Cloud SDK Callbacks​

The SAP Engagement Cloud SDK uses onLoaded and onClose callbacks:

// SAP Engagement Cloud SDK
InlineInAppView(
    viewId = "view-id",
    onLoaded = {
        // Called when message finishes loading
        println("Message loaded")
    },
    onClose = {
        // Called when message is closed
        println("Message closed")
    }
)

Callback Mapping​

SAP Emarsys SDK CallbackSAP Engagement Cloud SDK CallbackDescription
onCompletiononLoadedCalled after message finishes loading
onCloseonCloseCalled when message is closed
onEventUse EngagementCloud.events insteadFor interaction events, subscribe to the global events flow
tip

For tracking interaction events like button clicks, use the EngagementCloud.events API to subscribe to SDK events. This provides a unified event stream for all SDK interactions rather than per-view callbacks. App Events are extended with a source property to make it easy to filter events by origin (for example, only events from in-app interactions).

// Subscribe to SDK events for interaction tracking
lifecycleScope.launch {
    EngagementCloud.events.collect { event ->
        when (event) {
            is AppEvent -> {
                // handle app event
            }
            else -> {}
        }
    }
}

The SAP Emarsys SDK's trackDeepLink method is replaced by deepLink.track in the SAP Engagement Cloud SDK.

// In your Activity's onNewIntent
EngagementCloud.deepLink.track(this, intent)

8. Reactive Event Stream and onEventAction Handlers​

The SAP Emarsys SDK's onEventAction handlers are replaced by the reactive EngagementCloud.events stream in the SAP Engagement Cloud SDK.

lifecycleScope.launch {
  EngagementCloud.events.collect { event ->
    when (event) {
      is AppEvent -> // Handle event
      is BadgeCountEvent -> // Update badge
      else -> <...>
    }
  }
}

9. Checklist for Validating the Migration​

Check the following to validate that your migration is complete:

  • Initialization does not trigger network calls before you call enable().
  • Contact linking returns a successful result.
  • Push token appears in the SAP Engagement Cloud system. To verify, you can use SDK Events on the App Management page or in the logs.
  • Custom events are visible in analytics.
  • Deep links are being tracked.
  • In-app pause() and resume() calls work as expected.

10. Changes in Error Handling​

The SAP Emarsys SDK used completion listeners and blocks with nullable error objects. The SAP Engagement Cloud SDK replaces them with suspend and async functions, enabling easier composition with coroutines and async/await. These functions return typed results:

  • Success: result.isSuccess or try? await (Swift) / .getOrThrow() (Kotlin).
  • Failure: Inspect result.exceptionOrNull() or catch the thrown error if using .getOrThrow().

Example:

EngagementCloud.contact.link(contactFieldValue).onFailure { e ->
  // Log or retry
}

Next Steps​