Configuring Xiaomi Push

📘

If you are using the Push Amp Plus version below 2.0.00 refer to the Push Amp Plus Legacy documentation.

Configure your account on MoEngage

Go to the Settings Page Dashboard --> Settings --> Channel --> Push --> Mobile Push --> Push Amp+ on the MoEngage Dashboard and add the Xiaomi Push Settings under the Push Amp+ Tab

Refer to the Configuring Xiaomi Push documentation to learn more about the fields.

SDK Installation

MavenBadgeMavenBadge

Add the below dependency in the app/build.gradle file.

implementation("com.moengage:push-amp-plus:$sdkVersion")

replace $sdkVersion with the appropriate SDK version

Note: The push-amp-plus artifact should be compatible with the moe-android-sdk artifact you have already added. Make sure you check the version compatibility table below and pick the right version for your application

Add Permissions in Manifest File

Add the below permissions in your applications Manifest file

<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

  <uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />

  <uses-permission android:name="android.permission.VIBRATE" />

  <permission
      android:name="${applicationId}.permission.MIPUSH_RECEIVE"

      android:protectionLevel="signature" />

  <uses-permission android:name="${applicationId}.permission.MIPUSH_RECEIVE" />

Add Receivers and Services in the Manifest File

Add the below receiver and services in your application's manifest file.

<service
        android:name="com.xiaomi.push.service.XMPushService"
        android:enabled="true"
        android:process=":pushservice" />

    <service
        android:name="com.xiaomi.push.service.XMJobService"
        android:enabled="true"
        android:exported="false"
        android:permission="android.permission.BIND_JOB_SERVICE"
        android:process=":pushservice" />

    <service
        android:name="com.xiaomi.mipush.sdk.PushMessageHandler"
        android:enabled="true"
        android:exported="true" />

    <service
        android:name="com.xiaomi.mipush.sdk.MessageHandleService"
        android:enabled="true" />

    <receiver
        android:name="com.xiaomi.push.service.receivers.NetworkStatusReceiver"
        android:exported="true">
      <intent-filter>
        <action android:name="android.net.conn.CONNECTIVITY_CHANGE" />
        <category android:name="android.intent.category.DEFAULT" />
      </intent-filter>
    </receiver>

    <receiver
        android:name="com.xiaomi.push.service.receivers.PingReceiver"
        android:exported="false"
        android:process=":pushservice">
      <intent-filter>
        <action android:name="com.xiaomi.push.PING_TIMER" />
      </intent-filter>
    </receiver>

Add Meta Data

To use Push Amp Plus you need to provide the App Key, App Id from the Mi Console to the MoEngage SDK. If you are not sure where to find these keys refer to Configuring Xiaomi Push to know about it.
Use configureMiPush() of the MoEngage.Builder class to pass on the above information to the SDK.

val moEngage = MoEngage.Builder(this, "XXXXXXXX")
        .configureMiPush(MiPushConfig([appId], [appkey],[enableTokenRegistration]))
        .build()
    MoEngage.initialise(moEngage)
MoEngage moEngage =
        new MoEngage.Builder(this, "XXXXXXXXXX")
            .configureMiPush(new MiPushConfig([appId], [appkey],[enableTokenRegistration]))
            .build();
    MoEngage.initialise(moEngage);

enableTokenRegistration - This parameter tells the SDK whether SDK should register for push token or your application would be taking care of the same.

Configuring Receivers

Push Registration handled by the MoEngage SDK

If you want the MoEngage SDK to handle token registration and push notification, add the below receiver to your applications AndroidManifest.xml

<receiver
            android:name="com.moengage.mi.MoEMiPushReceiver"
            android:exported="true">
          <intent-filter>
            <action android:name="com.xiaomi.mipush.RECEIVE_MESSAGE" />
          </intent-filter>
          <intent-filter>
            <action android:name="com.xiaomi.mipush.MESSAGE_ARRIVED" />
          </intent-filter>
          <intent-filter>
            <action android:name="com.xiaomi.mipush.ERROR" />
          </intent-filter>
        </receiver>

Push Registration handled by the Application

If the application is handling token registration and notification via its own receiver the application would have to pass on the Push token and the MiPushMessage received on notification click to the MoEngage SDK.

Pass the Push token

Use the below API to pass the push token to the MoEngage SDK.

MoEMiPushHelper.getInstance().passPushToken(context, pushToken)
MoEMiPushHelper.Companion.getInstance().passPushToken(context, pushToken);

Pass Callback on Notification Click

Use the below API to pass the notification click callback to the MoEngage SDK.
You would need to override the onNotificationMessageClicked() of the PushMessageReceiver class and pass the callback to the SDK.

MoEMiPushHelper.getInstance().onNotificationClicked(context, message)
MoEMiPushHelper.Companion.getInstance().passPushPayload(context, message);

If you have multiple providers sending push notifications make sure you check if the notification is sent from the MoEngage platform or not using the below API.

MoEMiPushHelper.getInstance().isFromMoEngagePlatform(miPushMessage)
MoEMiPushHelper.Companion.getInstance().isFromMoEngagePlatform(miPushMessage);

So the final implementation of the onNotificationMessageClicked() will look like below

override fun onNotificationMessageClicked(context: Context?, message: MiPushMessage?) 
        if (message == null || context == null) {
            return
        }
        if (MoEMiPushHelper.getInstance().isFromMoEngagePlatform(message)) {
            MoEMiPushHelper.getInstance().onNotificationClicked(context, message)
        }
    }

Note: SDK takes care of re-directing the user to the selected screen or deep-link, do not add any logic for redirection.

Guidelines for token registration

If you are application is handling push token then please follow the guidelines

  • Register for Mi Push only if the device manufacturer is Xiaomi
  • Register for Mi Push only if the device has MIUI. You can use the helper API provided by MoEngage SDK to check whether the device has MIUI installed, use MoEMiPushHelper.getInstance().hasMiUi()
  • Add a retry mechanism in case of push registration failure.

Note: When using MoEngage SDK's registration all the above is taken care of. We recommend you to let MoEngage SDK register for the push token.

Callbacks

When the application is using MoEngage SDK's receiver the SDK optionally provides callbacks to the application in the following cases

  • Push Token is available
  • Non-MoEngage pass through message is received
  • Non-MoEngage Notification Clicked

To get the callback application needs to implement MiPushEventListener API Reference.
To register a listner use MoEMiPushHelper.getInstance().addEventListener() API. Since these callbacks can be triggered when the application is in background register the listener in the onCreate() of the Application class.

Version Compatibility

The push-amp-plus artifact/module is dependent on the Core SDK or moe-android-sdk artifact/module.
Based on the version of the Core SDK you are using choose the right version of the Push-Amp Plus module.

Core SDK Version

Push Amp Plus Version

11.2.00 and above

3.2.00 and above

11.1.00

3.1.00

11.0.03 - 11.0.05

3.0.01, 3.0.02

11.0.01 - 11.0.02

3.0.00

10.6.00

2.2.00

10.4.00 - 10.5.00

2.1.00 and above

10.3.00-10.3.02

2.0.00

10.2.01 - 10.2.02

1.2.00

10.1.01 - 10.2.00

1.1.01

10.0.00 - 10.0.03

1.0.00

9.8.02 - 9.8.04

0.5.00

9.7.03 - 9.8.01

0.4.00

9.7.01 - 9.7.02

0.3.00

9.6.00 - 9.7.00

0.2.00