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 iOS. Both SDKs can run 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.0.0, Support 7.0.0, Answerbot 4.0.0, and Chat 4.0.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 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.

Example: Routing users to Classic or Zendesk SDK

func showSupportExperience(useZendesk: Bool, from viewController: UIViewController) {
    if useZendesk {
        // Show Zendesk SDK experience
        guard let viewController = Zendesk.instance?.messaging?.messagingViewController() else { return }
        self.navigationController?.show(viewController, sender: self)
    } else {
        // Show Classic SDK experience
        let messagingConfiguration = MessagingConfiguration()
        let chatEngine = try ChatEngine.engine()
        let viewController = try Messaging.instance.buildUI(engines: [chatEngine],
                                configs: [messagingConfiguration])
        self.navigationController?.pushViewController(viewController, animated: true)
    }
}

Limitations and compatibility

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

Objective-C headers update

As part of this migration, the Objective-C headers have been updated to improve compatibility and integration with the Zendesk SDK. For details on the changes, see the migration guide: Updated Objective-C headers

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 UI customization, require special handling to avoid conflicts. See Limitations and compatibility.

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.