Overview
MoEngage’s React Native SDK helps you integrate MoEngage into iOS and Android applications built with React Native framework. 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 React Native.
info |
Information You can now get notified whenever MoEngage releases a new version of the React Native SDK. For more information, refer to Subscribe to MoEngage SDK Releases. |
SDK Installation and Initialization
Step 1: Installation
To add MoEngage's React Native SDK to your application, refer to Installation Methods.
Step 2: Complete Native Android Setup
- Android native setup guidelines to complete the installation are described in this article.
- There are no additional steps required for iOS. Move on to the initialization (Step 3).
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
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 setUserUniqueID(). 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 Notifications
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 React Native application, you must configure Firebase. Configuring Firebase steps will depend on how you want to integrate it. MoEngage recommends leaving the push handling to MoEngage SDK, as the best practices are properly integrated. You can also handle the push at your app level. In any case, look at the following section that applies to you and finish the integration steps.
Add messaging service
You must add the messaging service to the Manifest file for MoEngage SDK to show the notifications. Refer to this document here.Callback on token registration (optional)
To get a callback whenever a new token is registered or refreshed, refer to the method here.Notification Clicked Callback
To receive a callback whenever a push is clicked and for custom handling redirection, use the method in this article.
How to opt out of MoEngage Registration?
The MoEngage SDK attempts to register for a push token; since your application handles 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.
warning Warning
MoEngage recommends using the Android native APIs to pass the push payload to the MoEngage SDK instead of the React-Native/Javascript APIs. React-Native Engine might not get initialized if the application is killed or if the notification is not sent at a high priority.
- Pass the Push Token To MoEngage SDK
- Pass the Push payload to the MoEngage SDK
- Callbacks and customizations
Notification Clicked Callback - MoEngage's React Native plugin optionally provides a callback on push clicks with the method in this article.
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 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
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.
Registering for Push notification - Follow the steps in this article to initiate registration and the steps in this section to call the respective MoEngage SDK methods for registration callbacks.
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 want to keep the notifications even after the App Launch, 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. -
Notification Actions
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 React Native.
Push Templates
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
Push Amp+ (Android only and Optional)
Around 25-30% of notifications are 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.
Supported Integrations
Push Amplification (Android only and Optional)
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.
Notification Center
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 (Optional)
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 (Optional)
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.
In-App
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 React Native, use the following platform-specific methods:
- Android
- 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.
Show In-app
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. SDK has to be notified when the device orientation changes for SDK to handle in-app display. To handle orientation change, refer to this article.
Self-handled In-apps
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.
InApp Callbacks
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.
Cards
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 React Native.