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!

MoEngage WebSDK offers the capability to send push notifications to Google Chrome, Opera and Firefox browsers. There are some additional steps apart from integrating Segment’s analytics.js.

Integration

Setup your MoEngage Web SDK settings at MoEngage Dashboard

Please setup the web settings on the MoEngage dashboard in order to start using MoEngage <> Segment integration.

If you have selected HTTPS mode of integration in the settings, there are some additional steps to be taken

Set up for HTTPS websites

Download the required files (HTTPS only)

For HTTPS Web Push to work, you need to host two files in the root directory of your web server. These two files will be available for you to download at the web settings page.

  • manifest.json
  • serviceworker.js

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.

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.

Reset

If your website supports the ability for a user to logout and login with a new identity, then you’ll need to call reset method in analytics.js.

Test Mode and Debugging

While updating the MoEngage settings on the Segment Dashboard, you can enable the logging functionality of the MoEngage SDK to see the SDK logs on the browser console. Just set Enable Debug Logging to On and the SDK will be loaded in debug mode.

NOTE: When debug mode is enabled, the events and attributes of the users are sent to the TEST environment of your MoEngage App.

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:

Setup Segment SDK:

Now head to the the App Delegate, and setup the Segment SDK :

Objective-C:

 #import <SEGMoEngageIntegrationFactory.h> // This line is key for MoEngage integration
 #import <SEGAnalytics.h>

 - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {

    // Add your configuration key from Segment
    SEGAnalyticsConfiguration *config = [SEGAnalyticsConfiguration configurationWithWriteKey:@"configuration key"];

    // Add MoEngageIntegrationFactory. Without this data will not come to MoEngage.
    [config use:[SEGMoEngageIntegrationFactory instance]];
    [SEGAnalytics setupWithConfiguration:config];
  }

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.

```[[SEGAnalytics sharedAnalytics] reset];



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.


#### Push Notifications:
Push Notifications are a great way to keep your users engaged and informed about your app. You have following options while implementing push notifications in your app:

**Segment Push Implementation:**

1.Follow the directions to register for push using Segment SDK in this [link](https://segment.com/docs/libraries/ios/#how-do-i-use-push-notifications-).

2.In your application’s application:didReceiveRemoteNotification: method, add the following:

```[[SEGAnalytics sharedAnalytics] receivedRemoteNotification:userInfo];

3.If you integrated the application:didReceiveRemoteNotification:fetchCompletionHandler: in your app, add the following to that method:

```[[SEGAnalytics sharedAnalytics] receivedRemoteNotification:userInfo];


4.If you implemented handleActionWithIdentifier:forRemoteNotification:, add the following to that method:

```[[SEGAnalytics sharedAnalytics] handleActionWithIdentifier:identifier forRemoteNotification:userInfo];

Follow this link to implement Push Notification in your mobile app using MoEngage SDK : Push Notifications

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 Initialise MoEngage SDK:

Get APP ID from the Settings Page on the MoEngage dashboard and initialise the MoEngage SDK in the Application class’s onCreate()

Analytics analytics = new Analytics.Builder(getApplicationContext(),"writeKey")//use your own write key
            .logLevel(Analytics.LogLevel.VERBOSE)// should be added only in debug builds. Make sure this is removed before a signed apk is generated.
            .use(MoEngageIntegration.FACTORY)//enable MoEngage integration
            .build();
// this is the instance of the application class and "XXXXXXXXXXX" is the APP ID from the dashboard.
MoEngage moEngage = new MoEngage.Builder(this, "XXXXXXXXXXX")
            .enableSegmentIntegration()
            .build();
    MoEngage.initialise(moEngage);

How To - Push Notifications:

1. Adding meta information for push notification.

Along with the App Id and the notification small icon large icon and sender id(only if using GCM library) to the builder.

MoEngage moEngage =
        new MoEngage.Builder(this, "XXXXXXXXXX")
            .setSenderId("xxxxxxx")
            .setNotificationSmallIcon(R.drawable.icon)
            .setNotificationLargeIcon(R.drawable.ic_launcher)
            .enableSegmentIntegration()
            .build();
    MoEngage.initialise(moEngage);
2. Push Token

By default the SDK registers for push token. In case your application already has a mechanism to register for push token disable push token registration by using the opt-out as shown below

MoEngage moEngage =
        new MoEngage.Builder(this, "XXXXXXXXXX")
            .setNotificationSmallIcon(R.drawable.icon)
            .setNotificationLargeIcon(R.drawable.ic_launcher)
            .optOutTokenRegistration()
            .enableSegmentIntegration()
            .build();
    MoEngage.initialise(moEngage);

Once you have opted out of push token registration pass the token to MoEngage SDK, the application should pass the token to MoEngage SDK from the Registration Service used for getting the push token.

PushManager.getInstance().refreshToken(getApplicationContext(), token);

In case you are allowing MoEngage SDK to register for push but also want the token for internal usage you can get the token by implementing PushManager.OnTokenReceivedListener in your Application class

public class DemoApp extends Application implements PushManager.OnTokenReceivedListener{
  public void onCreate() {
    PushManager.getInstance().setTokenObserver(this);
  }
  @Override public void onTokenReceived(String token) {
        //save token for your use
    }
}
3. Configure FCM or GCM

Based on whether you are using FCM or GCM move to library specific configuration.

  1. Configuring FCM
  2. Configuring GCM
4. Configure Geo-fence

By default SDK does not track location neither geo-fence campaigns work by default. To track location and run geo-fence campaigns you need to opt-in for location service in the MoEngage initialiser. To initialise call the below opt-in API.

    MoEngage moEngage =
        new MoEngage.Builder(this, "XXXXXXXXXXX")
            .enableLocationServices()
            .enableSegmentIntegration()
            .build();
    MoEngage.initialise(moEngage);

Note: For Geo-fence pushes to work your Application should have location permission and Play Services’ Location Library should be included.

For more details on refer to the Configuring Geo-Fence section in the MoEngage documentation.

5. 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>
6. Data Redirection

In case your app wants to re-direct data to a specific zone because of any data regulation policy please configure the zone in the MoEngage initialiser object as shown below.

    MoEngage moEngage = 
        new MoEngage.Builder(this, "XXXXXXXXXXX")
            .redirectDataToRegion()// add the required region here.
            .build();
    MoEngage.initialise(moEngage);

Supported Regions

    REGION_INDIA, 
    REGION_EU

Refer to the API documentation for more details.

Note: If you are redirecting your data to the European Region please sign-up using the following URL.

Now log on to MoEngage Dashboard Settings and add the Server Key from the Firebase Console. Also update the app package name. If you are not sure where to find the server key refer to this documentation.

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


Personas

You can send computed traits and audiences generated through Segment Personas to this destination as a user property. To learn more about Personas, reach out for a demo.

For user-property destinations, an identify call will be sent to the destination for each user being added and removed. The property name will be the snake_cased version of the audience name you provide with a true/false value. For example, when a user first completes an order in the last 30 days, we will send an identify call with the property order_completed_last_30days: true, and when this user no longer satisfies we will set that value to false.

When the audience is first created an identify call is sent for every user in the audience. Subsequent syncs will only send updates for those users which were added or removed since the last sync.

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.

We offer an optional Cloud-based Connection Mode for Web data with MoEngage. As a reminder, this removes the MoEngage javascript library from your site, improving performance. Segment offers an optional Device-based Connection Mode for Mobile data with MoEngage. If you’d like to use those features that require client-based functionality, 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.