Integrating Mapp Engage in Flutter: Bridge API Guide

Overview

This guide provides step-by-step instructions for integrating Mapp Engage into a Flutter app. It focuses on initialization, device registration, push notifications, and advanced customization options for Android and iOS platforms. Follow each platform’s specific instructions carefully to ensure smooth integration.

Procedures

Step 1: Initializing the Mapp Plugin

Start by initializing the Mapp SDK in your application:

1. Import Required Files: Include mapp_sdk.dart and helper_classes.dart in your project.

2. Initialize SDK: Use the following method as the first action in your app to initialize the Mapp SDK:

   Future<String?> engage(String sdkKey, String googleProjectId, SERVER server, String appID, String tenantID);

   • Parameters:

     • sdkKey: Your Mapp account’s SDK key.

     • googleProjectId: Optional, for backward compatibility.

     • server: Server for engagement (provided by Mapp).

     • appID and tenantID: Identifiers for your app and Mapp account.

Step 2: Platform-Specific Setup

Complete the following setup based on your target platform.

For Android

1. Device Registration: Check if the device is registered and set or retrieve device aliases:

   bool isRegistered = MappSdk.isReady();
   MappSdk.getAlias().then((alias) => print("Device alias: $alias"));
   MappSdk.setAlias("your_alias");

2. Push Notifications:

   • Enable or Disable Push Notifications:

     MappSdk.setPushEnabled(true); // Enable push

   • Request Notification Permission (Android 13+ only):

     final result = await MappSdk.requestPermissionPostNotifications();

3. Firebase Device Tokens and Push Messages: Forward the Firebase token to Mapp and handle incoming push messages:

   final token = await FirebaseMessaging.instance.getToken();
   MappSdk.setToken(token);
   FirebaseMessaging.onBackgroundMessage(_firebaseMessageHandler);

4. Push Event Handlers:

   • Subscribe to Push Received Events:

     MappSdk.handledRemoteNotification = (arguments) {
       print("Push notification received: $arguments");
     };

   • Push Opened, Dismissed, and Silent Push Events (Android Only):

     • Push Opened:

       MappSdk.handledPushOpen = (arguments) {
         print("Push opened: $arguments");
       };

     • Push Dismissed:

       MappSdk.handledPushDismiss = (arguments) {
         print("Push dismissed: $arguments");
       };

     • Silent Push Received:

       MappSdk.handledPushSilent = (arguments) {
         print("Silent push received: $arguments");
       };

For iOS

1. Device Registration: Retrieve or set device aliases in the same way as Android:

   bool isRegistered = MappSdk.isReady();
   MappSdk.getAlias().then((alias) => print("Device alias: $alias"));
   MappSdk.setAlias("your_alias");

2. Push Notifications:

   • Subscribe to Push Received Events:

     MappSdk.handledRemoteNotification = (arguments) {
       print("Push notification received: $arguments");
     };

   • Enable or Disable Push Notifications:

     MappSdk.setPushEnabled(true); // Enable

   • Handle rich push content:

     MappSdk.handledRichContent = (arguments) => print("Rich content: $arguments");

Step 3: Advanced Features

These features are available on Android and iOS, enabling advanced user engagement, data management, and navigation across platforms.

In-App Messaging

Manage and retrieve in-app messages to engage users with event-based messaging.

• Fetch Inbox Messages:

  if (Platform.isAndroid) {
    MappSdk.fetchInboxMessage().then((messages) {
      print("Inbox messages: $messages");
    });
  } else {
    MappSdk.fetchInboxMessage();
  }

  On iOS, inbox messages are received as events and not through a returned promise. Use the didReceiveInboxMessagesHandler event handler to capture them.

• Show In-App Message: Trigger an in-app message based on a specific event:

  MappSdk.triggerInApp("app_open");

• Manage In-App Messages: Mark in-app messages as read, unread, or deleted:

  MappSdk.inAppMarkAsRead(templateId: number, eventId: string);
  MappSdk.inAppMarkAsUnRead(templateId: number, eventId: string);
  MappSdk.inAppMarkAsDeleted(templateId: number, eventId: string);

Geolocation Targeting

Enable geolocation-based features to target users based on their location. Ensure you’ve added the necessary location permissions in info.plist (iOS) or AndroidManifest.xml (Android) to enable this feature.

• Start Geofencing:

  MappSdk.startGeoFencing().then((status) {
    print("Geofencing started: $status");
  }).catchError((error) {
    print("Error starting geofencing: $error");
  });

• Stop Geofencing:

  MappSdk.stopGeoFencing().then((status) {
    print("Geofencing stopped: $status");
  }).catchError((error) {
    print("Error stopping geofencing: $error");
  });

Deep Linking

Handle deep links embedded within push notifications, enabling users to navigate to specific screens or content within the app.

MappSdk.addDeepLinkingListener((notification) {
  // Parse and handle the deep link URL to navigate within the app
});

Custom Fields

Store custom data fields for users in Mapp Engage to create personalized content and messages.

• Set Custom Fields:

  MappSdk.setAttributeString("fieldKey", "stringValue");    // Set a string field
  MappSdk.setAttributeInt("fieldKey", 42);                 // Set an integer field
  MappSdk.setAttributeBoolean("fieldKey", true);           // Set a boolean field

Logout

Log out and optionally disable push notifications:

MappSdk.logOut(pushEnabled: false);  // Set pushEnabled to true or false depending on your needs