User identification

The Mapp Engage Flutter plugin supports a device-first identification model. After initialization, each device starts with an anonymous AUTO alias. When a user signs in, you can replace that alias with a known identifier to associate the device with a Mapp contact.

This guide explains how to identify users, when to update aliases, and how to handle logout correctly.

How user identification works

When the SDK is initialized, the device is registered with an anonymous AUTO alias. This alias allows the SDK to operate before the user is known.

Once the user signs in, call setAlias() to replace the AUTO alias with a known identifier such as an email address or customer ID.

After that, the device is associated with the resolved contact and future engagement data is linked to that identity.

Get the current alias

Use getAlias() to retrieve the alias currently assigned to the device.

final String alias = await MappSdk.getAlias();
print('Current alias: $alias');

Before login, this usually returns the AUTO alias. After login, it returns the alias you assigned with setAlias().

Set a known alias after login

Call setAlias() after a successful login or after your application can reliably identify the user.

await MappSdk.setAlias('user@example.com');

When you set a known alias:

• The AUTO alias is replaced

• The device is associated with the supplied identifier

• The SDK can attach the device to an existing Mapp contact or create a new one

Use an identifier that is stable and unique for the user in your system.

When to call setAlias()

The correct moment to call setAlias() is after user authentication has completed successfully.

A typical flow looks like this:

1. Initialize the SDK on app launch

2. Let the device operate with its AUTO alias

3. Authenticate the user in your application

4. Call setAlias() with the resolved user identifier

Do not call setAlias() before the app can reliably identify the user.

Resend custom attributes after alias changes

If your app stores custom attributes before the user signs in, you can use setAliasWithResend() to re-send those attributes after the alias is updated.

await MappSdk.setAliasWithResend('user@example.com', true);

The second argument controls whether previously stored custom attributes are sent again after the alias change.

This is useful when attributes were collected while the device was still anonymous and should also be associated with the resolved contact.

Handle logout correctly

Use logOut() when the user signs out of your application.

await MappSdk.logOut(false);

The method accepts a positional boolean argument.

When logout is completed:

• The user alias is removed

• The device is detached from the identified contact

• A new AUTO alias is assigned

• Push behavior follows the pushEnabled argument

Do not use an empty alias to reset identity

Do not pass an empty string to setAlias() to return the device to anonymous state.

Use logOut() instead. This ensures that the SDK resets the identification state correctly and restores a new AUTO alias for the device.

Recommended identification flow

1. Initialize the SDK on app start

2. Allow the device to register with its AUTO alias

3. Set a known alias after login

4. Update tags and custom attributes as needed for the identified contact

5. Call logOut() when the user signs out

This approach keeps anonymous and identified states clearly separated and supports a predictable engagement lifecycle.

Common mistakes

• Calling setAlias() before the user is authenticated

• Using setAlias() with an empty value to simulate logout

• Forgetting to call logOut() on sign-out

• Using a non-unique alias value

• Skipping setAliasWithResend() when previously stored custom attributes should be associated with the identified contact

Best practices

• Use a stable and unique identifier for aliases

• Call setAlias() only after successful authentication

• Use setAliasWithResend() when anonymous custom attributes should be preserved for the identified contact

• Always use logOut() to return to anonymous state

• Keep your app's login and logout flow aligned with the SDK identification lifecycle