MoEngage

Step-by-step guide to set up MoEngage as a destination in RudderStack

MoEngage is an intelligent customer engagement platform that allows you to effectively engage with your customers throughout their product journey. It allows you to track and map your customer life-cycle across various touchpoints, and optimize their customer experience at each stage.

With MoEngage, you can effectively deliver personalized communication to your customers and thereby increase overall customer engagement and audience retention.

RudderStack now supports MoEngage as a destination to seamlessly send your event data in real-time.

Find the open-source transformer code for this destination in our GitHub repo.

Getting Started

Before configuring your source and destination on the RudderStack, please verify if the source platform is supported by MoEngage, by referring to the table below:

Connection Mode	Web	Mobile	Server
Device Mode	Supported	Supported	-
Cloud Mode	Supported	Supported	Supported

To know more about the difference between Cloud mode and Device mode in RudderStack, read the RudderStack connection modes guide.

Once you have confirmed that the platform supports sending events to MoEngage, perform the steps below:

• From your RudderStack dashboard, add the source. From the list of destinations, select MoEngage.

• Give a name to the destination and click on Next. You should then see the following screen:

In the Connection Settings on the RudderStack dashboard, please enter the MoEngage API ID, API Key, and Region, as shown above.

By turning on the native SDK switch under Android SDK Settings on the RudderStack dashboard you can enable Rudder Stack Device Mode for Android Sources. Similarly for Web Under Web SDK Settings and IOS under iOS SDK Settings.

Choose EU in the Region field to send your event data to the MoEngage Europe server. To send your event data to the MoEngage India server, choose IND.

Adding Device Mode Integration

iOS Android React Native Follow these steps to add MoEngage to your iOS project:

1. Go to your Podfile and add the Rudder-Moengage extension:

   pod 'Rudder-Moengage'

2. After adding the dependency followed by pod install, you can add the imports to your AppDelegate.m file, as shown:

   #import "RudderMoengageFactory.h"

3. Finally, change the initialization of your RudderClient, as shown:

   RudderConfigBuilder *builder = [[RudderConfigBuilder alloc] init];
   [builder withDataPlaneUrl:DATA_PLANE_URL];
   [builder withFactory:[RudderMoengageFactory instance]];
   [RudderClient getInstance:WRITE_KEY config:[builder build]];

Follow these steps to add MoEngage to your Android project:

1. Open your app/build.gradle (Module: app) file and add the following:

   repositories {
       mavenCentral()
   }

2. Add the following under the dependencies section:

   implementation 'com.rudderstack.android.sdk:core:1.+'
   implementation 'com.rudderstack.android.integration:moengage:1.0.0'
   api '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'

3. Also, add the below plugin after buildscript:

   // For Push Notification
   apply plugin: 'com.google.gms.google-services'

4. 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.4'
       }
   }

5. Initialize the RudderStack SDK in the Application class's onCreate() method, as shown:

   // initializing Rudder SDK
   val rudderClient = RudderClient.getInstance(
       this,
       WRITE_KEY,
       RudderConfig.Builder()
           .withDataPlaneUrl(DATA_PLANE_URL)
           .withFactory(MoengageIntegrationFactory.FACTORY)
           .build()
   )

6. Initialize the MoEngage SDK in the Application class's onCreate() method:

   // this is the instance of the application class
   // and "XXXXXXXXXXX" is the APP ID from the dashboard.
   val moEngage = MoEngage.Builder(this, "XXXXXXXXXXX")
           .build()
   MoEngage.initialise(moEngage)

Follow these steps to add MoEngage to your React Native project:

1. 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

2. Import the above module and add it to your SDK initialization, as shown:

   import rudderClient from "@rudderstack/rudder-sdk-react-native"
   import moengage from "@rudderstack/rudder-integration-moengage-react-native"
   const config = {
     dataPlaneUrl: <DATA_PLANE_URL>,
     trackAppLifecycleEvents: true,
     withFactories: [moengage],
   }
   rudderClient.setup( <WRITE_KEY> , config)

3. Add the following under the dependencies section of 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'

4. In the android/build.gradle (Module: Project) file, add the following:

   repositories {
     mavenCentral()
   }

5. 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'
     }
   }

6. Also, add the following plugin at the top of android/app/build.gradle (Module: app):

   // For Push Notification
   apply plugin: 'com.google.gms.google-services'

7. Initialize the MoEngage SDK in the Application class' onCreate() method, as shown:

   // MoEngage SDK initialisation: Replace "xxxxxxx" with your APP ID.
   MoEngage moEngage = new MoEngage
     .Builder(MainActivity.this.getApplication(), "xxxxxxx")
     .enableLogs(LogLevel.VERBOSE)
     .build();
   MoEngage.initialise(moEngage);

Identify

To identify a user to MoEngage, you need to call the identify API.

For information on the identify call, please refer to our RudderStack API Specification guide.

MoEngage needs a unique identifier to identify a user. So, if you provide userId in your identify call, RudderStack passes it as that customer_id . Otherwise, it sends an anonymousId if a userId is not present.

You can also create a new user property or update existing user properties of the users using the identify API.

A sample identify call is as shown:

rudderanalytics.identify("name123", {
  name: "Name Surname",
  first_name: "Name",
  last_name: "Surname",
  email: "[e-mail]",
  createdAt: "Thu Mar 24 2020 17:46:45 GMT+0000 (UTC)",
})

Identify api will be used to Login the user into MoEngage in Device Mode

MoEngage Reserved Properties

The following property names are reserved by MoEngage:

• name

• first_name

• last_name

• email

• age

• gender

• mobile

• transactions

• revenue

• moe_unsubscribe

You may create custom properties but you should not create properties with the following names "id", "_id", or "" .

Identifying a Device to MoEngage

You can also identify a device to MoEngage , using the identify API. With this API, you can create new properties or update the existing properties of the device.

A sample call for identifying device is as shown:

rudderanalytics.identify("name123", {
  context: {
    device: {
      id: "7ase32188a4dab669f",
      manufacturer: "Apple",
      model: "IOS SDK built for x86",
      name: "generic_x86",
      token: "devtoken",
      type: "ios",
    },
  },
})

Track

To track your users' actions, you can use the RudderStack track API. You can call track with eventname and the associated properties.

For information on the track call, please refer to our RudderStack API Specification guide.

A sample track call is as shown:

rudderanalytics.track("Order Completed", {
  checkout_id: "C324532",
  order_id: "T1230",
  value: 15.98,
  revenue: 16.98,
  shipping: 3.0,
  coupon: "FY21",
  currency: "INR",
  products: [
    {
      product_id: "product-mixedfruit-jam",
      sku: "sku-1",
      category: "Food",
      name: "Food/Drink",
      brand: "Sample",
      variant: "None",
      price: 10.0,
      quantity: 2,
      currency: "INR",
      position: 1,
      value: 6.0,
      typeOfProduct: "Food",
      url: "https://www.example.com/product/bacon-jam",
      image_url: "https://www.example.com/product/bacon-jam.jpg",
    },
  ],
})

Alias

The Alias api is used to merge two different profiles of a same user into a single profile.

Alias call can be done only through mobile sdks.

For more information, please refer to our RudderStack API Specification guide.

iOS Android

• Run the following command to implement the alias method in your iOS project:

  [[RSClient sharedInstance]  alias:@"newId"];

Run the following command to implement the `alias` method in your Android project:

rudderClient.alias("newId")

Reset

The reset method resets the previously identified user and the related information. For more information, please refer to our RudderStack API Specification guide.

iOS Android Run the following command to implement the reset method in your iOS project:

[[RSClient sharedInstance] reset];

Run the following command to implement the reset method in your Android project:

rudderClient.reset()

RESET api is applicable only for Device Mode Connections

Supported mappings

RudderStack maps the following properties to the MoEngage properties before sending them over 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

iOS Android Web React Native

• To send push notifications in iOS an APNS certificate needs to be created and has to be converted to .pem file.

• This .pem file needs to be uploaded in the 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.

• Turn on Background mode and set/enable Remote Notification.

• Turn on push notification capabilities in your app.

• Before initializing add [MoEngage setAppGroupID:<your app group id>];

• In case if you would like to keep the notifications even after the App Launch then : [MoEngage sharedInstance].disableBadgeReset = true;

For more detailed steps please follow MoEngage guidelines here.

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, interstitials, and more. To implement this please follow this guide: InApp NATIV. Copy the Server Key from the FCM console and add it to the MoEngage Dashboard(Not sure where to find the Server Key refer to Getting FCM Server Key. To upload it, go to the Settings Page and add the Server Key and package name. **Please make sure you add the keys both in the Test and Live environment.** Before configuring MoEngage SDK for receiving push notifications please make you have configured Firebase in your application, if not done already refer to the documentation and complete setup. Also, make sure you have added the Firebase Messaging dependency in your application build.gradle file.

Adding meta for push notification

To show push notifications you need to add the notification small icon and large icon along with the AppId to the MoEngage.Builder

val moEngage = MoEngage.Builder(this, "XXXXXXXX")
        .setNotificationSmallIcon(R.drawable.icon)
        .setNotificationLargeIcon(R.drawable.ic_launcher)
        .build()
MoEngage.initialise(moEngage)

For showing Push notifications there are 2 important things

1. Registration for Push, i.e. generating push token.

2. Receiving the Push payload from Firebase Cloud Messaging(FCM) service and showing the notification on the device. The above can either be handled by the application or MoEngage SDK. There is some configuration required based on whether the above-mentioned things are handled by the application or SDK.

Push Registration and Receiving handled by App

By default, MoEngage SDK attempts to register for push token, since your application is handling push you need to opt-out of SDK's token registration.

How to opt-out of MoEngage Registration?

To opt-out of MoEngage's token registration mechanism call in the optOutTokenRegistration() on the MoEngage.Builder as shown below

val moEngage = MoEngage.Builder(this, "XXXXXXXX")
        .setNotificationSmallIcon(R.drawable.icon)
        .setNotificationLargeIcon(R.drawable.ic_launcher)
        .configureFcm(FcmConfig(false))
        .build()
MoEngage.initialise(moEngage)

Pass the Push Token To MoEngage SDK

The Application would need to pass the Push Token received from FCM to the MoEngage SDK for the MoEngage platform to send out push notifications to the device. Use the below API to pass the push token to the MoEngage SDK.

MoEFireBaseHelper.getInstance().passPushToken(applicationContext, token)

_Note:_ Please make sure token is passed to MoEngage SDK whenever push token is refreshed and on application update. Passing token on application update is important for migration to the MoEngage Platform.

Passing the Push payload to the MoEngage SDK

To pass the push payload to the MoEngage SDK call the MoEngage API from the `onMessageReceived()` from the Firebase receiver. Before passing the payload to the MoEngage SDK you should check if the payload is from the MoEngage platform 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 below code in your manifest file within the application tag

<service android:name="com.moengage.firebase.MoEFireBaseMessagingService">
  <intent-filter>
    <action android:name="com.google.firebase.MESSAGING_EVENT" />
  </intent-filter>
</service>

When 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. Examples include popups, yes/no prompts, interstitials, and more. To implement this please follow: InApp NATIV

• Go to Web Push Settings.
• Under Web fill in the details as required.

• For HTTPS Web Push to work, you need to host two files in the root directory of your web server.

• After clicking **SAVE**, please proceed to download serviceworker.js file. Under Web Push Settings.
• In case you already have your own serviceworker.js add :

  importScripts(
    "https://cdn.moengage.com/webpush/releases/serviceworker_cdn.min.latest.js"
  )

• HTTP : Select a sub-domain. For more details please follow the guidelines from MoEngage.
• Open the android folder of your React Native app and follow all the steps listed in the Android tab of the Configuring Push Notifications section.
• Open the ios folder of your React Native app and follow all the steps listed in the iOS tab of the Configuring Push Notifications section.

Debugging in Web SDK

From the RudderStack dashboard, turn on the debug mode to get debug logs. The events will be seen under the Test section of the particular app in MoEngage.

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 where the current_time is UTC Time at which the event happened, and user_timezone_offset is the difference in seconds between the user local time and UTC.

The RudderStack transformer maps the current_time to timestamp or originalTimestamp value from the event payload sent to Rudder server. This value should be passed in UTC.

The user_timezone_offset is mapped to timezone field present under the context object of the event payload. This value should be passed as tz string. Rudder mobile SDKs populate the timezone field by itself. But for other sources like server like SDKs, HTTP api, the timezone needs to be set explicitly in every request.

Example payload:

{
  "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 user creation time for its user endpoint. This is reflected as first_Seen in their dashboard.

The RudderStack transformer maps the created_time from the createdAt spec'd traits in our payload. The value should be in the ISO 8601 format. If the value is not in proper format or not present, MoEngage will put in the value by itself.

An example payload is as shown:

{
  "type": "identify",
  "sentAt": "2020-12-02T13:04:05.953Z",
  "traits": {
    "city": "Bangalore",
    "name": "lolo",
    "email": "[e-mail]",
    "country": "India",
    "createdAt": "2020-12-02T12:29:53.872Z"
  },
  "userId": "111its111",
  "context": {
    "traits": {
      "city": "Bangalore",
      "name": "lolo",
      "email": "[e-mail]",
      "country": "India",
      "createdAt": "2020-12-02T12:29:53.872Z"
    },
    "library": {
      "name": "analytics-node",
      "version": "0.0.3"
    }
  },
  "rudderId": "754fe90e-89fb-4d71-9d11-3ec2b91b5777",
  "_metadata": {
    "nodeVersion": "10.22.0"
  },
  "messageId": "node-1a585828272cf1116407aaf6be3921f2-65c1670e-f4e1-4283-a7a5-0a60825c4f83",
  "originalTimestamp": "2020-12-02T13:04:05.951Z"
}

FAQs

Where can I find my MoEngage API ID and API KEY?

You can find your MoEngage API ID and API KEY in your moengage.com account under Settings > APIs > DATA API Settings.

Where can I see the events that are going to MoEngage?

If your app is in debug mode then you can see under Test otherwise you can see under Live. Go to For developers --> Recent Events.

Contact Us

If you come across any issues while configuring or using MoEngage with RudderStack, please feel free to contact us. You can also start a conversation in our Slack community; we will be happy to talk to you!