MoEngage Destination

Segment makes it easy to send your data to MoEngage (and lots of other destinations). Once you've tracked your data through our open source libraries we'll translate and route your data to MoEngage in the format they understand. Learn more about how to use MoEngage with Segment.

Getting Started

Once the Segment library is integrated with your app, toggle MoEngage on in your Segment destinations. These new settings will take up to an hour to propogate to all of your existing users. For new users it’ll be instanteneous! Segment-MoEngage destination is a bundled destination, requires client side destination.

Follow the steps below to integrate this destination

Web

IMPORTANT: If you need to use web push notification features when integrating the JS integration, please refer to MoEngage’s documentation on setting up your manifest.json and serviceworker.js. The Web Push feature does not work unless you complete their instructions!

iOS

To get started with MoEngage on iOS, first integrate your app with the MoEngage iOS library. To get the APP ID, login to your account, click on Settings in the left menu and select App Settings, here we show the APP ID of your app. Next, go to Push Settings, and select iOS Settings tab, upload the pem file for Push Notifications here and enter the password for the same. If you don’t have the pem already, follow the steps listed here. Finally, you want to ensure you have configured your app delegate to enable push notifications.

For more information on features provided in MoEngage iOS SDK refer to following links:

Identify

Use Identify to track user specific attributes. It equivalent to tracking user attributes on MoEngage. MoEngage supports traits supported by Segment as well as custom traits. If you set traits.id, we set that as the Unique ID for that user.

Track

Use track to track events and user behaviour in your app. This will send the event to MoEngage with the associated properties. Tracking events is essential and will help you create segments for engaging users differently.

You can use these .track() events and properties to create your MoEngage push campaigns and conversions.

Reset / Handling Logout

If your app supports the ability for a user to logout and login with a new identity, then you’ll need to call our mobile libraries’ reset method in your mobile app. Here we will call MoEngage’s resetUser implementation to ensure the previous user information is not overwritten.

If you are using MoEngage JS integration, you do not have to worry about handling logout/resets as if you call .identify() with a new userId, we will destroy the previous session before creating a new one. However, for best practices, you should always be calling analytics.reset() when a user logs out before you call .identify() for the new user to ensure that you don’t leak previous traits from the old user to the new.

Android

To get up and running with MoEngage on Android, there a couple of steps we will walk you through.

To enable its full functionality (like Push Notifications, InApp Messaging, Acquisition Tracking), there are still a couple of steps that you have to take care of in your Android app.

Adding MoEngage Dependency:

Along with the segment dependency add the below dependency in your build.gradle file.

compile(‘com.moengage:moengage-segment-integration:+’) { transitive = true }

How To - Push Notifications:

  1. Manifest permissions: Copy the permissions XML below into the AndroidManifest.xml and insert your package name into the name fields where it says [YOUR_PACKAGE_NAME/applicationId].

    <uses-permission android:name="android.permission.INTERNET" />
    <permission android:name="[YOUR_PACKAGE_NAME/applicationId].permission.C2D_MESSAGE" android:protectionLevel="signature" />
    <uses-permission android:name="[YOUR_PACKAGE_NAME/applicationId].permission.C2D_MESSAGE" />
    <uses-permission android:name="com.google.android.c2dm.permission.RECEIVE" />
    <uses-permission android:name="android.permission.GET_ACCOUNTS" />
    <uses-permission android:name="android.permission.WAKE_LOCK" />
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
    <!-- If you want to use our Geo Fencing feature  -->
    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>
    
  2. Declaring Receivers: Add the below components into the AndroidManifest.xml and replace [YOUR_PACKAGE_NAME/applicationId] with your package name or application id for Push.

When using Play Services 7.3

<!-- MOENGAGE RECEIVER FOR RECEIVING GCM BROADCAST MESSAGES -->
<receiver
  android:name="com.moengage.receiver.MoEngagePushReceiver"
  android:permission="com.google.android.c2dm.permission.SEND" >
  <intent-filter>
    <action android:name="com.google.android.c2dm.intent.RECEIVE" />
    <action android:name="com.google.android.c2dm.intent.REGISTRATION" />
    <category android:name="[YOUR_PACKAGE_NAME/applicationId]" />
  </intent-filter>
</receiver>

When using Play Services 7.5 and above

<receiver
    android:name="com.google.android.gms.gcm.GcmReceiver"
    android:exported="true"
    android:permission="com.google.android.c2dm.permission.SEND" >
    <intent-filter>
        <action android:name="com.google.android.c2dm.intent.RECEIVE" />
        <category android:name="[YOUR_PACKAGE_NAME/applicationId]" />
    </intent-filter>
</receiver>
<service
    android:name="com.moengage.worker.MoEGCMListenerService"
    android:exported="false" >
    <intent-filter>
        <action android:name="com.google.android.c2dm.intent.RECEIVE" />
        <action android:name="com.google.android.c2dm.intent.REGISTRATION" />
    </intent-filter>
</service>
<service
    android:name="com.moengage.receiver.MoEInstanceIDListener"
    android:exported="false">
    <intent-filter>
        <action android:name="com.google.android.gms.iid.InstanceID"/>
    </intent-filter>
</service>

Add the below components into the AndroidManifest.xml for Install Intents

<!-- MOENGAGE RECEIVER FOR RECEIVING INSTALLATION INTENT -->
<receiver android:name="com.moe.pushlibrary.InstallReceiver" >
  <intent-filter>
    <action android:name="com.android.vending.INSTALL_REFERRER" />
  </intent-filter>
</receiver>
  1. Declaring MoEngage Specific Meta Tags: Add the following meta tags into the AndroidManifest.xml. Description of each meta tag and its value:

    • [APP_ID] : MoEngage App Id which you can find under AppSettings on MoEngage Dashboard
    • [SENDER_ID] : The Google Project Number as seen on Google Developer console. This is required for GCM registration.
    • [NOTIFICATION_ICON]: The Small Notification icon which needs to be shown. The value must be just the image file name.
    • [NOTIFICATION_LARGE_ICON]: The large notification icon which will be used for notifications on Lollipop and above. The value must be just the image file name.
    • [NOTIFICATION_TYPE]: Whether its multiple or single. By default it is single but specified @integer/notification_type_multiple it will be able to show multiple notifications as one go.
    • [NOTIFICATION_TONE]: The Notification Tone which will be used to play when the notification is shown. By Default it is picked up from system settings but setting the sound file name will play that sound. Remember the value has to be just the sound file name.
    <!-- MANDATORY FIELD: APP ID AS SEEN ON MOENGAGE DASHBOARD APP SETTINGS PAGE -->
    <meta-data
     android:name="APP_ID"
     android:value="[MOENGAGE_APP_ID]" />
    <!-- MANDATORY FIELD: SENDER ID , i.e. THE PROJECT NUMBER AS MENTIONED ON GOOGLE CLOUD CONSOLE PROJECTS PAGE -->
    <meta-data
     android:name="SENDER_ID"
     android:value="id:[SENDER_ID]" />
    <!-- MANDATORY FIELD: THE NOTIFICATION SMALL ICON WHICH WILL BE USED TO SET TO NOTIFICATIONS POSTED -->
    <meta-data
     android:name="NOTIFICATION_ICON"
     android:value="ic_launcher" />
    <!-- MANDATORY FIELD: THE NOTIFICATION LARGE ICON WHICH WILL BE USED TO SET TO NOTIFICATIONS POSTED -->
    <meta-data
    android:name="NOTIFICATION_LARGE_ICON"
    android:value="large_icon" />
    <!-- OPTIONAL FIELD: THE NOTIFICATION TYPE WHICH WILL BE USED, SINGLE OR MULTIPLE. DEFAULT BEHAVIOR IS SINGLE -->
    <meta-data
     android:name="NOTIFICATION_TYPE"
     android:value="@integer/notification_type_multiple" />
    <!-- OPTIONAL FIELD: THE NOTIFICATION TONE THAT WILL BE USED. IF NOT SET WILL PLAY THE DEFAULT SOUND -->
    <meta-data
     android:name="NOTIFICATION_TONE"
     android:value="tring" />
    
  2. Declaring & configuring Rich Landing Activity: Add the following snippet and replace [PARENT_ACTIVITY_NAME] with the name of the parent activity; [ACTIVITY_NAME] with the activity name which should be the parent of the Rich Landing Page

    <activity
     android:name="com.moe.pushlibrary.activities.MoEActivity"
     android:label="[ACTIVITY_NAME]"
     android:parentActivityName="[PARENT_ACTIVITY_AME]" >
     <!-- Parent activity meta-data to support 4.0 and lower -->
     <meta-data
         android:name="android.support.PARENT_ACTIVITY"
         android:value="[PARENT_ACTIVITY_AME]" />
    </activity>
    

Install/Update Differentiation

We need your help to tell the SDK whether the user is a new user or an existing user. You can check for an existing SharedPreferences value and confirm whether its a fresh user or an existing user.

SharedPreferences pref = context.getSharedPreferences(PREF_NAME, Context.MODE_PRIVATE);
if( pref.contains("your_key")){
    helper.setExistingUser(true);
}else{
    helper.setExistingUser(false);
}

In the above code “your_key” is something you expect in the shared preference file if the app has been run at least once before. Possible values might be (firstRun, AppVersion, SenderId, Push Token, etc)

This code should be done in your Application class and should be called only once If this code is not added INSTALL InApp/Push Campaigns will not work

Now log on to MoEngage Dashboard and go to Push Platform Settings section. Add the GCM API Key which you have generated from the Google Developer console API Access for GCM Module. Also update the app package name.

You are now all setup to receive push notifications from MoEngage. For more information on features provided in MoEngage Android SDK refer to following links:

Identify

Use Identify to track user specific attributes. It equivalent to tracking user attributes on MoEngage. MoEngage supports traits supported by Segment as well as custom traits. If you set traits.id, we set that as the Unique ID for that user.

Track

Use track to track events and user behaviour in your app. This will send the event to MoEngage with the associated properties. Tracking events is essential and will help you create segments for engaging users differently.

You can use these .track() events and properties to create your MoEngage push campaigns and conversions.

Reset / Handling Logout

If your app supports the ability for a user to logout and login with a new identity, then you’ll need to call our mobile libraries’ reset method in your mobile app. Here we will call MoEngage’s resetUser implementation to ensure the previous user information is not overwritten.

If you are using MoEngage JS integration, you do not have to worry about handling logout/resets as if you call .identify() with a new userId, we will destroy the previous session before creating a new one. However, for best practices, you should always be calling analytics.reset() when a user logs out before you call .identify() for the new user to ensure that you don’t leak previous traits from the old user to the new.

Migrating from older version(One time process)

Please refer to this link to migrate from SDK version less than 2.0.00

Sample Implementation

Refer to this github repository for sample implementation


Supported Sources and Connection Modes

WebMobileServer
📱 Device-based
☁️ Cloud-based

To learn more about about Connection Modes and what dictates which we support, see here.

This destination requires a Device-based Connection Mode for Mobile data. Follow the steps above to ensure you have packaged the MoEngage SDK with Segment’s.

Settings

Segment lets you change these destination settings via your Segment dashboard without having to touch any code.

APP ID

You can find the APP_ID key under App Settings on the MoEngage dashboard. Please make sure you have uploaded the pem file for sending push on iOS and GCM Key for Android.

Enable Debug Logging

If you are in TEST mode and would like debug logs in your browser console, enable this setting. You should not have this option enabled for your production sources.


If you have any questions or see anywhere we can improve our documentation, please let us know or kick off a conversation in the Segment Community!