DocumentationAPI Reference

Setting an identity (Required)

Setting an identity (Required)

To access your organization's help center or to submit tickets, a user of your app must have an identity so they can authenticate as a Zendesk Support user. You can set two types of identities for a user:

To determine which option is best for your organization, see Authentication decision in the SDK integration checklist.

On the Zendesk Support side, an administrator must enable the chosen option in the admin interface. If you're a Zendesk Support admin, see Registering the application in Zendesk Support in Zendesk help. Make sure the identity type you set in the SDK matches the type set in the admin interface. Mismatched identity types will cause the SDK network calls to fail with an error.

Note: The Zendesk Support SDK is intended for end users only. Authenticating with an agent email address returns a 403 authentication error. Be aware of this when testing your integration.

Anonymous identity

Use this option if you don't know, or don't need to know, the details of the end user. For details, see Authentication decision in the SDK integration checklist. See How anonymous identities work in the mobile SDKs for more information about the lifecycle of an anonymous identity.

To set an anonymous identity

Swift

let identity = Identity.createAnonymous()Zendesk.instance?.setIdentity(identity)

Objective-C

id<ZDKObjCIdentity> userIdentity = [[ZDKObjCAnonymous alloc] initWithName:nil email:nil];[[ZDKClassicZendesk instance] setIdentity:userIdentity];

Adding identifying information to an anonymous identity

Even though the identity is anonymous, you can add the end user's name and email address to the identity. To decide whether or not to add this information, see User identification decision in the SDK integration checklist.

Note the following if you decide to add the information:

  • Including an email address in the anonymous identity ensures that any new tickets are linked to the user profile in Zendesk Support with that email address.
  • End users will only see the tickets they created on the mobile device with the Support SDK. This is because an anonymous identity is an untrusted one.
  • Tickets created using an anonymous identity are flagged with warning to agents so that they know the end user wasn't signed in when they created the ticket.

Note: If you need to comply with the Federal Trade Commission's Children's Online Privacy Protection Act (COPPA), consider not providing any identifying information.

To add identifying information

  • Define the identity as follows:

    Swift

    let identity = Identity.createAnonymous(name: "John Bob", email: "[email protected]")Zendesk.instance?.setIdentity(identity)

    Objective-C

    id<ZDKObjCIdentity> userIdentity = [[ZDKObjCAnonymous alloc] initWithName:@"John Bob"                                                                    email:@"[email protected]"];[[ZDKClassicZendesk instance] setIdentity:userIdentity];

Verified identity

If you want only verified users to access your organization's help center or to submit tickets, your app must supply the SDK with a user token for each user. A good example of a user token is an opaque user access token that your app receives after a user signs in.

Zendesk forwards the user token to your system for verification. In your Mobile SDK configuration, provide Zendesk with a JWT URL endpoint that will be used for verifying the user token. After getting a user token from your app, Zendesk sends it in a request to your dedicated JWT URL. Zendesk expects a response containing a JWT token confirming that the user is authenticated. The token must include name and email properties.

Here's the JWT authentication flow (enlarge):

See Building a dedicated JWT endpoint for the Support SDK.

Requirements

You must meet the following requirements to use verified identities in the SDK:

  • Your mobile app has a means to access a user token after the user has logged in to the app.

  • Your organization maintains a dedicated JWT endpoint for the Support SDK. See Building a dedicated JWT endpoint for the Support SDK.

  • The JWT endpoint must have a means of validating user tokens. Zendesk will send the user token from your app to the JWT endpoint and wait for your system to verify it.

  • The JWT endpoint must be able to query a user database in order to fetch the user's name and email.

  • The JWT endpoint must be configured with a JWT signing key, which it will use to generate the JWT response.

Setting verified identities

  • Add the following statement before you use the Zendesk SDK:

    Swift

    let identity = Identity.createJwt(token: "user_token")Zendesk.instance?.setIdentity(identity)

    Objective-C

    id<ZDKObjCIdentity> userIdentity = [[ZDKObjCJwt alloc] initWithToken:"user_token"];[[ZDKClassicZendesk instance] setIdentity:userIdentity];

    See Adding the initialization code.

When to set an identity

An identity must be set after Zendesk.initialize but before any action that interacts with the Zendesk back-end (such as showing the help center or ticketing, or using one of the API providers)

You can set it either before or after Support.initialize, but attempting to use the Support SDK without setting an identity will cause all network requests to fail.

Changing the identity

You can change the identity at any time by calling Zendesk.instance?.setIdentity again with a different identity object. Calling the method more than once with the same identity will have no effect.

If using an anonymous identity, there are some important caveats to consider when changing identities:

  • Changing the identity will result in all data being wiped from the Support SDK's storage. Any open tickets will be lost and can never be accessed through the SDK again, even if you set the same identity again later.

  • Any change to an anonymous identity's details will be treated as a change of identity rather than updating the current identity. Consider the scenario where you are initially creating the identity using only the user's name:

    let identity = Identity.createAnonymous(name: "John Bob", email: nil)

After finding out the user's email address later, you set the identity with the updated details

let identity = Identity.createAnonymous(name: "John Bob", email: "[email protected]")

The SDK treats this as a completely new user, and deletes any stored data (such as ticket IDs, which cannot be retrieved again).