MoEngage’s Flutter SDK helps you integrate MoEngage into iOS and Android applications built with Flutter. It allows you to work with push notifications, in-app messages, cards, user attributes, events, and much more.
To see the sample code, take a look at the GitHub repository. This article describes the steps to implement MoEngage features on Flutter.
SDK Installation and Initialization
Step 1: Installation
To add MoEngage's Flutter SDK to your application, refer to Installation Methods.
Step 2: Complete Native Setup
The platform-specific native setup guidelines to complete the installation are described in the following articles:
Step 3: Framework Initialization
Initialize an instance of the MoEngage plugin by calling the method described in this article.
Step 4: Platform Initialization
The platform-specific steps to initialize the SDK and set up the data center are described in the following articles:
Data tracking allows apps to monitor and analyze user behavior to optimize engagement strategies. It involves tracking various user actions such as login, logout, and event tracking in a way that avoids data corruption. Use the following methods to implement data tracking.
- Install/Update Differentiation - To track fresh installs and updates separately, refer to the methods in this article.
Tracking Login, Logout, and Setting Unique ID - To avoid data corruption, it is crucial to follow the steps outlined in the following articles when handling user login and logout.
It is essential to have a unique ID for each of your app's users, which can be passed onto MoEngage SDK using setUniqueId(). This unique ID helps to correctly identify a user across multiple installs and platforms to provide a unified view.
Once a user logs out of the app, it's critical to call logout() to initiate the creation of a new user. This step is necessary to ensure that any subsequent activities performed by the new user are not wrongly attributed to the previously logged-in user, which could distort user data.
- Tracking user attributes - To set custom attributes available in the user profile, refer to the methods in this article.
- Tracking Events - Tracking events is how you record user actions, along with any properties that describe the action. To track custom events, refer to the methods in this article.
- Enable Advertising Identifier Tracking (Android only) - MoEngage SDK uses a Device ID (persistent device identifier) to uniquely identify the user to deliver personalized content and associates this to AAID if allowed by the app. This allows accurate identification of reachable devices for sending push notifications and tracking re-installs for users over time. To enable tracking of the AAID after obtaining the user’s consent, refer to the methods in this article.
Push campaigns target users through notifications for your app or website. Depending on the desired capability, follow the integration steps listed below to integrate push notifications.
Basic Setup - Android
Follow the basic setup outlined in this section to enable push notifications on an Android device using MoEngage.
- FCM Setup on MoEngage Dashboard - FCM Authentication is the method to enable sending push notifications to your app installed on Android devices. Use the methods mentioned in this article to authenticate MoEngage to access Firebase services.
- Adding metadata for push notification - Set the small icon and large icon drawable and other options to handle push notifications using the methods available in this article.
- Android Notification Runtime Permissions - When the application is running on Android 13 to show notifications to the user, applications would need to request the user for notification permission. Refer to the methods available in this article to handle permission requests.
Push Registration and Receiving - To use Push Notification in your Flutter application, you need to configure Firebase. Depending on your requirements, refer to one of the below methods to enable Push Registration and Receiving.
The MoEngage SDK, by default, registers push tokens and handles the receiving of push notifications.
Callback on token registration - To get an optional callback whenever a new token is registered or the token is refreshed, refer to the method here.
How to opt out of MoEngage Registration?
The MoEngage SDK attempts to register for a push token; since your application is handling push, you need to opt out of SDK's token registration using the method in this article.
Pass the Push Token To MoEngage SDK - After receiving the push token from FCM, use the method in this article to pass the Push Token to the MoEngage SDK to set it in the MoEngage platform.
Passing the Push payload to the MoEngage SDK - After receiving the push payload on the app, use the method in this article to send out push notifications to the device.
Notification Clicked Callback - To receive a callback whenever a push is clicked and for custom handling redirection, use the method in this article.
We recommend you use the Android native APIs to pass the push payload to the MoEngage SDK instead of the Flutter/Dart APIs. Flutter Engine might not get initialized if the application is in the killed state, which will lead to poor push reachability or delivery.
- Pass the Push Token To MoEngage SDK
- Pass the Push payload to the MoEngage SDK
- Callbacks and customizations
Basic Setup - iOS
Follow the basic setup outlined in this section to enable push notifications on an iOS device using MoEngage.
APNS Setup on MoEngage dashboard
APNS Authentication is the method to enable sending push notifications to your app installed on Android devices. You can use any of these options to set up APNS on the MoEngage dashboard.
- App target implementation - Make changes to your app target to enable notifications by following the steps mentioned in this article.
- Provide the App Group ID to SDK - Pass the App Group ID to MoEngage SDK using the method in this article.
Push Registration and Receiving
In MoEngage SDK, we have now swizzled the AppDelegate Class to get all the callbacks related to Push Notifications, and we have also applied the method swizzling for UserNotificationCenter delegate methods. This is to ease the integration of the SDK.
Registering for Push notification
Follow the steps in this article to initiate registration.
Callback methods on receiving Push Notification
The callback the app would receive on receiving the push notifications is mentioned in this article. With Swizzling enabled, no additional configuration is required.
In case you do not prefer to use swizzling, you can disable the same by adding the flag MoEngageAppDelegateProxyEnabled in the app’s Info.plist file and setting it to Boolean value NO, and follow the steps below.
Callback methods on receiving Push Notification - With Swizzling disabled, include calls to MoEngage SDK methods on receiving notification callbacks, as described in this article.
Disable Badge Reset
By default, the SDK sets the notification badge count to 0 on every app launch, and this also clears the notifications in the device notification center. If you would like to keep the notifications even after the App Launch, then disable badge reset by calling the method in this section.
Custom Sound for Notification
To optionally set a custom tone for notifications of your app, you can follow the method in this section.
Notification Service Extension Target Implementation
The notification service extension allows MoEngage SDK to customize the content of a notification before the system delivers it to the user. This gives you the capability to add media in notifications, support inbox, update badge count on notifications delivered, and track notification impressions. Follow the steps in this article to set up the notification service extension.
Actionable notifications let you add custom action buttons to the standard iOS push notifications. Follow the steps mentioned in this article to add custom actions to your notifications and track the actions performed on notifications
This completes your basic setup for push notifications in Flutter.
Push templates enable you to craft beautiful notifications within minutes without any coding. For information on how to create campaigns with templates in the dashboard, refer to this article.
To enable push templates, please follow the platform-specific documentation
A significant percentage of notifications, around 25-30%, is not delivered due to issues with original equipment manufacturer (OEM) devices. To combat this problem and improve retention rates, MoEngage developed Push Amplification+ to reach customers who may not have received notifications. MoEngage has also partnered with OEMs to address these issues and ensure that notifications are reliably delivered. To minimize any additional burden on your application, we have developed individual software development kits (SDKs) for each OEM. You can choose and integrate the relevant SDK based on your application's specific needs and device share. Refer to the documentation for each OEM-specific service and integrate the appropriate ones into your application for optimal push notification delivery.
Push Amplification works as a fallback mechanism when Firebase Cloud Messaging (FCM) fails to deliver Push Notifications. Follow the method here to set up Push Amplification.
The Notification Center shows your push notification history, allowing you to provide an option for the end-user to scroll back and see what they have missed. MoEngage provides out-of-box inbox support with a fully customizable default UI and also provides an option to build your own Notification Center. For more information, refer to Notification Center.
Location Triggered Notifications
Location-triggered notifications allow you to send messages to your audience that are triggered on the user’s entry, exit, and dwell in defined Geo Fences. Follow the method in this article to set up location triggers.
Device triggered notifications
Device-triggered notifications allow you to send messages to your audience that are triggered locally based on any activity on a device. Offline delivery of messages is supported as well.
To enable device-triggered notifications, use the following platform-specific articles:
Advanced Use Cases in Android
For advanced use cases, the following options are available:
- Non-MoEngage Payload - To get an optional callback in case a push payload is received for any other server apart from the MoEngage Platform, refer to the method here.
Callbacks and customizations - The MoEngage SDK allows the client application to optionally customize the notification display and extend/customize the behavior of the notification. Refer to the methods mentioned here to access the features, such as:
- Control whether a notification is shown to the user or not
- Notification Received Callback
- Notification Clicked Callback
- Notification Cleared Callback
- Custom Action on Action Button Click
- Push Display Handled by Application(Android) - When the application needs to handle the push display on the client side, you can track notification impressions and cases using the methods described in this article.
MoEngage In-App Campaigns target users by showing a message while the user is using your app. They are effective in providing contextual information and help to cross-sell/up-sell on desired screens of your app or/and on desired actions performed by the user in your app.
Basic Setup - To install In-app notifications in Flutter, use the following platform-specific methods:
- iOS (installation is not required for iOS)
Displaying In-App Messages
You can either show In-app messages using MoEngage’s out-of-the-box UI, or you can use Self-handled In-apps to build the UI of the application using the payload from MoEngage.
Call the method here to show an inApp campaign on a screen. In-app pop-ups will only show up where showInApp() method is called.
Handling Orientation Change
In-apps are supported in both portrait and landscape modes. There are two ways to do it:
- Add the API call in the Android native part of your app
- Call MoEngage plugin's onOrientationChanged()
Self-handled In Apps are messages that are delivered by the SDK to the application, and the application builds the UI using the delivered payload by the SDK. To get the self-handled in-app, refer to this article.
Optionally, we provide callbacks for in-app shown, in-app clicked, in-app dismissed, and self-handled in-app available events. You can register for the callbacks using the methods in this article.
MoEngage Cards campaigns help you interact with your users with persistent and non-intrusive messages in your customer's journey. Self-handled cards are message payloads that are delivered by the SDK to the application, and the application builds the UI using the delivered payload.
Refer to this article to implement self-handled cards on Flutter.