Device and alias model

New
  • 2 minute(s) read
Prev Next

The Mapp Engage Flutter plugin follows a device-first identification model. Each app installation is registered as a device first, even before a known user signs in. This allows the SDK to support engagement features immediately and later associate the device with a known contact.

How identification starts

After successful SDK initialization, the device is registered and assigned an anonymous AUTO alias.

The AUTO alias follows this format:

AUTO_<APP_ID>_<RANDOM_HASH>

Example:

AUTO_21324_4554AGKR443543KA231241

This alias identifies the current app installation as an anonymous device. It is created automatically and is required for normal SDK operation.

Why the AUTO alias matters

The AUTO alias allows the SDK to start working before the user is known. This means your app can initialize Mapp Engage, register the device, and use supported features even if no user has logged in yet.

This is useful because it allows you to:

  • Register a device on first launch

  • Enable device-based engagement before login

  • Associate the device with a known contact later

Retrieve the current alias

You can retrieve the alias currently assigned to the device with getAlias().

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

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

Set a known user alias

When a user signs in, replace the AUTO alias with a known identifier such as an email address or customer ID.

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

After the alias is set:

  • 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 setAlias() only after the user is authenticated in your application.

When to call setAlias()

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

Recommended flow:

  1. Initialize the SDK on app launch

  2. Let the device operate with its AUTO alias

  3. Call setAlias() after login

Do not pass an empty string to remove the alias. To return the device to anonymous state, use logOut().

Resend custom attributes after alias changes

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

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

This is useful when custom attributes were collected while the device was still operating with its AUTO alias and should also be associated with the resolved user contact.

What happens on logout

When a user signs out, call logOut() to detach the device from the current user and return it to anonymous state.

await MappSdk.logOut(false);

After logout:

  • The user alias is removed

  • The device is detached from the identified contact

  • A new AUTO alias is assigned

  • Push behavior is controlled by the pushEnabled argument

The method accepts a positional boolean argument.

Recommended identification lifecycle

  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. Use the identified contact for engagement features

  5. Call logOut() on sign-out to return to anonymous state

Best practices

  • Initialize the SDK before any alias-related call

  • Use the AUTO alias as the default anonymous state

  • Call setAlias() only when the user identity is known

  • Use logOut() instead of passing an empty alias

  • Use setAliasWithResend() when previously stored custom attributes should be re-sent after identification