MoEngage is an intelligent customer engagement platform. It lets you personalize every customer interaction and drive better engagement, retention, loyalty, and lifetime value.
Find the open source transformer code for this destination in the GitHub repository.
In the web device mode integration, that is, using JavaScript SDK as a source, RudderStack loads the MoEngage native SDK from the hhttp(s)://cdn.moengage.com/webpush/moe_webSdk.min.latest.js domain.
Based on your website’s content security policy, you might need to allowlist this domain to load the MoEngage SDK successfully.
Get started
Once you have confirmed that the source platform supports sending events to MoEngage, follow these steps:
From your RudderStack dashboard, add a source. Then, from the list of destinations, select MoEngage.
Assign a name to the destination and click Continue.
Connection settings
To successfully configure MoEngage as a destination, you will need to configure the following settings:
API ID: Enter your MoEngage API ID.
API Key: Enter your MoEngage API key.
For more information on obtaining your MoEngage API ID and API key, refer to the FAQ section below.
Region: Choose the MoEngage server region (EU, US, or IND ) to send your event data.
Client-side Events Filtering: This setting is applicable only for the device mode integrations. It lets you specify which events should be blocked or allowed to flow through to MoEngage. For more information on this setting, refer to the Client-side Events Filtering guide.
Use device mode to send events: Enable this setting to send events to MoEngage via the device mode.
Debug mode: Enable this setting to get the debug logs for the events sent using the web SDK. You can then see the events under the Test section of your MoEngage app.
Once you add MoEngage as a destination in the RudderStack dashboard, follow these steps to add it to your project depending on your integration platform:
Go to your Podfile and add the Rudder-Moengage extension.
pod'Rudder-Moengage'
After adding the dependency followed by pod install, add the imports to your AppDelegate.m file:
#import "RudderMoengageFactory.h"
Finally, change the initialization of your RudderClient:
Open your app/build.gradle (Module: app) file and add the following lines:
repositories{mavenCentral()}
Add the following dependencies:
// RudderStack Android and MoEngage SDKs
implementation'com.rudderstack.android.sdk:core:[1.0,2.0)'implementation'com.rudderstack.android.integration:moengage:2.0.0'// For MoEngage core SDK initialisation
implementation("com.moengage:moe-android-sdk:12.5.04")// Firebase messaging dependency
implementation'com.google.firebase:firebase-messaging:23.1.1'// If you don't have Gson included already
implementation'com.google.code.gson:gson:2.8.9'
After buildscript, add the below plugin:
// For Push Notification
applyplugin:'com.google.gms.google-services'
Open your build.gradle (Module: Project) file and add the following in the buildscript dependencies:
// For Push Notification
buildscript{dependencies{classpath'com.google.gms:google-services:4.3.14'}}
Initialize the RudderStack SDK in the Application class’ onCreate() method:
Initialize the MoEngage SDK in the Application class’ onCreate() method:
// initializing MoEngage SDK and "XXXXXXXXXXX" is the APP ID from the dashboard.
valmoEngage=MoEngage.Builder(this,"XXXXXXXXXXX").configureLogs(LogConfig(LogLevel.VERBOSE,false)).build()MoEngage.initialiseDefaultInstance(moEngage)
Add the RudderStack-MoEngage module to your app by running the following command:
npm install @rudderstack/rudder-integration-moengage-react-native
// OR //
yarn add @rudderstack/rudder-integration-moengage-react-native
Import the above module and add it to your SDK initialization:
Add the following dependencies in the android/app/build.gradle (Module: app) file in the Android folder of your React Native project:
implementation'com.rudderstack.android.sdk:core:1.+'implementation'com.rudderstack.android.integration:moengage:1.0.0'implementation'com.moengage:moe-android-sdk:10.5.00'//jet pack library required by moengage
implementation'androidx.core:core-ktx:1.3.2'implementation'androidx.appcompat:appcompat:1.2.0'implementation'androidx.lifecycle:lifecycle-process:2.2.0'//firebase messaging dependency
implementation'com.google.firebase:firebase-messaging:21.0.0'// if you don't have Gson included already
implementation'com.google.code.gson:gson:2.8.6'
In the android/build.gradle (Module: Project) file, add the following lines:
repositories{mavenCentral()}
Add the following in the buildscript dependencies in android/build.gradle (Module: Project) file:
// For Push Notification
buildscript{dependencies{classpath'com.google.gms:google-services:4.3.4'}}
Add the following plugin at the top of android/app/build.gradle (Module: app):
// For Push Notification
applyplugin:'com.google.gms.google-services'
Initialize the MoEngage SDK in the Application class’ onCreate() method:
// MoEngage SDK initialisation: Replace "xxxxxxx" with your APP ID.
MoEngagemoEngage=newMoEngage.Builder(MainActivity.this.getApplication(),"xxxxxxx").enableLogs(LogLevel.VERBOSE).build();MoEngage.initialise(moEngage);
Identify
You can use the identify API to identify a user in MoEngage. You can also create a new user property or update existing user properties using the identify call.
MoEngage needs a unique identifier to identify a user. So, you must provide a userId in your identify call that RudderStack passes as the MoEngage customer_id . If userId is absent, RudderStack sends the anonymousId field instead.
A sample identify call is as shown:
rudderanalytics.identify("1hKOmRA4GRlm",{name:"Alex Keener",first_name:"Alex",last_name:"Keener",email:"alex@example.com",createdAt:"Thu Mar 24 2020 17:46:45 GMT+0000 (UTC)",})
RudderStack uses the identify call to log the user into MoEngage in the device mode.
Identifying a device in MoEngage
You can identify a device in MoEngage using the identify call to create or update your device properties.
A sample call for identifying device is shown below:
rudderanalytics.identify("name123",{context:{device:{id:"7ase32188a4dab669f",manufacturer:"Apple",model:"IOS SDK built for x86",name:"generic_x86",token:"devtoken",type:"ios",},},})
MoEngage reserved properties
MoEngage has reserved the following property names:
name
first_name
last_name
email
age
gender
mobile
transactions
revenue
moe_unsubscribe
Also, MoEngage lets you create custom properties but you must not create properties with the names id, _id, or "" .
Track
RudderStack’s track API lets you track user events and their associated properties.
You can use the alias API to merge two different user profiles in MoEngage.
MoEngage’s user merging functionality is a closed feature and is not available by default. To enable it for your account, contact your Customer Success Manager or drop a mail to their support team.
A sample alias call made using the different RudderStack SDKs is shown below:
rudderanalytics.alias("12345","1hKOmRA4GRlm")
[[RSClientsharedInstance]alias:@"newId"];
rudderClient.alias("newId")
Supported mappings
RudderStack maps the following alias properties to the corresponding MoEngage properties:
RudderStack property
MoEngage property
Data type
message.userId Required
merged_user
String
message.previousId Required
retained_user
String
Reset
RudderStack’s reset API resets the previously identified user and the related information.
The reset API is applicable only for device mode connections.
Refer to the following snippets to implement the reset method in your mobile project:
[[RSClientsharedInstance]reset];
rudderClient.reset()
Supported mappings
RudderStack maps the following properties to the MoEngage properties before sending them using MoEngage’s HTTP API.
RudderStack property
MoEngage property
pushPreference
push_preference
active
active
userId
customer_id
name
name
firstname first_name firstName
first_name
lastname last_name lastName
last_name
email
email
age
age
gender
gender
mobile
mobile
source
source
createdAt
created_time
last_seen lastSeen
last_seen
transactions
transactions
revenue
revenue
moe_unsubscribe moeUnsubscribe
moe_unsubscribe
event
action
properties
attributes
Configuring push notifications
Depending on your platform, follow these steps to configure MoEngage push notifications in your project:
Create an APNS certificate and convert it to a .pem file.
Upload this .pem file in your MoEngage dashboard.
In the target app, turn on App Groups and enable one of the app group IDs. In case if you don’t have an app group ID, then create one. The name of your app group should be group.{bundle id}.MoEngage.
Enable Background mode by navigating to Targets > Your App > Signing & Capabilities > Select Background Modes. Then, check Remote notifications.
Enable push notification capabilities in your app.
Before initializing, add [MoEngage setAppGroupID:<your app group id>];
To keep the notifications even after the app launch, add the line [MoEngage sharedInstance].disableBadgeReset = true;
For more information on implementing push notifications in MoEngage, see the MoEngage documentation.
In-App messaging
In-app messaging is a type of mobile messaging where the notification is displayed within the app. Some examples include popups, yes/no prompts, and more. To implement this feature, follow MoEngage’s InApp NATIV guide.
Create an APNS certificate and convert it to a .pem file.
Upload this .pem file in your MoEngage dashboard.
Enable Background mode by navigating to Targets > Your App > Signing & Capabilities > Select Background Modes. Then, check Remote notifications.
Then, in your plist file, add the MoEngageAppDelegateProxyEnabled key and set it to false to disable swizzling.
For more information on implementing push notifications in MoEngage, see the MoEngage documentation.
Copy the Server Key from the FCM console and add it to the MoEngage dashboard. If you’re not sure where to find the server key, refer to this MoEngage guide.
Navigate to the Settings page of your MoEngage dashboard and add the server key and package name. Make sure you add the keys both in the Test and Live environment.
Before configuring the MoEngage SDK for receiving push notifications, make you have configured Firebase in your application.
Add the Firebase messaging dependency in your application’s build.gradle file.
Add the meta tags to manifest. To show the push notifications, you need to add the notification icons (small and large) along with the app ID to the MoEngage.Builder, as shown:
To display the notifications, you must ensure the following:
Registration for Push, that is, generating a push token.
Receiving the push payload from Firebase Cloud Messaging (FCM) and displaying the alert on the device.
These actions are handled by the application or the MoEngage SDK, depending on your preference. Refer to the following sections to configure them.
Push Registration and Receiving handled by the app
By default, the MoEngage SDK attempts to register a push token. If your application is handling the push notifications, you need to opt-out of the SDK’s token registration.
Opt out of MoEngage Registration
To opt-out of MoEngage’s token registration mechanism call the optOutTokenRegistration() method in MoEngage.Builder, as shown:
The application would need to pass the push token received from FCM to the MoEngage SDK for MoEngage to send push notifications to the device. Use the following API to pass the push token to the MoEngage SDK:
Make sure the token is passed to the MoEngage SDK whenever the push token is refreshed or your app is updated. Passing the token on application update is required to migrate to MoEngage.
Passing the push payload to the MoEngage SDK
To pass the push payload to the MoEngage SDK, call the MoEngage API from onMessageReceived() from the Firebase receiver.
Before passing the payload to the MoEngage SDK, you should check if the payload is from MoEngage using the helper API provided by the SDK.
if(MoEPushHelper.getInstance().isFromMoEngagePlatform(remoteMessage.data)){MoEFireBaseHelper.getInstance().passPushPayload(applicationContext,remoteMessage.data)}else{// your app's business logic to show notification
}
Push registration and receiving handled by SDK
Add the following code in your manifest file within the application tag:
When the MoEngage SDK handles push registration it optionally provides a callback to the application whenever a new token is registered or token is refreshed.
An application can get this callback by implementing FirebaseEventListener and registering for a callback in the application class’ onCreate() using MoEFireBaseHelper.getInstance().setEventListener().
In-App messaging
In-app messaging is a type of mobile messaging where the notification is displayed within the app. Some examples include popups, yes/no prompts, and more. To implement this follow the MoEngage InApp NATIV guide.
Open the android folder of your React Native app and follow all steps listed in the Android tab in this section.
Open the ios folder of your React Native app and follow all steps listed in the iOS tab in this section.
Timezone offset for cloud mode
Track
MoEngage allows sending the time at which the event occurred and calculates the user local time by taking two parameters - current_time and user_timezone_offset. current_time is the UTC time at which the event occurred and user_timezone_offset is the time difference (in seconds) between the user local time and UTC.
Note the following:
RudderStack maps the current_time to timestamp or originalTimestamp from the event payload. Hence, you must pass these values in UTC.
RudderStack maps user_timezone_offset to timezone present in the context object of the event’s payload. You must pass this value as a string tz.
The RudderStack mobile SDKs automatically populate the timezone field. However, for the other sources like server-side SDKs or HTTP API, you must explicitly set the timezone field in every request.
A sample track payload is shown below:
{"type":"track","event":"Email Replied","sentAt":"2020-12-02T11:30:33.262Z","context":{"library":{"name":"analytics-node","version":"0.0.3"},"timezone":"Asia/Kolkata"},"rudderId":"87a40cf3-f6d8-4675-bc01-7854ab4486ec","_metadata":{"nodeVersion":"10.22.0"},"messageId":"node-7519b5f2fcacca521c7a9e8ddb9fc09c-c273004b-6968-422d-a511-440b6db24403","properties":{"details":"list of details"},"anonymousId":"anony11111111111","originalTimestamp":"2020-12-02T11:30:33.259Z"}
Identify
MoEngage accepts the user creation time for its User endpoint. This is reflected as first_seen in the MoEngage dashboard.
RudderStack sets the created_time field in MoEngage from the createdAt field present in the event payload. This value should be in the ISO 8601 format. If the value is absent or present in an improper format, MoEngage assigns the value automatically.
Where can I see the events that are sent to MoEngage?
To view the events sent to MoEngage, go to For developers > Recent Events in your MoEngage dashboard. If your app is in debug mode, then you can view the events under the Test tab, otherwise you can view them under the Live tab.
This site uses cookies to improve your experience while you navigate through the website. Out of
these
cookies, the cookies that are categorized as necessary are stored on your browser as they are as
essential
for the working of basic functionalities of the website. We also use third-party cookies that
help
us
analyze and understand how you use this website. These cookies will be stored in your browser
only
with
your
consent. You also have the option to opt-out of these cookies. But opting out of some of these
cookies
may
have an effect on your browsing experience.
Necessary
Always Enabled
Necessary cookies are absolutely essential for the website to function properly. This
category only includes cookies that ensures basic functionalities and security
features of the website. These cookies do not store any personal information.
This site uses cookies to improve your experience. If you want to
learn more about cookies and why we use them, visit our cookie
policy. We'll assume you're ok with this, but you can opt-out if you wish Cookie Settings.