In-App-Messaging

Starting from 0.3.0, the In-App-Messaging(IAM) feature is available in the Flutter SDK. This feature allows you to display in-app messages (such as fullscreens, popups, bottomsheets, and toasts) in your application.

info

Starting from SDK version 0.8.0, the call of showing in-app messages has changed. If you are upgrading from older version please see migration guide here.

The module provides methods for preloading messages, displaying them, and handling related events.

Presentation types

IAM can be displayed in different presentation styles:

Value	Description
fullScreen	Full-screen presentation
bottomSheet	Bottom sheet (modal)
popUp	Pop-up window
toast	Toast notification

info

Starting from SDK version 0.9.0, the Toast message type is supported (iOS & Android). No additional setup is required for toast messages — they automatically pass through touch gestures outside the message area to the underlying UI.

tip

If you have troubles with closing IAM in Android devices by pressing back button or using back gesture, please add android:enableOnBackInvokedCallback="true" to AndroidManifest.xml file:

AndroidManifest.xml

<manifest xmlns:android="http://schemas.android.com/apk/res/android">
    <application>
        <activity
                android:name=".MainActivity"
                android:enableOnBackInvokedCallback="true">
        </activity>
    </application>
</manifest>

Show In-App message

By Message ID

To show an in-app message by its ID without targeting evaluation:

Future<void> showInAppMessage(String id) async {
  InAppStoryManager.instance.showIAMById(id);
}

With targeting

Starting with version 0.11.0, use showIAMByIdWithTargeting to check targeting rules before displaying the message, optionally passing request-specific tags:

Future<void> showInAppMessageWithTargeting(String id) async {
  InAppStoryManager.instance.showIAMByIdWithTargeting(
    id,
    tags: ['premium', 'discount'],
  );
}

By Event

To show a message for a specific event:

Future<void> showInAppMessage(String event) async {
  InAppStoryManager.instance.showIAMByEvent(event);
}

With targeting tags override

Starting with version 0.11.0, event requests can also provide request-specific tags:

Future<void> showInAppMessageWithTags(String event) async {
  InAppStoryManager.instance.showIAMByEventWithTargeting(
    event,
    tags: ['summer_sale'],
  );
}

Targeting rules

• showIAMById skips targeting evaluation entirely.
• showIAMByIdWithTargeting enables targeting evaluation. If tags is supplied, those tags override global tags for this request; if null, active global tags are used.
• showIAMByEvent always evaluates targeting for the event using global tags.
• showIAMByEventWithTargeting allows supplying request-specific tags while evaluating event targeting.

Bottom padding

Both ID and event display methods accept an optional bottomPadding parameter. Use it to lift the in-app message above overlapping UI, such as a bottom navigation bar. If omitted, no bottom padding is applied.

Future<void> showInAppMessage(String id) async {
  InAppStoryManager.instance.showIAMById(id, bottomPadding: 56);
}

Preload In-App Messages

To preload in-app messages, you can use the InAppStoryManager.instance.preloadInAppMessages(...) method. This method allows you to preload all messages or preload specific messages by passing its ids.

Future<void> preloadInAppMessages(List<String>? messageIds) async {
  InAppStoryManager.instance.preloadInAppMessages(ids: messageIds);
}

It is also possible to limit the message display if it is not preloaded. To do this, specify the onlyPreloaded = true parameter in the InAppStoryManager.instance.showIAMById(...) or InAppStoryManager.instance.showIAMByEvent(...) methods of showing the message. In this case, the InAppMessage screen will not be shown.

Future<void> showInAppMessageById(String id) async {
  InAppStoryManager.instance.showIAMById(id, onlyPreloaded: true);
}

Future<void> showInAppMessageByEvent(String event) async {
  InAppStoryManager.instance.showIAMByEvent(event, onlyPreloaded: true);
}

Events

To receive events from the In-App Messaging module, you can implement the IASInAppMessageCallback mixin and set up your listener.

class InAppMessageWidget extends StatefulWidget {
  const InAppMessageWidget({super.key});

  @override
  State<InAppMessageWidget> createState() => _InAppMessageWidgetState();
}

class _InAppMessageWidgetState extends State<InAppMessageWidget>
    with IASInAppMessageCallback {
  @override
  Widget build(BuildContext context) {
    return ElevatedButton(
      onPressed: () {
        InAppStoryManager.instance.showIAMById("<id>");
      },
      child: const Text("Show In-App Message"),
    );
  }

  @override
  void onShowInAppMessage(InAppMessageData? inAppMessageData) {
    print("IAM: onShowInAppMessage: ${inAppMessageData?.id}");
  }

  @override
  void onCloseInAppMessage(InAppMessageData? inAppMessageData) {
    print("IAM: onCloseInAppMessage: ${inAppMessageData?.id}");
  }

  @override
  void onInAppMessageWidgetEvent(InAppMessageData? inAppMessageData,
      String? name, Map<String?, Object?>? data) {
    print("IAM: onInAppMessageWidgetEvent: ${inAppMessageData?.id}");
  }
}

Event List

• onShowInAppMessage(InAppMessageData? inAppMessageData) - Called when the in-app message is shown:
  • inAppMessageData - The data of the in-app message that was shown;
• onCloseInAppMessage(InAppMessageData? inAppMessageData) - Called when the in-app message is closed:
  • inAppMessageData - The data of the in-app message that was shown;
• onInAppMessageWidgetEvent(InAppMessageData? inAppMessageData, String? name, Map<String?, Object?>? data) - Called when the in-app message widget event is triggered:
  • inAppMessageData - The data of the in-app message that was shown;
  • name - The name of widget;
  • data - widget data detail;

class InAppMessageData {
  /// The unique identifier of the in-app message.
  final int id;
  /// The title of the in-app message, or `null` if not available.
  final String? title;
  /// The event associated with the in-app message, or `null` if not available.
  final String? event;
  /// The presentation type of the in-app message, or `null` if not available.
  final InAppMessageType? messageType;
  /// Additional custom fields associated with the in-app message.
  final Map<String, String>? extraFields;
}