Invalidating and switching SDK instances

Introduction

Invalidating a Zendesk SDK instance on Android means stopping and cleaning up the current SDK session. This process removes user data, closes real-time connections, and ensures that no further messages or notifications are received until the SDK is re-initialized. You may need to invalidate the SDK to protect user privacy, switch between brands or environments, or reset the SDK state.

Switching between SDK instances allows your app to support multiple Zendesk brands, environments, or user contexts at runtime. This is useful for applications that need to dynamically change the Zendesk configuration, such as multi-brand apps or apps that allow users to switch accounts. Properly invalidating the current instance before initializing a new one ensures data isolation and prevents issues with user state, push notifications, or conversation continuity.

When should you invalidate the SDK?

Common use cases include:

• Switching brands or environments: If your app supports multiple Zendesk brands or environments, invalidate the current instance before initializing a new one.
• Clearing sensitive data: When handling sensitive information, invalidate the SDK to ensure no data persists locally.

Important: Calling Zendesk.instance.invalidate() only clears local SDK state and does not log out a user authenticated with a JWT. The user's session on the backend remains active unless you explicitly log out using the appropriate API.

Logging out a JWT-authenticated user

To properly log out a user authenticated with a JWT:

• Call the SDK's logoutUser() method to end the session and remove the JWT from the SDK.
• If your app manages JWTs directly, ensure you also invalidate the JWT on your backend and remove it from local storage.
• After logging out, call Zendesk.instance.invalidate() to clear all local SDK data and connections.

Differences between invalidate() and logout

• invalidate() clears local SDK state, user data, and closes connections, but does not log out a JWT user on the backend.
• logoutUser() should be used to end the user's session and invalidate the JWT both locally and on the backend.

Important caveats when switching instances

• After invalidation, no messages or notifications will be received until the SDK is re-initialized.
• All local data (including conversations and user state) is cleared on invalidation. There is no option to retain cached data.
• Push notifications received after invalidation will not be processed until the SDK is re-initialized.
• Switching between instances without proper invalidation can lead to data leaks, user state confusion, or conversation continuity issues.

Code samples

Invalidate the SDK

Zendesk.instance.invalidate()

Switching between instances

// Invalidate the current instance
Zendesk.getInstance().invalidate();
// Initialize a new instance with a different brand or environment
Zendesk.initialize(this, "NEW_CHANNEL_KEY");

Push notifications for switching between instances

No additional setup is required to switch between instances. However, an API is available to validate incoming push notifications for the currently active instance.

To handle push notifications for switching instances, add the following API to your custom implementation of the FirebaseMessagingService:

PushNotifications.validatePushIntegration(context: Context, messageData: Map<String, String>)

This API will need to be called in the onMessageReceived method when a push notification will be displayed.

Kotlin

class SampleMessagingService : FirebaseMessagingService() {

    override fun onMessageReceived(remoteMessage: RemoteMessage) {
    	val responsibility = PushNotifications.shouldBeDisplayed(remoteMessage.data)
        when (responsibility) {
            MESSAGING_SHOULD_DISPLAY -> {
                // The push needs to be validated that it belongs to the current SDK instance.
                if (PushNotifications.validatePushIntegration(this, remoteMessage.data)) {
                    // This push has been validated and it belongs to Messaging so the SDK is able to display it to the end user
                    PushNotifications.displayNotification(
                        context = this,
                        messageData = remoteMessage.data,
                    )
                } else {
                    // This push does not belong to the current SDK instance and should not be displayed.
                }
            }

            }
            MESSAGING_SHOULD_NOT_DISPLAY -> {
                // This push belongs to Messaging but it should not be displayed to the end user
            }
            NOT_FROM_MESSAGING -> {
                // This push does not belong to Messaging
            }
        }
    }
}

Java

public class SampleMessagingService extends FirebaseMessagingService {

	@Override
	public void onMessageReceived(@NonNull RemoteMessage remoteMessage) {
		PushResponsibility responsibility = PushNotifications.shouldBeDisplayed(remoteMessage.getData());
		switch (responsibility) {
			case MESSAGING_SHOULD_DISPLAY:
			// The push needs to be validated that it belongs to the current SDK instance.
                if (PushNotifications.validatePushIntegration(this, remoteMessage.getData())) {
                    // This push has been validated and it belongs to Messaging so the SDK is able to display it to the end user
                    PushNotifications.displayNotification(this, remoteMessage.getData());
                } else {
                    // This push does not belong to the current SDK instance and should not be displayed.
                }
                break;
            case MESSAGING_SHOULD_NOT_DISPLAY:
            	// This push belongs to Messaging but it should not be displayed to the end user
            	break;
            case NOT_FROM_MESSAGING:
                // This push does not belong to Messaging
                break;
		}
	}
}