本文档介绍非中国大陆版Mipush Android客户端SDK的集成方式，如需集成中国大陆版SDK，请参见《Android客户端SDK集成指南（AAR版）》。

一、前提条件

您已启用推送服务，并获得应用的AppId、AppKey和AppSecret。

二、接入准备

1、下载MiPush Android客户端SDK软件包

MiPush Android客户端SDK从5.0.6版本开始，提供AAR包接入方式，其支持的最低Android SDK版本为19。

下载地址：https://admin.xmpush.xiaomi.com/en/mipush/downpage

建议您下载最新版本。

2、如您之前通过JAR包方式接入过MiPush客户端SDK，需将原JAR包接入配置完全删除，具体配置请参见《Mi Push Service Android Client SDK User Guide》。

三、接入指导

1、添加依赖

首先将MiPush SDK的AAR包如MiPush_SDK_Client_xxx.aar 复制到项目/libs/目录，然后在项目APP module的build.gradle中依赖：

android{
    repositories {
        flatDir {
            dirs 'libs'
        }
    }
}
dependencies {
    implementation (name: 'MiPush_SDK_Client_xxx', ext: 'aar')
}

2、自定义一个BroadcastReceiver类接收推送消息

为了接收消息，您需要为APP自定义一个继承自PushMessageReceiver类的BroadcastReceiver，实现其中的onReceivePassThroughMessage，onNotificationMessageClicked，onNotificationMessageArrived，onCommandResult和onReceiveRegisterResult方法；其中，onReceivePassThroughMessage用来接收服务器发送的透传消息，onNotificationMessageClicked用来接收服务器发来的通知栏消息（用户点击通知栏时触发），onNotificationMessageArrived用来接收服务器发来的通知栏消息（消息到达客户端时触发，并且可以接收应用在前台时不弹出通知的通知消息），onCommandResult用来接收客户端向服务器发送命令消息后返回的响应，onReceiveRegisterResult用来接收客户端向服务器发送注册命令消息后返回的响应。

注意这些方法运行在非UI线程中。

举例：

自定义BroadcastReceiver：

public class DemoMessageReceiver extends PushMessageReceiver {
    private String mRegId;
    private long mResultCode = -1;
    private String mReason;
    private String mCommand;
    private String mMessage;
    private String mTopic;
    private String mAlias;
    private String mUserAccount;
    private String mStartTime;
    private String mEndTime;
    @Override
    public void onReceivePassThroughMessage(Context context, MiPushMessage message) {
        mMessage = message.getContent();
        if(!TextUtils.isEmpty(message.getTopic())) {
            mTopic=message.getTopic();
        } else if(!TextUtils.isEmpty(message.getAlias())) {
            mAlias=message.getAlias();
        } else if(!TextUtils.isEmpty(message.getUserAccount())) {
            mUserAccount=message.getUserAccount();
        }
    }
    @Override
    public void onNotificationMessageClicked(Context context, MiPushMessage message) {
        mMessage = message.getContent();
        if(!TextUtils.isEmpty(message.getTopic())) {
            mTopic=message.getTopic();
        } else if(!TextUtils.isEmpty(message.getAlias())) {
            mAlias=message.getAlias();
        } else if(!TextUtils.isEmpty(message.getUserAccount())) {
            mUserAccount=message.getUserAccount();
        }
    }
    @Override
    public void onNotificationMessageArrived(Context context, MiPushMessage message) {
        mMessage = message.getContent();
        if(!TextUtils.isEmpty(message.getTopic())) {
            mTopic=message.getTopic();
        } else if(!TextUtils.isEmpty(message.getAlias())) {
            mAlias=message.getAlias();
        } else if(!TextUtils.isEmpty(message.getUserAccount())) {
            mUserAccount=message.getUserAccount();
        }
    }
    @Override
    public void onCommandResult(Context context, MiPushCommandMessage message) {
        String command = message.getCommand();
        List<String> arguments = message.getCommandArguments();
        String cmdArg1 = ((arguments != null && arguments.size() > 0) ? arguments.get(0) : null);
        String cmdArg2 = ((arguments != null && arguments.size() > 1) ? arguments.get(1) : null);
        if (MiPushClient.COMMAND_REGISTER.equals(command)) {
            if (message.getResultCode() == ErrorCode.SUCCESS) {
                mRegId = cmdArg1;
            }
        } else if (MiPushClient.COMMAND_SET_ALIAS.equals(command)) {
            if (message.getResultCode() == ErrorCode.SUCCESS) {
                mAlias = cmdArg1;
            }
        } else if (MiPushClient.COMMAND_UNSET_ALIAS.equals(command)) {
            if (message.getResultCode() == ErrorCode.SUCCESS) {
                mAlias = cmdArg1;
            }
        } else if (MiPushClient.COMMAND_SUBSCRIBE_TOPIC.equals(command)) {
            if (message.getResultCode() == ErrorCode.SUCCESS) {
                mTopic = cmdArg1;
            }
        } else if (MiPushClient.COMMAND_UNSUBSCRIBE_TOPIC.equals(command)) {
            if (message.getResultCode() == ErrorCode.SUCCESS) {
                mTopic = cmdArg1;
            }
        } else if (MiPushClient.COMMAND_SET_ACCEPT_TIME.equals(command)) {
            if (message.getResultCode() == ErrorCode.SUCCESS) {
                mStartTime = cmdArg1;
                mEndTime = cmdArg2;
            }
        } 
    }
    @Override
    public void onReceiveRegisterResult(Context context, MiPushCommandMessage message) {
        String command = message.getCommand();
        List<String> arguments = message.getCommandArguments();
        String cmdArg1 = ((arguments != null && arguments.size() > 0) ? arguments.get(0) : null);
        String cmdArg2 = ((arguments != null && arguments.size() > 1) ? arguments.get(1) : null);
        if (MiPushClient.COMMAND_REGISTER.equals(command)) {
            if (message.getResultCode() == ErrorCode.SUCCESS) {
                mRegId = cmdArg1;
            }
        } 
    }
}

然后需要把该自定义BroadcastReceiver注册到AndroidManifest.xml文件中，注册内容如下：

<receiver
  android:exported="true"
  android:name="com.xiaomi.mipushdemo.DemoMessageReceiver">
          <!--这里com.xiaomi.mipushdemo.DemoMessageRreceiver改成app中定义的完整类名-->
  <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>

注意：请务必确保该自定义BroadcastReceiver所在进程与调用注册推送接口（MiPushClient.registerPush()）的进程为同一进程（强烈建议都在主进程中）。

如果您的应用使用了混淆，您需要使用下面的代码keep自定义的BroadcastReceiver：

#这里com.xiaomi.mipushdemo.DemoMessageRreceiver改成app中定义的完整类名
 -keep class com.xiaomi.mipush.sdk.DemoMessageReceiver {*;}

3、定制化配置（可选）

在AAR包标准配置中，XMPushService、XMJobService和PingReceiver组件默认运行在:pushservice进程，如果您希望其运行在其他进程下，如:appcustom，可通过tools命名空间的replace属性实现：

首先，在您项目的APP module的AndroidManifest.xml的根标签<manifest/>中声明tools命名空间：

xmlns:tools="http://schemas.android.com/tools"

然后，在您的项目APP module的AndroidManifest.xml文件的<application/>标签内，对XMPushService、XMJobService和PingReceiver组件进行修改进程配置的声明：

<service
    android:name="com.xiaomi.push.service.XMJobService"
    android:process=":appcustom"
    tools:replace="android:process"/>
<service
    android:name="com.xiaomi.push.service.XMPushService"
    android:process=":appcustom"
    tools:replace="android:process" /> 
<receiver
    android:name="com.xiaomi.push.service.receivers.PingReceiver"
    tools:replace="android:process"
    android:process=":appcustom" />

注意：请确保XMPushService、XMJobService和PingReceiver组件运行在同一进程。

4、注册推送服务

首先通过MiPushClient.setRegion接口设置数据存储区域，可选区域如下：

public enum Region {
    Global,//新加坡
    Europe,//欧洲德国法兰克福
    Russia,//俄罗斯莫斯科
    India//印度孟买
}

然后再调用MiPushClient.registerPush接口注册小米推送服务。

注意：请务必在调用MiPushClient.registerPush之前先调用MiPushClient.setRegion设置数据存储区域，否则会抛出IllegalArgumentException异常。

注册成功后，您可以在自定义的onCommandResult和onReceiveRegisterResult中收到注册结果，其中的regId即是当前设备上当前App的唯一标识。

为了提高push的注册率，您可以在Application的onCreate中初始化push。您也可以根据需要，在其他地方初始化push。 示例代码如下：

public class DemoApplication extends Application {

    public static final String APP_ID = "your appid";
    public static final String APP_KEY = "your appkey";
    public static final String TAG = "your packagename";

    @Override
    public void onCreate() {
        ...
        //初始化push推送服务
        if(isMainProcess()) {
            //务必在调用registerPush前先调用setRegion设置区域
            MiPushClient.setRegion(Region.Global);
            MiPushClient.registerPush(this, APP_ID, APP_KEY);
        }
        ...
    }

    private boolean isMainProcess() {
        ActivityManager am = ((ActivityManager) getSystemService(Context.ACTIVITY_SERVICE));
        List<RunningAppProcessInfo> processInfos = am.getRunningAppProcesses();
        String mainProcessName = getApplicationInfo().processName;
        int myPid = Process.myPid();
        for (RunningAppProcessInfo info : processInfos) {
            if (info.pid == myPid && mainProcessName.equals(info.processName)) {
                return true;
            }
        }
        return false;
    }
}

注意：因为推送服务XMPushService在AndroidManifest.xml中设置为运行在另外一个进程，这导致本Application会被实例化两次，所以我们需要让应用的主进程初始化。

5、设置alias、userAccount和订阅topic

在注册成功，收到regId之后，即可调用MiPushClient.setAlias来设置alias，调MiPushClient.setUserAccount来设置userAccount，调MiPushClient.subscribe订阅topic。 

alias可以理解为regId的别名，开发者可以将alias设置为自己应用账号系统的账号，或者设备标识等。然后在使用Server SDK发送消息的时候，即可直接指定发送给特定的alias，而不是regId，避免存储regId。 

开发者可以在不同设备上设置同一个userAccount。然后使用Server SDK给该userAccount发送消息；此时，所有设置了该userAccount的设备都可以收到消息。 

主题用来做广播消息。不同手机上的同一个app可以订阅同一个主题。通过发送主题消息的API，即可同时向所有订阅该主题的客户端发送消息。比如，您有一个新闻类的app，可以自定义“财经”、“体育”、“科技“等主题；对于经常阅读财经新闻的用户，您可以帮用户订阅“财经”类主题，当有新的财经要闻发生时，直接通过主题推送该新闻给所有订阅该主题的用户。

四、API说明

对开发者而言，使用客户端SDK可以完成两方面功能，一方面是客户端给服务器发送各种请求，另一方面是服务器给客户端发送的消息和对客户端请求的响应。它们分别对应MiPushClient的接入类和PushMesssageReceiver的实现类。

1、MiPushClient的接入类

MiPushClient是MiPush Client SDK在Android平台的接入类。该类提供了一系列静态方法（static），无需实例化。

1.1、MiPushClient

public abstract class
extends Object
java.lang.Object 
↳ com.xiaomi.mipush.sdk.MiPushClient

1.2、成员列表

下表列出了MiPushClient的成员，各API的详细说明请参见“4.4. API详细说明”。

表 4-1. MiPushClient成员列表

2、ErrorCode错误类型

ErrorCode是接入push失败后，返回的错误类型。

2.1、ErrorCode

public abstract class
extends Object
java.lang.Object 
↳ com.xiaomi.mipush.sdk.ErrorCode

2.2、静态变量

表4-2. ErrorCode静态变量

3、PushMesssageReceiver广播接收器

PushMessageReceiver是一个抽象的BroadcastReceiver类，里面定义了六个方法，分别为onReceivePassThroughMessage、onNotificationMessageClicked、onNotificationMessageArrived、onCommandResult、onReceiveRegisterResult和onRequirePermissions。 它的用途有两种：

1. 获取服务器推送的消息
2. 获取调用MiPushClient方法的返回结果

3.1、 PushMesssageReceiver

public abstract class
extends Object
java.lang.Object 
↳ com.xiaomi.mipush.sdk.PushMesssageReceiver

3.2、成员列表

下表列出了PushMesssageReceiver的成员，各API的详细说明请参见“4.4. API详细说明”。

表 4-3. PushMesssageReceiver成员列表

4、API详细说明

public static void registerPush(Context context, String appID, String appKey)

注册MiPush推送服务，建议在app启动的时候调用。

表 4-4-1. registerPush函数参数列表

public static void unregisterPush(Context context)

关闭MiPush推送服务，当用户希望不再使用MiPush推送服务的时候调用，调用成功之后，app将不会接收到任何MiPush服务推送的数据，直到下一次调用registerPush ()。 注: 调用unregisterPush()之后，服务器不会向app发送任何消息。

表 4-4-2. unregisterPush函数参数列表

public static void setAlias(Context context, String alias, String category)

开发者可以为指定用户设置别名，然后给这个别名推送消息，效果等同于给RegId推送消息。 

说明：每个App单台设备可设置的alias个数为15个，如果超过了对应上限数，则新设置的alias会覆盖最早设置的alias。

表 4-4-3. setAlias函数参数列表

public static void unsetAlias(Context context, String alias, String category)

开发者可以取消指定用户的某个别名，服务器就不会给这个别名推送消息了。

表 4-4-4. unsetAlias函数参数列表

public static void setUserAccount(final Context context, final String userAccount, String category)

开发者可以为指定用户设置userAccount。

表 4-4-5. setUserAccount函数参数列表

public static void unsetUserAccount(final Context context, final String userAccount, String category)

开发者可以取消指定用户的某个userAccount，服务器就不会给这个userAccount推送消息了。

表 4-4-6. unsetUserAccount函数参数列表

public static void subscribe(Context context, String topic, String category)

为某个用户设置订阅主题（Topic）；根据用户订阅的不同主题，开发者可以根据订阅的主题实现分组群发。

说明：每个App单台设备可设置的Topic个数为30个，如果超过了对应上限数，则新设置的Topic会覆盖最早设置的Topic。

表 4-4-7. subscribe函数参数列表

public static void unsubscribe(Context context, String topic, String category)

为某个用户取消某个订阅主题。

表 4-4-8. unsubscribe函数参数列表

public static void setAcceptTime(Context context, int startHour, int startMin, int endHour, int endMin, String category)

设置接收MiPush服务推送的时段，不在该时段的推送消息会被缓存起来，到了合适的时段再向app推送原先被缓存的消息。 这里采用24小时制，如果开始时间早于结束时间，则这个时段落在一天内；否则，这个时间将会跨越凌晨0点。 注: 这里使用与regId相关联的alias和topic推送消息，也会受到限制。 如果时间设置为0:00-0:00，就是暂停push推送服务，也可以直接调用pausePush()方法，其本质相同 如果时间设置为0:00-23:59，就是恢复push推送服务，即全天接收push推送消息，也可以直接调用resumePush()方法，其本质相同

表 4-4-9. setAcceptTime函数参数列表

public static void pausePush(Context context, String category)

暂停接收MiPush服务推送的消息，app在恢复MiPush推送服务之前，不接收任何推送消息 注: 这里使用与RegId相关联的alias和topic推送消息，也是被暂停的

表 4-4-10. pausePush函数参数列表

public static void resumePush(Context context, String category)

恢复接收MiPush服务推送的消息 注: 这里使用与RegId相关联的alias和topic推送消息，也是被恢复的；这时服务器会把暂停时期的推送消息重新推送过来

表 4-4-11. resumePush函数参数列表

public static List<String> getAllAlias(final Context context)

获取客户端所有设置的别名。

表 4-4-12. getAllAlias函数参数列表

public static List<String> getAllTopic(final Context context)

获取客户端所有订阅的主题。

表 4-4-13. getAllTopic函数参数列表

public static List<String> getAllUserAccount(final Context context)

获取客户端所有设置的账号。

表 4-4-14. getAllUserAccount函数参数列表

public static void reportMessageClicked(Context context, String msgid)

上报点击的消息。

表 4-4-15. reportMessageClicked函数参数列表

public static void clearNotification(Context context, int notifyId)

清除小米推送弹出的某一个notifyId通知。

表 4-4-16. clearNotification函数参数列表

public static void clearNotification(Context context)

清除小米推送弹出的所有通知。

表 4-4-17. clearNotification函数参数列表

public static void setLocalNotificationType(final Context context, int notifyType)

客户端设置通知消息的提醒类型。 注：当服务端指定了消息的提醒类型，会优选考虑客户端设置的。

表 4-4-18. setLocalNotificationType函数参数列表

public static void clearLocalNotificationType(final Context context)

清除客户端设置的通知消息提醒类型。

表 4-4-19. clearLocalNotificationType函数参数列表

public static String getRegId(Context context)

获取客户端的RegId。

表 4-4-20. getRegId函数参数列表

public void onReceivePassThroughMessage(Context context, MiPushMessage message)

接收服务器推送的透传消息。

表 4-4-21. onReceivePassThroughMessage函数参数列表

public void onNotificationMessageClicked(Context context, MiPushMessage message)

接收服务器推送的通知消息，用户点击后触发。

参数说明与onReceivePassThroughMessage中相同，具体请参见表 4-4-21。

public void onNotificationMessageArrived(Context context, MiPushMessage message)

接收服务器推送的通知消息，消息到达客户端时触发，还可以接收应用在前台时不弹出通知的通知消息。

参数说明与onReceivePassThroughMessage中相同，具体请参见表 4-4-21。

public void onCommandResult(Context context, MiPushCommandMessage message)

当客户端向服务器发送注册push、设置alias、取消注册alias、订阅topic、取消订阅topic等等命令后，从服务器返回结果。

表 4-4-22. onCommandResult函数参数列表

public void onReceiveRegisterResult(Context context, MiPushCommandMessage message)

 获取给服务器发送注册命令的结果。

参数说明与onCommandResult中相同，具体请参见表 4-4-22。

public void onRequirePermissions(Context context, String[] permissions)

当所需要的权限未获取到的时候会回调该接口。

表 4-4-23. onRequirePermissionspermissions函数参数列表

public static void enablePush(final Context context) 

启用MiPush推送服务。调用disablePush和enablePush接口后，不会生成新的regId，regId会和原来的保持一致。

表 4-4-24. enablePush函数参数列表

public static void disablePush(final Context context) 

禁用MiPush推送服务。调用disablePush和enablePush接口后，不会生成新的regId，regId会和原来的保持一致。

表 4-4-25. disablePush函数参数列表

五、专题

1、定制通知栏通知的图标

目前通知类的消息， 通知的图标展示规则如下：

• 如果app中同时存在名为mipush_notification和mipush_small_notification的drawable文件，则使用mipush_notification的drawable作为通知的大图标，mipush_small_notification的drawable作为通知的小图标。
• 如果app中只存在其中一个drawable文件，则使用该drawable作为通知的图标。
• 如果app中不存在这两个drawable文件，则使用app的icon作为通知的图标。在MIUI中，通知栏图标统一显示为app的icon，不可以定制。

2、消息的处理

消息类型：分为透传消息和通知消息。 服务端发送消息，请参见《服务端Java SDK文档》。

2.1、透传消息的处理

透传消息到达客户端后，封装消息的MiPushMessage对象直接通过PushMessageReceiver继承类的的onReceivePassThroughMessage方法传到客户端。 客户端收到透传消息后，可以自定义一些操作。

2.2、通知消息的处理

通知消息分为自定义通知消息和预定义通知消息。 如果服务端调用Message.Builder类的extra(String key, String value)方法设置了Constants.EXTRA_PARAM_NOTIFY_EFFECT的值，则为预定义通知消息（具体细节请参见《服务端Java SDK文档》）；否则为自定义通知消息。 如果在小米推送服务开发者站推送消息，需要通过指定“点击后续动作”来指定通知消息类型。 通知消息到达客户端后会在通知栏弹出notification，这时候消息已经传到PushMessageReceiver继承类的onNotificationMessageArrived方法，但这时候消息还没有通过PushMessageReceiver继承类的的onNotificationMessageClicked方法传到客户端。当用户点击了自定义通知消息，消息会通过onNotificationMessageClicked方法传到客户端。 

注意：用户点击了预定义通知消息，消息不会通过onNotificationMessageClicked方法传到客户端。 

客户端定义不同的通知栏消息点击行为，分为以下四种。

1. 自定义通知消息的处理

服务端没有设置Constants.EXTRA_PARAM_NOTIFY_EFFECT的值表示是自定义通知消息。客户端收到自定义通知消息后，可以自定义一些操作。 比如：通过启动一个Activity将消息传过去，这时需要给Intent添加FLAG_ACTIVITY_NEW_TASK。

intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK);

 透传消息和自定义通知消息的处理参考代码如下：

public void onReceivePassThroughMessage(Context context, MiPushMessage message)
{ 
  mMessage = message.getContent(); 
  if(!TextUtils.isEmpty(message.getTopic())) { 
    mTopic=message.getTopic(); 
 } 
else if(!TextUtils.isEmpty(message.getAlias())) {
  mAlias=message.getAlias(); 
 } 
}

public void onNotificationMessageClicked(Context context, MiPushMessage message) 
{ 
  mMessage = message.getContent(); 
  if(!TextUtils.isEmpty(message.getTopic())) {
   mTopic=message.getTopic(); 
  } 
  else if(!TextUtils.isEmpty(message.getAlias())) { 
    mAlias=message.getAlias(); 
  }
}

public void onNotificationMessageArrived(Context context, MiPushMessage message) 
{ 
  mMessage = message.getContent(); 
  if(!TextUtils.isEmpty(message.getTopic())) {
    mTopic=message.getTopic(); 
  }
  else if(!TextUtils.isEmpty(message.getAlias())) {
    mAlias=message.getAlias(); 
  } 
}

2. 打开当前app对应的Launcher Activity

服务端调用Message.Builder类的extra(String key, String value)方法，将key设置为Constants.EXTRA_PARAM_NOTIFY_EFFECT，value设置为Constants.NOTIFY_LAUNCHER_ACTIVITY。具体请参见《服务端Java SDK文档》。封装消息的MiPushMessage对象通过Intent传到客户端，客户端在相应的Activity中可以调用Intent的getSerializableExtra（PushMessageHelper.KEY_MESSAGE）方法得到MiPushMessage对象。

3. 打开当前app内的任意一个Activity

服务端调用Message.Builder类的extra(String key, String value)方法，将key设置为Constants.EXTRA_PARAM_NOTIFY_EFFECT，value设置为Constants.NOTIFY_ACTIVITY。具体请参见《服务端Java SDK文档》。封装消息的MiPushMessage对象通过Intent传到客户端，客户端在相应的Activity中可以调用Intent的getSerializableExtra（PushMessageHelper.KEY_MESSAGE）方法得到MiPushMessage对象。

4. 打开网页

服务端调用Message.Builder类的extra(String key, String value)方法，将key设置为Constants.EXTRA_PARAM_NOTIFY_EFFECT，value设置为Constants.NOTIFY_WEB。具体请参见《服务端Java SDK文档》。