Identifying your users

Identifying your users

Once you've initialized the SDK, you need to tell Zendesk how to identify your users.

Support SDK (Required)

The Support SDK provides two authentication options: "anonymous" identity and JWT. For detailed instructions, see Setting an identity in the Support SDK documentation.

In a nutshell, create either an Anonymous or a Jwt identity, depending on which authentication type was selected on the Mobile SDK page in the Zendesk Support admin.

Import the necessary components, and set the correct identity type:

Swift

import ZendeskCoreSDK

// in a class
let anonymous = Identity.createAnonymous(name: "John Bob", // name is optional
				email: "[email protected]") // email is optional

let authenticated = Identity.createJwt(token: "unique_id")

Objective-C

#import <ZendeskCoreSDK/ZendeskCoreSDK.h>

// in a class
id<ZDKObjCIdentity> anonymous = [[ZDKObjCAnonymous alloc] initWithName:@"John Bob" // name is nullable
                                 			email:@"[email protected]"]; // email is nullable
id<ZDKObjCIdentity> authenticated = [[ZDKObjCJwt alloc] initWithToken:"unique_id"];

Then set this object on the Zendesk singleton:

Swift

Zendesk.instance?.setIdentity(anonymous)

Objective-C

[[ZDKClassicZendesk instance] setIdentity:anonymous];

Once you've set an identity, see Support engine for instructions on starting the MessagingViewController with an instance of SupportEngine.

Chat SDK (Optional)

Like the Support and Answer Bot SDK, the Chat SDK supports both anonymous and authenticated users with JWT. An anonymous identity is created automatically if JWT authentication is not used. You can provide visitor information to the chat backend with VisitorInfo for an anonymous session. Configuring chat session with VisitorInfo for an authenticated user will be discarded by the backend.

For an in-depth walkthrough on setting up Chat authentication, follow the article. Or you can take a look at the sample app.

To create a JWT identity for your end user, you will first need to conform to the JWTAuthenticator object protocol. The class that conforms to the protocol must contain the getToken function. This is where you should retrieve the JWT from your service:

Swift

import ChatProvidersSDK

final class JWTAuth: NSObject, JWTAuthenticator {
​
    func getToken(_ completion: @escaping (String?, Error?) -> Void) {
	// Call completion block once you get the JWT token
        completion(<"token", <"error">)
    }
}

Objective-C

#import <ChatProvidersSDK/ChatProvidersSDK.h>

@interface ZDKJWTAuth: NSObject<ZDKJWTAuthenticator>

@end
​
@implementation ZDKJWTAuth
​
- (void)getToken:(void (^)(NSString * _Nullable, NSError * _Nullable))completion {
    // Call completion block once you get the JWT token
    completion(<"token">, <"error">);
}
​
@end

After you conform to the protocol, pass an instance of the protocol to the setIdentity function of the Chat instance:

Swift

let authenticator = JWTAuth()
Chat.instance?.setIdentity(authenticator: authenticator)

Objective-C

ZDKJWTAuthenticator *authenticator = [ZDKJWTAuthenticator new];
[ZDKChat.instance setIdentityWithAuthenticator:authenticator];

Error handling in Chat SDK

Chat will call getToken before the chat connects to the backend and validate the authentication token.

If authentication fails the chat will proceed as an anonymous session, and an error will be logged. If the SDK needs to re-authenticate the user at any point during the chat conversation and fails, the current conversation will end, and a new conversation will begin as an anonymous session. In both of these failure cases, the user will appear as non-authenticated to any other parties participating in the chat conversation.

You can observe the authentication errors logged by the Chat SDK by subscribing for notification with name Chat.NotificationAuthenticationFailed.

Authentication error	Description
invalidAccountKey	Invalid account key was provided to Chat SDK
invalidAccessToken	Invalid access token was provided when calling getToken function
invalidEmail	Invalid email was used to generate the JWT token
invalidName	Invalid name was used to generate the JWT token
invalidSharedSecret	Invalid shared secret was used to generate the JWT token
externalUserIdHasChanged	External user id in provided JWT has changed
tokenHasExpired	The provided JWT token has expired

Swift

@objc func authenticationHasFailed(_ notification: Notification) {
    guard let error = notification.userInfo?[NSUnderlyingErrorKey] as? AuthenticationError else { return }

    switch error {
    case .invalidAccessToken(let token):
    // Provided JWT token is invalid

    @unknown default:
       break
    }
}

Objective-C

- (void)authenticationHasFailed:(NSNotification *)notification {
    NSError *error = ((NSError *)notification.userInfo[NSUnderlyingErrorKey]);
    if (error != nil) {
        switch (error.code) {
            case ZDKAuthenticationErrorCodeInvalidAccessToken:
                break;

            default:
                break;
        }
    }
}

Resetting a user's identity in Chat SDK

You can reset the identity of a user which will force a new unique identifier to be generated. This will cause them to be unassociated with the any ongoing chats and the local cache to be discarded. Important This will also cause agents to no longer see previous chats as they will be identified as a new anonymous user.

Swift

Chat.instance?.resetIdentity {
    // Identity was reset
}

Objective-C

[ZDKChat.instance resetIdentity:^{
    // Identity was reset
}];