---
title: "SDK lifecycle and readiness"
slug: "sdk-lifecycle-and-readiness-flutter-engage"
updated: 2026-04-17T09:13:42Z
published: 2026-04-17T09:13:42Z
canonical: "docs.mapp.com/sdk-lifecycle-and-readiness-flutter-engage"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mapp.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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()`.

```dart
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.

```dart
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()`.

```dart
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.

```dart
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