How anonymous identities work in the mobile SDKs

The mobile SDKs have two ways of creating end users. One type of end user is identified using an anonymous identity. The other type of end user is authenticated with a JWT identity.

Note the difference in terminology here, namely identified versus authenticated. Anonymous end users are untrusted and have some access restrictions. The rest of this article assumes that your SDK application is configured in Zendesk Support for anonymous identities.

Topics covered in this article:

• Lifecycle of an anonymous identity
• Email, name, and resolution strategies
• Frequently encountered issues

An anonymous identity can be created with absolutely no personally identifiable information. A UUID is created when you set an identity in the SDK, and this is used to identify the user.

Glossary

UUID - Universally unique identifier

Related docs

• Set an identity (iOS SDK)
• Set an identity (Android SDK)
• Authentication decision
• User identification decision

Lifecycle of an anonymous identity

An anonymous identity exists until one of the following events happens: 

• A request is made by the SDK that results in a 401 error
• The identity is updated in code
• The app is uninstalled, or the app's app-data is cleared

Each event is described in more details below. The identity is deleted after any of these events. The next identity that you create will be a new user.

401 HTTP error is encountered in a network request

The goal of anonymous identities is for them to exist as long as possible. If no details of the identity changes, then a new end user doesn't have to be created in Zendesk Support. A 401 error means that the end user doesn't have access to the requested resource anymore. This can happen for many reasons, such as the end user being suspended. When a 401 happens, the SDKs take the following steps:

• Deletes the user's requests from the device
• Deletes the stored access token (used for API calls)
• Generates a new UUID.

Identity changes

The SDKs are very strict when it comes to changing identities. We don't support adding data to an identity without considering it as a new identity. This is a common scenario where the integrators of our SDKs might not know their users at the start, but they would after their login process.

Consider if you start with something like this:

// Android: Create an identity with no additional information
Identity identity = new AnonymousIdentity();
Zendesk.INSTANCE.setIdentity(identity);

// iOS: Create an identity with no additional information
let identity = Identity.createAnonymous()
Zendesk.instance?.setIdentity(identity)

If at a later point you do the following, then the SDK treats this as a change of identity. It clears the user's data from the device. The SDK considers any addition (no email to having an email) or any change ([email protected] to [email protected]) as a new identity.

// Android: naive attempt at updating the identity
Identity identity = new AnonymousIdentity.Builder()
    .withEmailIdentifier("[email protected]")
    .build();
Zendesk.INSTANCE.setIdentity(identity);

// iOS: naive attempt at updating the identity
let identity = Identity.createAnonymous(email: "[email protected]")
Zendesk.instance?.setIdentity(identity)

Note: If you keep the same email address and change something else, you can only make up to 1000 identity changes. Example: Suppose that on launch your app initializes an anonymous identity where the email address "[email protected]" is hard-coded but the user name is set dynamically. Result: Every time a different user launches the app, the existing identity for "[email protected]" is deleted and a new identity with a different name is created for "[email protected]". After 1000 such identity changes, you'll start receiving failed login attempt messages.

App is uninstalled, or the app's data is cleared

The identity, requests, and access token are stored locally on the end user's device. If the app is uninstalled, then the identity, requests, access token, and any other user data is cleared. The same happens if the app's data is cleared.

Email, name, and resolution strategies

An anonymous identity allows for some optional information to be specified, but it can be quite confusing to figure out how it actually works. In general, there are always two cases you need to consider:

1. Is this a new user?
2. Is this an existing user?

This is really important because if it's an existing user, then the SDK doesn't update the end user. Here's an example.

Making a new user

Let's say you have a user with the email address of [email protected]. He doesn't exist in your instance of Zendesk Support yet. In your app, you create an anonymous identity for him and set his email address and name:

// Android
Identity identity = new AnonymousIdentity.Builder()
    .withNameIdentifier("John Smith")
    .withEmailIdentifier("[email protected]")
    .build();
Zendesk.INSTANCE.setIdentity(identity);

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

This user doesn't already exist in your instance of Zendesk, so a user is created and the name and email address are set to the ones that the SDK provided.

Trying to update the user

At some point in the future, you might want to change the user's name, so you try something like this:

// Android
Identity identity = new AnonymousIdentity.Builder()
    .withNameIdentifier("Joanna Smith")
    .withEmailIdentifier("[email protected]")
    .build();
Zendesk.INSTANCE.setIdentity(identity);

// iOS
let identity = Identity.createAnonymous(name: "Joanna Smith", email: "[email protected]")
Zendesk.instance?.setIdentity(identity)

Reminder:

• This counts as an identity change, so everything said in "Lifecycle of an anonymous identity" above applies
• A user with the email address of "[email protected]" already exists at this point.

Zendesk Support tries to see if the end user exists before creating one. It does this by looking at the optional information passed through the anonymous identity. In the case of the user above, Zendesk Support takes the following steps:

1. Searches for the "[email protected]" email
2. Finds the existing end user
3. Generates a new access token for the end user
4. Leaves the user's name unchanged as "John Smith" rather than changing it to "Joanna Smith"

Zendesk Support does not update an end user when it finds that the user already exists. This is a security measure.

Here's the generalized resolution strategy used by Zendesk Support:

1. Find the user by email.
2. If the user is not found by email, then create the user.

If the end user is found by email, then Zendesk Support ignores the name.

Frequently encountered issues

The most important thing to remember in an anonymous identity is that all information is completely optional. Our recommendation is to only fill in the details that you know you definitely have.

If you need more control over user identities, consider using JWT authentication. See Authentication decision in the SDK integration checklist.