快速开始

本文介绍如何快速将消息推送组件接入到 Android 客户端。消息推送支持原生 AAR 和组件化(Portal & Bundle)两种接入方式。

前提条件

操作步骤

要使用消息推送服务,您需要完成以下接入步骤:

  1. 添加推送 SDK。添加推送 SDK 依赖和 AndroidManifest 配置。

    1. 添加 SDK 依赖。根据不同的接入方式进行相应的操作:

    2. 添加 AndroidManifest 配置AndroidManifest.xml 中添加以下内容:

      说明

      如果是采用组件化方式接入,需要在 Portal 工程中添加 AndroidManifest 配置。

      <uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED" />
      
      <service
          android:name="com.alipay.pushsdk.push.NotificationService"
          android:enabled="true"
          android:exported="false"
          android:label="NotificationService"
          android:process=":push">
          <intent-filter>
              <action android:name="${applicationId}.push.action.START_PUSHSERVICE" />
          </intent-filter>
      </service>
      <receiver
          android:name="com.alipay.pushsdk.BroadcastActionReceiver"
          android:enabled="true"
          android:exported="true"
          android:process=":push">
          <intent-filter android:priority="2147483647">
              <action android:name="android.intent.action.BOOT_COMPLETED" />
              <action android:name="android.net.conn.CONNECTIVITY_CHANGE" />
              <action android:name="android.intent.action.USER_PRESENT" />
              <action android:name="android.intent.action.ACTION_POWER_CONNECTED" />
          </intent-filter>
      </receiver>
    3. 推送 SDK 为了提高消息的到达率,内置了进程保活功能,包括上述 com.alipay.pushsdk.BroadcastActionReceiver 监听系统广播唤起推送进程,以及进程回收后的自动重启,接入时可以根据自身需求决定是否启用这些功能:

      1. 如不需要监听系统启动广播,可删除:

        <uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED" />
        <action android:name="android.intent.action.BOOT_COMPLETED" />
      2. 如不需要监听网络切换广播,可删除:

        <action android:name="android.net.conn.CONNECTIVITY_CHANGE" />
      3. 如不需要监听用户唤醒广播,可删除:

        <action android:name="android.intent.action.USER_PRESENT" />
      4. 如不需要监听充电状态变化广播,可删除:

        <action android:name="android.intent.action.ACTION_POWER_CONNECTED" />
      5. 如不需要监听上述所有广播,可将 com.alipay.pushsdk.BroadcastActionReceiverandroid:enabled 属性设置为 false 。

      6. 如不需要推送进程回收后自动重启,可在 application 节点下添加以下配置:

        <meta-data
        		android:name="force.kill.push"
        		android:value="on" />
        说明

        该配置仅在基线版本 10.2.3.21 及以上版本中有效。

  2. 初始化。初始化推送服务,建立客户端和移动推送网关之间的长连接,这个长连接由推送 SDK 维护,即自建通道。

    根据不同的接入方式进行相应的操作:

    • 原生 AAR 方式

      • 如已在 Application 中调用初始化 mPaaS,则在 MP.init() 方法之后调用:

         MPPush.init(this);
      • 如未调用 mPaaS 初始化方法,则在 Application 中调用:

          MPPush.setup(this);
          MPPush.init(this);
    • 组件化方式

      LauncherApplicationAgentLauncherActivityAgentpostInit 方法中调用:

      MPPush.init(context);
  3. 创建 Service。创建 Service 继承 MPPushMsgServiceAdapter,重写 onTokenReceive 方法,接收自建通道下发的设备标识(token)。

    public class MyPushMsgService extends MPPushMsgServiceAdapter {
    
        /**
         * 收到自建通道 token 的回调
         *
         * @param token 自建通道 token
         */
        @Override
        protected void onTokenReceive(String token) {
            Log.d("收到自建通道 token: " + token);
        }
    
    }

    AndroidManifest.xml 中声明该 Service:

    <service
        android:name="com.mpaas.demo.push.MyPushMsgService"
        android:exported="false">
        <intent-filter>
            <action android:name="${applicationId}.push.action.MESSAGE_RECEIVED" />
            <action android:name="${applicationId}.push.action.REGISTRATION_ID" />
            <category android:name="${applicationId}" />
        </intent-filter>
    </service>

    完成此步骤后,就可以在控制台通过设备维度推送消息了,需要填写的设备标识就是收到的 token。

  4. 绑定用户 ID。此用户 ID 由开发者自定义,既可以是真实用户系统的用户标识,也可以是能和每个用户形成映射关系的其他参数,例如账号、手机号等。

    在收到 token 后,可以将 token 和用户 ID 绑定:

    String userId = "自定义 userId";
    ResultPbPB bindResult = MPPush.bind(context, userId, token);
    Log.d("绑定 userId " + (bindResult.success ? "成功" : ("错误:" + bindResult.code)));

    如已调用 MPLogger 设置过用户 ID,可以在绑定时不传入用户 ID,例如:

    MPLogger.setUserId("自定义 userId");
    ResultPbPB bindResult = MPPush.bind(context, token);

    如需解绑用户 ID,例如用户退出登录,可调用:

    ResultPbPB unbindResult = MPPush.unbind(context, userId, token);
    ResultPbPB unbindResult = MPPush.unbind(context, token);

    完成此步骤后,即可在控制台通过用户维度推送消息,需要填写的用户标识就是自定义的用户 ID。

  5. (可选)绑定用户手机号。

    重要

    目前,仅杭州非金融区提供短信补充服务。

    在收到 token 后,还可以将 token 和用户的手机号码绑定,同时将 token 与用户 ID 和手机号绑定。绑定手机号码后,用户就可以通过该手机号码收到相关推送短信。

    String userId = "自定义 userId";
    String phoneNumber = "138xxxxxxxx"
    ResultPbPB bindResult = MPPush.bind(context, userId, token,phoneNumber);
    Log.d("绑定 userId " + (bindResult.success ? "成功" : ("错误:" + bindResult.code)));

相关操作

  • 为提升消息推送的到达率,推荐接入 Android 手机厂商提供的推送通道,目前支持华为、小米、OPPO、vivo,具体操作参见 接入厂商通道

  • 收到消息后会自动发送通知,用户点击通知可自动打开网页,如需根据自定义的 DeepLink 跳转应用内页面,或自定义收到消息后的行为,请参见 通知点击处理

更多其他功能,参见 高级功能 说明文档。

代码示例

点击此处 下载示例代码包。

后续操作

接入完成后,可以通过服务端调用 RESTful 接口,推送消息。具体内容请参考 配置服务端