MoEngage destination

Send your events from RudderStack to MoEngage.

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.

Getting started

RudderStack supports sending event data to MoEngage via the following connection modes:

Connection ModeWebMobileServer
Device ModeSupportedSupported-
Cloud ModeSupportedSupportedSupported
info
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.

Once you have confirmed that the source platform supports sending events to MoEngage, follow these steps:

  1. From your RudderStack dashboard, add a source. Then, from the list of destinations, select MoEngage.
  2. 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.
info
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.

The following settings are applicable for the RudderStack JavaScript SDK:

  • 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.
  • OneTrust Cookie Categories: This setting lets you associate OneTrust cookie consent groups to MoEngage.

Adding device mode integration

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:

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)",
})
info
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.

A sample track call is shown below:

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

You can use the alias API to merge two different user profiles in MoEngage.

warning
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:

Supported mappings

RudderStack maps the following alias properties to the corresponding MoEngage properties:

RudderStack propertyMoEngage propertyData type
message.userId
Required
merged_userString
message.previousId
Required
retained_userString

Reset

RudderStack’s reset API resets the previously identified user and the related information.

warning
The reset API is applicable only for device mode connections.

Refer to the following snippets to implement the reset method in your mobile project:

Supported mappings

RudderStack maps the following properties to the MoEngage properties before sending them using MoEngage’s HTTP API.

RudderStack propertyMoEngage property
pushPreferencepush_preference
activeactive
userIdcustomer_id
namename
firstname
first_name
firstName
first_name
lastname
last_name
lastName
last_name
emailemail
ageage
gendergender
mobilemobile
sourcesource
createdAtcreated_time
last_seen
lastSeen
last_seen
transactionstransactions
revenuerevenue
moe_unsubscribe
moeUnsubscribe
moe_unsubscribe
eventaction
propertiesattributes

Configuring push notifications

Depending on your platform, follow these steps to configure MoEngage push notifications in your project:

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.

info

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.

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

A sample identify payload is shown below:

{
  "type": "identify",
  "sentAt": "2020-12-02T13:04:05.953Z",
  "traits": {
    "city": "Bangalore",
    "name": "lolo",
    "email": "lolo@website.com",
    "country": "India",
    "createdAt": "2020-12-02T12:29:53.872Z"
  },
  "userId": "111its111",
  "context": {
    "traits": {
      "city": "Bangalore",
      "name": "lolo",
      "email": "lolo@website.com",
      "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"
}

FAQ

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

You can find your MoEngage API ID and API key in your MoEngage dashboard under Settings > APIs > DATA API Settings.

For more information, refer to the MoEngage documentation.

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.


Questions? Contact us by email or on Slack