全部产品
云市场

使用 SDK

更新时间:2020-06-04 14:47:13

步骤概览

在 Android 客户端中使用 pushSDK,您需要进行如下操作:

  1. 初始化 pushSDK:建立客户端和移动推送网关的长链接,获取设备标识。
  2. 监听消息:为接收消息、获取 Android 设备标识(Ad-token)编写 service,实现设备维度的消息推送。
  3. 接入第三方推送渠道:可选,提升消息推送的到达率。
  4. 上报用户 ID:将用户标识上传到服务端,进行用户和设备绑定,实现用户维度的消息推送。

初始化 pushSDK

关于此任务

客户端通过调用 mPaaS 中间层的 MPPush 类来实现对 pushSDK 的初始化:

  1. MPPush.init(Context context)

初始化过程中, pushSDK 会用设定好的地址和端口尝试建立链接。如果客户端建链信息中未携带设备标识,移动推送网关在建链成功后将下发设备标识(Ad-token)。

在 pushSDK 成功获取到设备标识后,您可以通过 App 中配置好的 service 来获取这个设备标识。具体方法,参考 监听消息 中的示例。

监听消息

在接收到推送消息,或者获取到 Ad-token 后,pushSDK 都会启动一个 service 来对该消息或该 Ad-token 进行处理。为接收消息、获取 Android 设备标识(Ad-token)编写 service,实现设备维度的消息推送。

关于此任务

通过编写和配置继承自 AliPushRcvService 的 service,用来接收移动推送网关下发的设备标识和消息。

操作步骤

  1. 编写 service。客户端可以分别为接收消息、获取 Ad-token 各编写一个 service,也可以共用同一个 service。下面是共用同一个 service 的示例代码:

    1. public class RecvMsgIntentService extends AliPushRcvService {
    2. public RecvMsgIntentService() {
    3. super();
    4. }
    5. // 调用时机:
    6. // 华为、小米手机:接入推送后,点击通知栏时进行调用
    7. // 其他手机:收到消息时进行调用
    8. @Override
    9. protected void handleActionReceived(String s, String s1, boolean clicked) {
    10. //示例代码
    11. Intent intent1 = new Intent("tt-action");
    12. String extra = "key:=" + s + "data:=" + s1;
    13. intent1.putExtra("intent :", extra);
    14. LocalBroadcastManager.getInstance(this).sendBroadcast(intent1);
    15. Log.v("push-test", "onHandleIntent sendLocalBroadcast : " + intent1.toString());
    16. if (TextUtils.isEmpty(s1)) {
    17. return;
    18. }
    19. if(clicked){
    20. //华为小米采用通知栏消息,所以一定点击过
    21. }
    22. BDataBean bDataBean = BDataBean.create(s1);
    23. // BDataBean 含有自定义的Param
    24. if (bDataBean == null) {
    25. return;
    26. }
    27. // 处理默认的跳转等事件
    28. // 可以不调用以下方法,自行处理
    29. bDataBean.action(this);
    30. }
    31. public static String adToken = "";
    32. public static String thirdToken = "";
    33. public static int platform = 0;
    34. // 自建渠道 AdToken 返回
    35. /** 调用时机:完成初始化后,收到自建渠道标识时调用
    36. *@param s adtoken 自建渠道标识
    37. */
    38. @Override
    39. protected void handleActionId(String s) {
    40. // 示例代码
    41. String registrationId = s;
    42. PushAppInfo pushAppInfo = new PushAppInfo(getApplicationContext());
    43. pushAppInfo.setAppToken(registrationId);
    44. Log.e("push-test", "registrationId = " + registrationId);
    45. Intent intent1 = new Intent("tt-action");
    46. String extra = "adToken:=" + s;
    47. intent1.putExtra("intent :", extra);
    48. LocalBroadcastManager.getInstance(this).sendBroadcast(intent1);
    49. Log.e("push-test", "onHandleIntent sendLocalBroadcast : " + intent1.toString());
    50. adToken = s;
    51. }
    52. /**
    53. *调用时机:收到第三方渠道标识时调用
    54. *@param s thirdToken 第三方渠道标识
    55. *@param i platform 第三方渠道类型
    56. */
    57. @Override
    58. protected void handleActionThirdId(String s, int i) {
    59. // 示例代码
    60. Intent intent1 = new Intent("tt-action");
    61. String extra = "third token:=" + s + "channel" + i;
    62. intent1.putExtra("intent :", extra);
    63. LocalBroadcastManager.getInstance(this).sendBroadcast(intent1);
    64. Log.e("push-test", "onHandleIntent sendLocalBroadcast : " + intent1.toString());
    65. thirdToken = s;
    66. platform = i;
    67. }
    68. }
  2. AndroidManifest.xml 配置此 service。

    说明:基于 mPaaS 框架的工程,在 portal 或 bundle 的 AndroidManifest.xml 中都可以配置。

    通配符说明:你需要将代码中 ${} 替换为真实的值。

    • ${applicationId}:包名。示例:

      ${applicationId}.push.action.CHECK 替换为 com.mpaas.demo.push.action.CHECK

    • ${appId}${workspaceId}:应用 ID 与工作空间 ID。在 mPaaS 控制台 > 代码管理 > 代码配置 页面 下载配置文件.config 文件包含了两者的值。

      1. <uses-permission android:name="android.permission.INTERNET" />
      2. <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
      3. <uses-permission android:name="android.permission.ACCESS_WIFI_STATE"/>
      4. <uses-permission android:name="android.permission.BROADCAST_STICKY" />
      5. <uses-permission android:name="android.permission.READ_PHONE_STATE" />
      6. <uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
      7. <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
      8. <uses-permission android:name="android.permission.WRITE_SETTINGS" />
      9. <uses-permission android:name="android.permission.VIBRATE" />
      10. <uses-permission android:name="android.permission.WAKE_LOCK" />
      11. <!-- RecvMsgIntentService 是指前文代码中定义的 service -->
      12. <service android:name="com.mpaas.demo.push.RecvMsgIntentService"
      13. android:exported="false" >
      14. <intent-filter>
      15. //MESSAGE_RECEIVED 表示处理接收到的消息
      16. <action android:name="${applicationId}.push.action.MESSAGE_RECEIVED" />
      17. //REGISTRATION_ID 表示处理获取到的设备标识
      18. <action android:name="${applicationId}.push.action.REGISTRATION_ID" />
      19. <category android:name="${applicationId}" />
      20. </intent-filter>
      21. </service>
      22. <!-- 需要配置您的 alipush appId-->
      23. <meta-data
      24. android:name="ALIPUSH_APPID"
      25. android:value="${appId}-${workspaceId}" />
      26. <service
      27. android:name="com.alipay.pushsdk.push.NotificationService"
      28. android:enabled="true"
      29. android:exported="false"
      30. android:process=":push"
      31. android:label="NotificationService">
      32. <intent-filter>
      33. <action android:name="${applicationId}.push.action.START_PUSHSERVICE" />
      34. </intent-filter>
      35. </service>
      36. <service
      37. android:name="com.alipay.pushsdk.push.AppInfoRecvIntentService"
      38. android:exported="false"
      39. android:process=":push">
      40. </service>
      41. <receiver
      42. android:name="com.alipay.pushsdk.BroadcastActionReceiver"
      43. android:enabled="true"
      44. android:process=":push">
      45. <intent-filter android:priority="2147483647">
      46. <action android:name="android.intent.action.BOOT_COMPLETED" />
      47. <action android:name="android.net.conn.CONNECTIVITY_CHANGE" />
      48. <action android:name="android.intent.action.USER_PRESENT" />
      49. <action android:name="android.intent.action.ACTION_POWER_CONNECTED" />
      50. </intent-filter>
      51. </receiver>
      52. <receiver
      53. android:name="com.alipay.mobile.logmonitor.ClientMonitorWakeupReceiver"
      54. android:enabled="true"
      55. android:process=":push">
      56. <intent-filter>
      57. <action android:name="android.intent.action.BOOT_COMPLETED" />
      58. <action android:name="${applicationId}.push.action.CHECK" />
      59. <action android:name="${applicationId}.monitor.command" />
      60. </intent-filter>
      61. </receiver>
  3. 您可在控制台上创建极简推送类型的消息,测试基于设备维度的消息推送是否成功。
    创建消息的操作方法,参见 创建消息 > 操作方法

    说明
    • 收到消息后不会弹出通知栏。
    • 为了防止主进程被杀死后通知栏无法弹出,建议开发者在消息接收服务的 handleActionReceived(String s, String s1, boolean clicked) 方法中添加通知栏弹出代码。

后续步骤

  • 10.1.60 基线已支持内建通知消息,以满足普通消息推送场景,具体方法参考 内建消息通知
  • 为了提升消息推送的到达率,您可以选择是否接入 Android 客户端三方推送渠道,具体方法参考 第三方推送渠道
  • pushSDK 支持基于用户标识的推送,你可以选择将用户标识和设备标识进行绑定,具体方法参考 上报用户 ID

接入第三方推送渠道

为了提升推送的到达率,mPaaS 集成了华为、小米、OPPO 和 vivo 等厂商的推送功能。采用 小米通知栏消息华为通知消息OPPO 通知栏消息vivo 通知栏消息 实现推送,在进程挂起时,依然可以发送通知,用户点击通知栏可以激活进程。

说明:接入厂商自有的推送渠道后,能够帮助应用获得稳定的推送性能,因此建议您将第三方推送渠道接入您的应用。

本文档分为 客户端接入第三方推送渠道接入 MpaaSNcActivity、和 FAQ 三部分,引导开发者接入三方渠道的推送功能。在 客户端接入第三方推送渠道 中,分别介绍了接入华为、小米、OPPO 和 vivo 四家厂商的推送服务所需要进行的客户端配置。

客户端接入第三方推送渠道

接入华为渠道

注册华为推送

登录华为开发官网,注册账号并且开启推送服务。详情请参见 华为推送开启步骤

客户端接入华为推送
  1. 接入 MPS 依赖。第三方渠道的接入与 MPS 自建通道的接入完全相同,更多信息请参见 添加 SDK
  2. 配置 AndroidManifest.xml

    1. <activity
    2. android:name="com.huawei.hms.activity.BridgeActivity"
    3. android:configChanges="orientation|locale|screenSize|layoutDirection|fontScale"
    4. android:excludeFromRecents="true"
    5. android:exported="false"
    6. android:hardwareAccelerated="true"
    7. android:theme="@android:style/Theme.Translucent">
    8. <meta-data
    9. android:name="hwc-theme"
    10. android:value="androidhwext:style/Theme.Emui.Translucent" />
    11. </activity>
    12. <!--为了防止低版本 dex 崩溃,动态开启 provider,enabled 设置为 false-->
    13. <provider
    14. android:name="com.huawei.hms.update.provider.UpdateProvider"
    15. android:authorities="${applicationId}.hms.update.provider"
    16. android:exported="false"
    17. android:enabled="false"
    18. android:grantUriPermissions="true">
    19. </provider>
    20. <!-- value 的值“appid”用实际申请的应用 ID 替换,来源于开发者联盟网站应用的服务详情。-->
    21. <meta-data
    22. android:name="com.huawei.hms.client.appid"
    23. android:value="\ your huawei appId" />
    24. <receiver
    25. android:name="com.huawei.hms.support.api.push.PushEventReceiver"
    26. >
    27. <intent-filter>
    28. <!-- 接收通道发来的通知栏消息,兼容老版本PUSH -->
    29. <action android:name="com.huawei.intent.action.PUSH" />
    30. </intent-filter>
    31. </receiver>
    32. <receiver
    33. android:name="com.alipay.pushsdk.thirdparty.huawei.HuaweiPushReceiver">
    34. <intent-filter>
    35. <!-- 必须,用于接收 TOKEN -->
    36. <action android:name="com.huawei.android.push.intent.REGISTRATION" />
    37. <!-- 必须,用于接收消息 -->
    38. <action android:name="com.huawei.android.push.intent.RECEIVE" />
    39. <!-- 可选,用于点击通知栏或通知栏上的按钮后触发 onEvent 回调 -->
    40. <action android:name="com.huawei.android.push.intent.CLICK" />
    41. <!-- 可选,查看PUSH通道是否连接,不查看则不需要 -->
    42. <action android:name="com.huawei.intent.action.PUSH_STATE" />
    43. </intent-filter>
    44. </receiver>
  3. 接入 MpaaSNcActivity

接入小米渠道

注册小米推送

参考以下小米官方文档,完成小米推送注册:

客户端接入小米推送
  1. 接入 MPS 依赖。第三方渠道的接入与 MPS 自建通道的接入完全相同,更多信息请参见 添加 SDK
  2. 配置 AndroidManifest.xml

    1. <!--由于涉及到签名,权限放在 Portal 中-->
    2. <permission
    3. android:name="${applicationId}.permission.MIPUSH_RECEIVE"
    4. android:protectionLevel="signature"/>
    5. <uses-permission android:name="${applicationId}.permission.MIPUSH_RECEIVE"/>
    6. <!-- value 斜杠空格要保留 -->
    7. <meta-data
    8. android:name="xiaomi_appid"
    9. android:value="\ 2xxxxxxxxxx" />
    10. <!-- value 斜杠空格要保留 -->
    11. <meta-data
    12. android:name="xiaomi_appkey"
    13. android:value="\ 5xxxxxxxxxxxx" />
    14. <service android:name="com.xiaomi.push.service.XMJobService"
    15. android:enabled="true"
    16. android:exported="false"
    17. android:permission="android.permission.BIND_JOB_SERVICE"
    18. android:process=":push" />
    19. <service
    20. android:name="com.xiaomi.push.service.XMPushService"
    21. android:enabled="true"
    22. android:process=":push"/>
    23. <service
    24. android:name="com.xiaomi.mipush.sdk.PushMessageHandler"
    25. android:enabled="true"
    26. android:exported="true"
    27. android:process=":push"/>
    28. <service
    29. android:name="com.xiaomi.mipush.sdk.MessageHandleService"
    30. android:enabled="true"
    31. android:process=":push"/>
    32. <receiver
    33. android:name="com.xiaomi.push.service.receivers.NetworkStatusReceiver"
    34. android:exported="true"
    35. android:process=":push">
    36. <intent-filter>
    37. <action android:name="android.net.conn.CONNECTIVITY_CHANGE"/>
    38. <category android:name="android.intent.category.DEFAULT"/>
    39. </intent-filter>
    40. </receiver>
    41. <receiver
    42. android:name="com.xiaomi.push.service.receivers.PingReceiver"
    43. android:exported="false"
    44. android:process=":push">
    45. <intent-filter>
    46. <action android:name="com.xiaomi.push.PING_TIMER"/>
    47. </intent-filter>
    48. </receiver>
    49. <receiver
    50. android:name="com.alipay.pushsdk.thirdparty.xiaomi.XiaoMiMsgReceiver"
    51. android:exported="true"
    52. android:process=":push">
    53. <intent-filter>
    54. <action android:name="com.xiaomi.mipush.RECEIVE_MESSAGE"/>
    55. </intent-filter>
    56. <intent-filter>
    57. <action android:name="com.xiaomi.mipush.ERROR"/>
    58. </intent-filter>
    59. <intent-filter>
    60. <action android:name="com.xiaomi.mipush.MESSAGE_ARRIVED"/>
    61. </intent-filter>
    62. </receiver>
  3. 接入 MpaaSNcActivity

接入 OPPO 渠道

说明:仅 10.1.60 及以上基线版本支持接入 OPPO 推送渠道。如果您使用了较早版本基线的提供的 AliPushInterface 类进行初始化,请替换成使用 MPPush 类。
注册 OPPO 推送

参考 OPPO推送平台使用指南OPPO 开放平台 注册账号并申请接入推送服务。

客户端接入 OPPO 推送
  1. mPaaS 不提供 OPPO Push SDK 的库,请前往 OPPO SDK 文档 下载 SDK 并集成到主工程中。
    说明:当前适配的版本为 2.0.2。
  2. 配置 AndroidManifest.xml

    1. <uses-permission android:name="com.coloros.mcs.permission.RECIEVE_MCS_MESSAGE" />
    2. <uses-permission android:name="com.heytap.mcs.permission.RECIEVE_MCS_MESSAGE"/>
    3. <application>
    4. <service
    5. android:name="com.heytap.mcssdk.PushService"
    6. android:permission="com.coloros.mcs.permission.SEND_MCS_MESSAGE"
    7. android:process=":push">
    8. <intent-filter>
    9. <action android:name="com.coloros.mcs.action.RECEIVE_MCS_MESSAGE"/>
    10. </intent-filter>
    11. </service>
    12. <service
    13. android:name="com.heytap.mcssdk.AppPushService"
    14. android:permission="com.heytap.mcs.permission.SEND_MCS_MESSAGE"
    15. android:process=":push">
    16. <intent-filter>
    17. <action android:name="com.heytap.mcs.action.RECEIVE_MCS_MESSAGE"/>
    18. </intent-filter>
    19. </service>
    20. <meta-data
    21. android:name="com.oppo.push.app_key"
    22. android:value="OPPO开放平台获取"
    23. />
    24. <meta-data
    25. android:name="com.oppo.push.app_secret"
    26. android:value="OPPO开放平台获取"
    27. />
    28. <meta-data
    29. android:name="mpaas.notification.channel.default.name"
    30. android:value="默认"
    31. />
    32. <meta-data
    33. android:name="mpaas.notification.channel.default.description"
    34. android:value="默认消息通知"
    35. />
    36. </application>
  3. 接入 MpaaSNcActivity

接入 vivo 渠道

说明:仅 10.1.60 及以上基线版本支持接入 vivo 推送渠道。
注册 vivo 推送

参考 vivo 推送平台使用指南,在 vivo 开放平台 上注册账号,并申请接入推送服务。

客户端接入 vivo 推送
  1. mPaaS 不提供 vivo Push SDK的库,请前往 vivo SDK 文档 下载 SDK 并集成到主工程中。
  2. 配置 AndroidManifest.xml
    1. <application>
    2. <service
    3. android:name="com.vivo.push.sdk.service.CommandClientService"
    4. android:process=":push"
    5. android:exported="true" />
    6. <activity
    7. android:name="com.vivo.push.sdk.LinkProxyClientActivity"
    8. android:exported="false"
    9. android:process=":push"
    10. android:screenOrientation="portrait"
    11. android:theme="@android:style/Theme.Translucent.NoTitleBar" />
    12. <meta-data
    13. android:name="com.vivo.push.api_key"
    14. android:value="VIVO开放平台提供" />
    15. <meta-data
    16. android:name="com.vivo.push.app_id"
    17. android:value="VIVO开放平台提供" />
    18. <receiver
    19. android:name="com.alipay.pushsdk.thirdparty.vivo.PushMessageReceiver"
    20. android:process=":push" >
    21. <intent-filter>
    22. <!-- 接收push消息 -->
    23. <action android:name="com.vivo.pushclient.action.RECEIVE" />
    24. </intent-filter>
    25. </receiver>
    26. </application>
  3. 接入 MpaaSNcActivity

接入 MpaaSNcActivity

  1. <activity
  2. android:name="com.alipay.pushsdk.thirdparty.MPaaSNcActivity"
  3. android:exported="true"
  4. android:theme="@android:style/Theme.Translucent">
  5. <intent-filter>
  6. <action android:name="android.intent.action.VIEW" />
  7. <category android:name="android.intent.category.DEFAULT" />
  8. </intent-filter>
  9. </activity>

FAQ

  • 实现 PUSH 通知栏消息,对 EMUI 和华为移动服务是否有版本限制?
    答:有版本限制,详细版本要求请参见 设备接收华为推送消息的条件

  • 华为手机无法打印日志
    答:在手机拨号界面输入 *#*#2846579#*#* 进入工程菜单 > 后台设置 > LOG 设置 > 选中 AP 日志。重启手机后,logcat 开始生效。

  • 华为手机推送错误码
    答:如需了解错误码详情,请至华为官网查看 客户端错误码详解服务端错误码详解

  • OPPO 推送支持的系统版本和机型
    答:目前支持 ColorOS 3.1 及以上系统的 OPPO 机型,一加5/5T 及以上机型以及 realme 所有 机型。

  • OPPO 手机推送错误码
    答:当 OPPO 推送不生效时,您可在客户端日志中搜索 OPPO onRegister error =,获取错误码,并对照 OPPO 错误码 查询相应的错误原因。

  • vivo 推送支持的系统版本
    答:推送服务 SDK 支持的最低系统版本为 Android 6.0。

  • vivo 手机推送错误码
    答:当 vivo 推送不生效时,您可在客户端日志中搜索 fail to turn on vivo push state =,获取状态码,并对照 公共状态码 定位具体原因。

  • 常见问题排查步骤

    1. 检查 Manifest 文件是否配置正确。
    2. 检查 appId(华为、小米、vivo)、appSecret(小米、OPPO)、appKey(OPPO、vivo)、ALIPUSH_APPID(mPaaS)是否与对应开发平台的注册应用一致。
    3. 查看 tag 为 mpush 的 logcat 日志。

后续操作

在完成上述客户端接入第三方推送渠道的配置后,需要在消息推送控制台上配置对应三方渠道的相关参数。更多信息,参见 控制台渠道配置

上报用户 ID

如果需要用户维度的推送,当用户登录时,将该用户标识上传到服务端,由服务端向移动推送服务发出请求,将用户和设备进行绑定。当用户登出时,将该绑定关系解绑。

服务端的相关处理请参考 配置服务端

操作步骤

  1. 为了方便开发者进行用户绑定,提供接口进行绑定和解除绑定操作,示例代码如下:
    1. // 具体代码可以参考 Demo
    2. // 此处的用户 userId 不一定为开发者用户系统的真实标识,但是一定是可以与用户形成一一映射关系。
    3. // 参数 userId,adtoken(会在 service handleActionId 中接收到)
    4. ResultPbPB resultBean = MPPush.bind(getApplicationContext(), your userId, ad-token);
    5. ResultPbPB resultBean = MPPush.unbind(getApplicationContext(), your userId, ad-token);
    6. // 如果您已经通过调用 MPLogger.reportUserLogin() 或 MPLogger.setUserId() 设置了 userId,也可以直接使用以下方法(版本须为 10.1.60.9 及以上,或 10.1.68.3 及以上)
    7. ResultPbPB resultBean = MPPush.bind(getApplicationContext(), ad-token);
    8. ResultPbPB resultBean = MPPush.unbind(getApplicationContext(), ad-token);
  2. 选择绑定时机,可选的关键时机如下:

    • 用户登录(有登录态 app)和 push 收到 Ad-token 后,为了登录后首次接口收到 push。
    • App 冷启动,为了防止出现未注册情形。