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:

• Anonymous identity
• Unique identity verified using a JWT workflow
• When to set an identity
• Changing the identity

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.

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

Setting an 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

Identity identity = new AnonymousIdentity();
Zendesk.INSTANCE.setIdentity(identity);

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:

Identity identity = new AnonymousIdentity.Builder()
    .withNameIdentifier("John Bob")
    .withEmailIdentifier("[email protected]")
    .build();

Setting a unique identity

If you want only trusted users to access your organization's help center or to submit tickets, your app must supply the SDK with a unique identity for the user. Zendesk must be able to use the identity to verify with your organization that the user is known and trusted. Your organization must provide Zendesk with a dedicated JWT endpoint to verify the identity.

After getting a unique identifier from your app, Zendesk will send it in a request to your dedicated JWT endpoint. Zendesk will expect a response containing a JWT token confirming that the user is known and trusted. 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 set this type of identity in the SDK:

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

• Your organization has a user database and a way for the JWT endpoint to query it. Zendesk will send the unique identifier from your app to the JWT endpoint and wait for your system to look up the user and send a response that the user is known and trusted.

• Your mobile app has access to the unique identifier used to look up the user in the database. The identifier can be whatever you want to use in the query.

A good example of a unique identifier is a user's access token that your app has after your user signs in. We don't recommend using something predictable like an email address or user id.

Setting unique identities

• Add the following statement before the initialization code:

Identity identity = new JwtIdentity("unique_id");
Zendesk.INSTANCE.setIdentity(identity);

The "unique_id" is different for each app user.

See Adding the initialization code.

When to set an identity

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

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

Depending on your use case, you may want to initialize the SDK with an empty identity when your app first launches, and then set a different identity later when you know more about your user.
In this case it's important to make sure not to re-set the empty identity at your next app start-up time, as this would override your user's identity, removing tickets and any other stored information.
A best practice is to keep track of what identity you've set on Zendesk, and make sure not to override it unless the user is different (for example, if your app supports logging in/out of different accounts).

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:

Identity identity = new AnonymousIdentity.Builder()
    .withNameIdentifier("John Bob")
    .build();

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

Identity identity = new AnonymousIdentity.Builder()
    .withNameIdentifier("John Bob")
    .withEmailIdentifier("[email protected]")
    .build();

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