SDK lifecycle and readiness

The Mapp Engage Flutter plugin follows a strict initialization flow. Before you use aliases, push configuration, custom attributes, or other SDK features, the SDK must be initialized successfully and the device must be ready.

Initialize the SDK first

Initialization is mandatory and must be the first Mapp Engage call in your application lifecycle. Call MappSdk.engage(...) before runApp().

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();

  await MappSdk.engage(
    'YOUR_SDK_KEY',
    'YOUR_GOOGLE_PROJECT_ID',
    SERVER.L3,
    'YOUR_APP_ID',
    'YOUR_TENANT_ID',
    NotificationMode.backgroundAndForeground,
  );

  runApp(MyApp());
}

What happens during initialization

When engage() completes successfully, the SDK performs the core setup required for device-based engagement.

• 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

Check whether the SDK is ready

Use isReady() to confirm that initialization completed successfully and the device is registered.

final bool ready = await MappSdk.isReady();

if (!ready) {
  // SDK is not ready yet
}

This method returns true when the SDK has initialized successfully and is ready for normal use.

When to use isReady()

In many apps, checking isReady() is useful when SDK-related actions depend on application state or user interaction.

Typical examples include:

• Before setting a known alias

• Before reading device information

• Before updating push state

• Before sending custom attributes or tags

If your startup flow already guarantees that engage() completed successfully, you may not need to check readiness before every SDK call. Still, isReady() is a useful guard for delayed or conditional flows.

Order of operations

Use the following lifecycle order as a guideline:

1. Initialize Flutter bindings

2. Assign any event callbacks that should be available immediately

3. Call MappSdk.engage(...)

4. Confirm readiness if needed with isReady()

5. Call other SDK methods such as setAlias(), setPushEnabled(), or setCustomAttributes()

Assign callbacks before initialization

Some SDK events can occur early in the application lifecycle, especially push-related or event-driven callbacks. To avoid missing those events, assign callback handlers before calling engage().

MappSdk.handledRemoteNotification = (dynamic arguments) {
  // Handle received push notification
};

MappSdk.handledPushOpen = (dynamic arguments) {
  // Handle notification open
};

await MappSdk.engage(
  'YOUR_SDK_KEY',
  'YOUR_GOOGLE_PROJECT_ID',
  SERVER.L3,
  'YOUR_APP_ID',
  'YOUR_TENANT_ID',
);

Read device information after initialization

After initialization, you can retrieve metadata for the current device.

final Map<String, dynamic>? info = await MappSdk.getDeviceInfo();
print('Device info: $info');

Call this only after the SDK is initialized and ready.

Common lifecycle mistakes

• Calling SDK methods before engage()

• Initializing the SDK too late in the app startup flow

• Assigning callbacks after initialization and missing early events

• Using alias or push methods before device registration is complete

Best practices

• Call engage() before runApp()

• Treat all SDK calls as asynchronous

• Assign callback handlers before initialization if early events matter

• Use isReady() for guarded or delayed flows

• Do not treat initialization as optional