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.
UUID - Universally unique identifier
- 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.
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 (firstname.lastname@example.org to email@example.com) as a new identity.
// Android: naive attempt at updating the identity Identity identity = new AnonymousIdentity.Builder() .withEmailIdentifier("firstname.lastname@example.org") .build(); Zendesk.INSTANCE.setIdentity(identity);
// iOS: naive attempt at updating the identity let identity = Identity.createAnonymous(email: "email@example.com") 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 "firstname.lastname@example.org" is hard-coded but the user name is set dynamically. Result: Every time a different user launches the app, the existing identity for "email@example.com" is deleted and a new identity with a different name is created for "firstname.lastname@example.org". 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:
- Is this a new user?
- 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@example.com. 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("firstname.lastname@example.org") .build(); Zendesk.INSTANCE.setIdentity(identity);
// iOS let identity = Identity.createAnonymous(name: "John Smith", email: "email@example.com") 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("firstname.lastname@example.org") .build(); Zendesk.INSTANCE.setIdentity(identity);
// iOS let identity = Identity.createAnonymous(name: "Joanna Smith", email: "email@example.com") Zendesk.instance?.setIdentity(identity)
- This counts as an identity change, so everything said in "Lifecycle of an anonymous identity" above applies
- A user with the email address of "firstname.lastname@example.org" 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:
- Searches for the "email@example.com" email
- Finds the existing end user
- Generates a new access token for the end user
- 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:
- Find the user by email.
- 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.