Core concepts

Before integrating advanced features, it is helpful to understand how the Mapp Engage Flutter plugin works at a higher level. The plugin follows a bridge-based model between Flutter and the native Mapp Engage SDKs on Android and iOS.

The concepts below explain how the SDK initializes, how devices are identified, and how events are delivered back to your Flutter application.

How the Flutter plugin works

The Flutter plugin acts as a bridge between your Dart code and the native Mapp Engage SDKs on Android and iOS. You call asynchronous methods from Flutter, and the plugin forwards them to the native platform implementation.

This means:

All SDK calls should be treated as asynchronous
Platform-specific behavior may differ between Android and iOS
Some results are returned directly, while others are delivered through callbacks

What happens during initialization

When you call MappSdk.engage(...), the SDK performs the initial setup required for device-based engagement.

During initialization:

The native Mapp Engage SDK is initialized
The device is registered with the Mapp Engage backend
An anonymous AUTO alias is assigned to the device

This initialization step must happen before other Mapp Engage methods are used.

The device-first model

The plugin follows a device-first lifecycle. Each app installation is initially registered as an anonymous device. Later, that device can be associated with a known user by assigning a custom alias.

This model makes it possible to:

Start engagement before the user logs in
Keep device registration independent from user authentication
Link anonymous activity to a known contact later in the lifecycle

Three concepts to understand first

Device and alias model

Every initialized device receives an AUTO alias. After a user signs in, you can replace that AUTO alias with a known identifier such as an email address or customer ID.

This topic explains how aliases are created, updated, and reset during logout.

SDK lifecycle and readiness

The SDK must be initialized before any other call is made. After initialization, use isReady() to confirm that the SDK is ready for operations such as alias changes, push handling, or custom attribute updates.

This topic explains the order of operations and when SDK calls are safe to use.

Event callbacks

Some SDK events are delivered through static callback properties instead of direct return values. This is especially important for push interactions, in-app events, inbox delivery, and deep linking.

This topic explains which events are available and when to assign callback handlers.