DocumentationAPI Reference

Invalidating and switching SDK instances

Introduction

Invalidating a Zendesk SDK instance 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. Integrators 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.

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.

Invalidate with or without clearing storage

When you need to invalidate the Support SDK, it's important to understand the difference between doing so with or without clearing storage.

With clearing storage

This option completely removes all user data, conversations, and cached information from the device. It is best used when a user logs out, switches accounts, or when you need to ensure sensitive data is fully erased for privacy reasons.

Without clearing storage

This option stops the SDK's activity but preserves cached data and conversations on the device. It’s useful if you want to temporarily disable the SDK while retaining user and session information for future use.

Important caveats when switching instances

  • After invalidation, no messages or notifications will be received until the SDK is re-initialized.
  • If you clear storage, all local data (including conversations and user state) is lost. If you do not clear storage, some data may persist and be reused on re-initialization.
  • 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

Swift – Invalidate with clearing storage

Zendesk.instance?.invalidate(clearStorage: true)

Swift – Invalidate without clearing storage

Zendesk.instance?.invalidate(clearStorage: false)

Swift – Switching between instances

// Invalidate the current instanceZendesk.instance?.invalidate(clearStorage: true)// Initialize a new instance with a different brand or environmentZendesk.initialize(channelKey: "NEW_CHANNEL_KEY")

Objective-C – Invalidate with clearing storage

[[Zendesk instance] invalidateWithClearStorage:YES];

Objective-C – Invalidate without clearing storage

[[Zendesk instance] invalidateWithClearStorage:NO];

Objective-C – Switching between instances

// Invalidate the current instance[[Zendesk instance] invalidateWithClearStorage:YES];// Initialize a new instance with a different brand or environment[Zendesk initializeWithChannelKey:@"NEW_CHANNEL_KEY"];