Migrating from the Classic SDK to the Zendesk SDK

Migrating from the Classic SDK to the Zendesk SDK

This guide explains how to migrate from the Classic SDK to the Zendesk SDK for Android. You can run both SDKs side by side in the same application, allowing for a gradual, low-risk migration. This approach lets you incrementally move features and user flows to the Zendesk SDK while maintaining your existing Classic SDK experience.

Why migrate gradually?

Migrating gradually offers several advantages that help ensure a smooth transition from the Classic SDK to the Zendesk SDK.

• Reduced risk: Minimize disruption by migrating features one at a time.
• Easier testing: Test Zendesk SDK features in production alongside Classic SDK.
• Phased rollout: Roll out new experiences to select users or flows before completing the full migration.

Coexistence: Running both SDKs side by side

Compatibility

• Only Classic SDK versions using Messaging 5.3.0 or later support coexistence with the Zendesk SDK.
• Both SDKs can be initialized and used in the same app, but you must avoid conflicts in push notification handling, UI presentation, and configuration.

Best practices

• Namespace your code: Keep Classic and Zendesk SDK integrations in separate modules or classes.
• User segmentation: Route users to either the Classic or Zendesk SDK experience based on feature readiness, user type, or A/B testing.
• Feature toggles: Use remote config or feature flags to control which SDK is used for specific flows.
• Push notifications: Implement separate Firebase Messaging Services for each SDK (see below).

Example: Routing users to Classic or Zendesk SDK

fun showSupportExperience(context: Context, useZendesk: Boolean) {
    if (useZendesk) {
        // Show Zendesk SDK experience
        Zendesk.instance.messaging.showMessaging(context)
    } else {
        // Show Classic SDK experience
        MessagingActivity.builder()
            .withEngines(ChatEngine.engine())
            .show(context, chatConfiguration);
    }
}

Push Notifications: Handling both SDKs

You must implement a custom Firebase proxy service to forward push notifications to both SDKs. See the code samples below:

Zendesk SDK Firebase service:

class ZendeskSDKFirebaseMessagingService : FirebaseMessagingService() {
    // ...existing code...
}

Classic Chat SDK Firebase service:

class ChatSDKFirebaseMessagingService : FirebaseMessagingService() {
    // ...existing code...
}

Proxy Service:

class FirebaseMessagingProxyService : FirebaseMessagingService() {
    private val messagingServices: List<FirebaseMessagingService> by lazy {
        listOf(
            ZendeskSDKFirebaseMessagingService(),
            ChatSDKFirebaseMessagingService()
        ).onEach { it.injectContext(this) }
    }

    override fun onMessageReceived(remoteMessage: RemoteMessage) {
        super.onMessageReceived(remoteMessage)
        messagingServices.forEach { it.onMessageReceived(remoteMessage) }
    }

    //.. other existing callbacks

    private fun <T : Service> T.injectContext(context: T, func: T.() -> Unit = {}) {
        setField("mBase", context)
        func()
    }

    private fun Class<*>.findDeclaredField(name: String): Field? {
        var clazz: Class<*>? = this
        do {
            try {
                return clazz?.getDeclaredField(name)
            } catch (_: Throwable) {
            }
            clazz = clazz?.superclass
        } while (clazz != null)
        return null
    }

    private fun Any.setField(name: String, value: Any): Boolean =
        javaClass.findDeclaredField(name)?.let {
            try {
                it.isAccessible = true
                it.set(this, value)
                true
            } catch (e: Throwable) {
                false
            }
        } ?: false
}

Register the proxy service in your AndroidManifest.xml:

<service
    android:exported="false"
    android:name=".pushnotification.FirebaseMessagingProxyService">
    <intent-filter>
        <action android:name="com.google.firebase.MESSAGING_EVENT" />
    </intent-filter>
</service>

---

Limitations & compatibility

• Some features may require additional steps to avoid conflicts (e.g., push notifications, UI customization).
• Not all Classic SDK features have direct equivalents in the Zendesk SDK.
• See Known Issues for the latest limitations and updates.

---

Demo apps & further reading

• Zendesk SDK Demo Apps
• Zendesk SDK Documentation
• Classic SDK Documentation

---

FAQ

Q: Can I run both the Classic SDK and Zendesk SDK in the same app?
A: Yes. Both SDKs can coexist in the same application, allowing you to migrate features and user flows incrementally.

Q: How do I decide which SDK experience to show to users?
A: Use feature flags, user segmentation, or remote config to route users to either the Classic or Zendesk SDK experience based on readiness or testing needs.

Q: Are there any conflicts or limitations when running both SDKs?
A: Some features, such as push notifications and UI customization, require special handling to avoid conflicts. See Limitations and compatibility.

Q: How do I handle push notifications for both SDKs?
A: Implement a custom Firebase proxy service to forward push notifications to both SDKs. See the code samples in this guide.

Q: Where can I find example apps or more migration help?
A: See the Demo Apps & Further Reading section for links to demo apps and documentation.

By following this guide, you can migrate to the Zendesk SDK at your own pace, minimizing risk and ensuring a smooth transition for your users.