In-app messaging and inbox

New
  • 2 minute(s) read
Prev Next

The Mapp Engage Flutter plugin supports in-app messaging and inbox functionality. These features allow you to trigger messages inside the app, retrieve stored messages, and manage message states such as read or deleted.

This guide explains how to trigger in-app messages, fetch inbox content, and handle platform-specific behavior.

How in-app messaging works

In-app messages are triggered by events defined in your Mapp Engage setup. Your app sends an event name, and the SDK checks whether a corresponding message should be displayed.

In-app messaging depends on:

  • SDK initialization

  • A valid device or user context (AUTO alias or identified user)

  • Configured events in the Mapp dashboard

Trigger an in-app message

Use triggerInApp() to fire an event that may display an in-app message.

await MappSdk.triggerInApp('app_open');
await MappSdk.triggerInApp('checkout_started');

The event name must match a configured event in your Mapp Engage setup.

If a matching in-app campaign is active, the message is displayed automatically.

Receive in-app message events

You can listen for in-app message delivery using a callback handler.

MappSdk.didReceiveInappMessageWithIdentifier = (dynamic arguments) {
  // In-app message is ready to display
};

This callback is triggered when an in-app message is available and ready to be shown.

Fetch inbox messages

Use fetchInboxMessage() to retrieve all inbox messages associated with the current device or contact.

if (Platform.isAndroid) {
  final dynamic messages = await MappSdk.fetchInboxMessage();
  print('Inbox messages: $messages');
} else {
  MappSdk.fetchInboxMessage();
}

Platform behavior differs:

  • Android: Returns the messages directly as a result

  • iOS: Messages are delivered through a callback instead of a return value

Handle inbox messages on iOS

On iOS, inbox messages are delivered via callback handlers.

MappSdk.didReceiveInBoxMessages = (dynamic arguments) {
  print('Inbox messages: $arguments');
};

You can also receive a single inbox message using:

MappSdk.didReceiveInBoxMessage = (dynamic arguments) {
  print('Single inbox message: $arguments');
};

Assign these callbacks before calling fetchInboxMessage().

Fetch a specific inbox message

Use fetchInBoxMessageWithMessageId() to retrieve a specific message by its ID.

final String? message =
    await MappSdk.fetchInBoxMessageWithMessageId(12345);

print('Message: $message');

This method returns a JSON string containing the message data.

Update message state

You can update the state of an in-app or inbox message by marking it as read, unread, or deleted.

await MappSdk.inAppMarkAsRead('templateId', 'eventId');

await MappSdk.inAppMarkAsUnread('templateId', 'eventId');

await MappSdk.inAppMarkAsDeleted('templateId', 'eventId');

All three methods require two positional arguments:

  • templateId

  • eventId

Make sure to pass both values as strings.

Important method naming details

Pay attention to the exact method names and casing:

  • inAppMarkAsRead

  • inAppMarkAsUnread (lowercase r)

  • inAppMarkAsDeleted

Incorrect casing or parameter formats will cause runtime or compilation issues.

Platform differences

In-app messaging and inbox handling behave differently on Android and iOS:

  • Inbox fetching returns data directly on Android

  • Inbox fetching uses callbacks on iOS

  • In-app message delivery uses callbacks on both platforms

Make sure your app handles both patterns correctly if you support both platforms.

Recommended usage flow

  1. Initialize the SDK

  2. Assign in-app and inbox callbacks

  3. Trigger events using triggerInApp()

  4. Fetch inbox messages when needed

  5. Update message states based on user interaction

This approach ensures that your app can both trigger and respond to engagement messages consistently.

Common mistakes

  • Using incorrect method names or casing for message state updates

  • Expecting inbox messages to return directly on iOS

  • Not assigning callbacks before triggering events

  • Passing incorrect parameter types for template or event IDs

Best practices

  • Assign callbacks before calling SDK methods

  • Handle Android and iOS inbox behavior explicitly

  • Use consistent event naming aligned with your Mapp configuration

  • Keep message handling logic separate from UI rendering

  • Log payloads during development to understand message structure