Sunshine Conversations SDK to Zendesk SDK Migration

This article guides you through migrating your iOS app from the Sunshine Conversations SDK to the Zendesk SDK. It highlights key differences, required actions, and provides code samples for both Swift and Objective-C.

Key Differences: Integration ID vs Channel Key

Sunshine Conversations Conversations SDK: Initialization used an integration id.
Zendesk SDK: Requires a channel key obtained from the Zendesk Admin Center.

How to Obtain a Channel Key

Go to the Zendesk Admin Center.
Follow the instructions to create a new messaging channel and obtain your channel key.
Use this channel key to initialize the Zendesk SDK.

Initializing the Zendesk SDK

You must update your initialization code to use the channel key. The Zendesk SDK supports both Swift and Objective-C.

Swift Example

Zendesk.initialize(    channelKey: "<your_channel_key>",    messagingFactory: DefaultMessagingFactory())

Objective-C Example

[Zendesk initializeWithChannelKey:@"<your_channel_key>"                  messagingFactory:[DefaultMessagingFactory new]];

Authentication: Public APIs and setup differences

The Zendesk SDK provides public APIs for authentication, such as loginUser, which require a different setup compared to the Sunshine Conversations SDK. Unlike the Sunshine Conversations SDK, you do not need to pass an external id to the loginUser API, only a valid JWT is required. This simplifies the authentication process and reduces the risk of mismatched identifiers.

You must implement authentication using the Zendesk SDK's APIs and follow the recommended integration steps for secure user login. For details, see the Authentication documentation.

What happens to user data during migration?

When migrating from the Sunshine Conversations SDK to the Zendesk SDK, all existing user sessions—both authenticated and unauthenticated—will be lost after the transition. This means:

Unauthenticated users will lose access to their previous conversations and will start with a fresh session in the Zendesk SDK.
Authenticated users can continue seamlessly, but you must re-authenticate them using the new Zendesk SDK APIs. Their conversations and data will be preserved once they are authenticated again.

Push Notifications

Push notifications are supported in the Zendesk SDK. A similar setup is required as with the Sunshine Conversations SDK. For detailed instructions, see the Push Notifications documentation.

Swift and Objective-C Interop Support

The Zendesk SDK is fully compatible with Swift projects. While you can call the SDK from Objective-C, all new APIs and official support are focused on Swift.

Custom UI Support

Implementing your own UI is not supported in the Zendesk SDKs. Unlike the Sunshine Conversations SDK, which allowed building a custom user interface (see legacy docs), the Zendesk SDK currently does not provide public APIs for custom UI implementations.

Client-side API differences

Below is a high-level comparison of key client-side APIs and features between the Sunshine Conversations SDK and the Zendesk SDK.

Feature / API	Sunshine Conversations SDK	Zendesk SDK
Access user data (e.g., getUser)	Yes	No
Access conversation data (e.g., getConversation)	Yes	No
Programmatically create conversations	Yes	No
`beforeDisplay` message delegate	Yes	No
`beforeSend` message delegate	Yes	No
`beforeNotification` delegate	Yes	No
`invalidAuth` authentication delegate	Yes	No
Access unread messages count	Yes	Yes
Custom UI support	Yes	No
JWT authentication	Yes	Yes
Push notifications	Yes	Yes
UI customization (colors, branding)	Yes	Limited
Swift Support	No	Yes

Key differences:

The Zendesk SDK does not support accessing user or conversation data client-side.
Delegates such as beforeDisplay, beforeSend, beforeNotification and invalidAuth are not supported in the Zendesk SDK.
You cannot programmatically create conversations in the Zendesk SDK.
Custom UI is not currently supported in the Zendesk SDK.

Behavioural Differences

There are important behavioural differences between the Zendesk SDK and the Sunshine Conversations SDK that may impact your migration and user experience:

Conversation Creation:

The Zendesk SDK will automatically create a new conversation whenever the messaging view is displayed, regardless of user action.
The sSunshine Conversations SDK does not force-create a conversation; a conversation is only created when the user takes an explicit action or a conversation is created for them by an agent.

Authentication Handling:

The Zendesk SDK will attempt to create an unauthenticated user automatically if no user is logged in, ensuring the messaging experience is always available.
The Sunshine Conversations SDK will remain in an error state if authentication fails or is not provided, and will not create an unauthenticated user automatically.

Be sure to review these differences and adjust your app's logic and user experience as needed during migration.

Additional Resources

FAQ

Q: Can I use my existing Sunshine Conversations integration id with the Zendesk SDK?
A: No. The Zendesk SDK requires a channel key, which you must create in the Zendesk Admin Center. See the steps above for details.

Q: Does the Zendesk SDK support both Swift and Objective-C?
A: The Zendesk SDK is focused on Swift and all new APIs are designed for Swift. You can call the SDK from Objective-C, but official support are centered on Swift usage.

Q: How do I handle authentication in the Zendesk SDK?
A: The Zendesk SDK provides public APIs such as loginUser for authentication. The setup is different from Sunshine Conversations SDK. See the Authentication documentation for details.

Q: Are push notifications supported in the Zendesk SDK?
A: Yes. Push notifications are supported and require a similar setup as with the Sunshine Conversations SDK. See the Push Notifications documentation for detailed instructions.

Q: Where can I find more migration help or sample code?
A: See the Additional Resources section for links to documentation and demo apps.

Q: What happens to user sessions and conversations when migrating from the Sunshine Conversations SDK to the Zendesk SDK?
A: Unauthenticated users will lose access to previous conversations and start fresh. Authenticated users can continue seamlessly, but you must re-authenticate them using the Zendesk SDK APIs. Unauthenticated sessions are not restored because session data is stored in a different location and cannot be fully recovered.

Q: How is authentication different in the Zendesk SDK?
A: The Zendesk SDK only requires a valid JWT for authentication using the loginUser API. You do not need to pass an external id, unlike the Sunshine Conversations SDK. See the Authentication documentation for details.

Q: What are the main client-side API differences between the SDKs?
A: The Zendesk SDK does not support accessing user or conversation data client-side, does not support delegates like beforeDisplay or beforeSend, and does not allow programmatically creating conversations. Custom UI is not currently supported. See the client-side API differences table above for a detailed comparison.

Q: How does conversation creation differ between the SDKs?
A: The Zendesk SDK automatically creates a new conversation whenever the messaging view is displayed. The Sunshine Conversations SDK only creates a conversation when the user takes an explicit action or an agent creates one for them.

Q: How does unauthenticated user handling differ?
A: The Zendesk SDK will attempt to create an unauthenticated user automatically if no user is logged in, ensuring messaging is always available. The Sunshine Conversations SDK will remain in an error state if authentication fails or is not provided, and will not create an unauthenticated user automatically.