Android SDK 进阶教程

别名与标签使用教程

为什么需要别名与标签

推送消息时，要指定推送的对象：全部，某一个人，或者某一群人。

全部很好办，针对某应用“群发”就好了。Portal 与 API 都支持向指定的 AppKey 群发消息。

要指定向某一个特定的人，或者某一群特定的人，则相对复杂。因为对于 JPush 来说，某一个人就是一个注册 ID，这个注册 ID 与开发者 App 没有任何关系，或者说对开发者 App 是没有意义的。

如果要对开发者 App 有意义的某个特定的用户推送消息，则需要：把 JPush 注册用户与开发者 App 用户绑定起来。

这个绑定有两个基本思路：

  • 把绑定关系保存到 JPush 服务器端
  • 把绑定关系保存到开发者应用服务器中
    前者，就是这里要说到的：别名与标签的功能。这个机制简单易用，适用于大多数开发者。

后者，则是 JPush 提供的另外一套 RegistrationID 机制。这套机制开发者需要有应用服务器来维护绑定关系，不适用于普通开发者。Android SDK 1.6.0 版本开始支持。

使用方式

别名与标签的机制，其工作方式是：

  • 客户端开发者 App 调用 setAlias 或者 setTags API 来设置关系
  • JPush SDK 把该关系设置保存到 JPush Server 上
  • 在服务器端推送消息时，指定向之前设置过的别名或者标签推送
    SDK 支持的 Alias 与 Tags 接口请参考相应的文档：别名与标签 API

使用过程中有几个点做特别说明：

  • 1.5.0 版本开始提供的旧版 tag、alias 设置接口已不再维护，建议开发者使用 3.0.7 版本开始提供的新的 tag、alias 接口，支持对别名标签进行增删改查。

    • 在 callback 返回结果中如果返回 6002 （超时）或 6014（服务繁忙）则建议重试，具体错误码定义请参考错误码定义。
  • Portal 上推送或者 API 调用向别名或者标签推送时，可能会报错：不存在推送目标用户。该报错表明，JPush Server 上还没有针对你所推送的别名或者标签的用户绑定关系，所以没有推送目标。这时请开发者检查确认，开发者 App 是否正确地调用了 alias 和 tags API，以及调用时是否网络不好，JPush SDK 暂时未能保存成功。

使用别名

用于给某特定用户推送消息。别名，可以近似地被认为，是用户帐号里的昵称。

使用标签

用于给某一群人推送消息。

标签类似于博客里为文章打上 tag ，即为某资源分类。

动态标签

JPush 提供的设置标签的 API 是在客户端的。开发者如何做到在自己的服务器端动态去设置分组呢？ 比如一个企业 OA 系统，经常需要去变更部门人员分组。以下是大概的思路：

  • 设计一种自定义消息格式（业务协议），App 解析后可以调用 JPush SDK setTags API 来重新设置标签（分组），从 3.0.7 版本开始支持对标签进行增删改查，更便于对标签进行更新操作。
    • 例：{"action":"resetTags", "newTags":["dep_level_1":"A公司", "dep_level_2":"技术部", "dep_level_3":"Android开发组", "address":"深圳", "lang":"zh"]}
  • 要动态设置分组时，推送这条自定义消息给指定的用户
    • 使用别名的机制，推送到指定的用户。
  • 客户端 App 调用 JPush SDK API 来设置新的标签

别名与标签设置异常处理

由于网络连接不稳定的原因，有一定的概率 JPush SDK 设置别名与标签会失败。App 开发者合理地处理设置失败，则偶尔失败对应用的正常使用 JPush 影响是有限的。

以下以 Android SDK 作为示例,更为详细的请参考 example。

基本思路：

  • 设置成功时，往 SharePreference 里写状态，以后不必再设置
  • 遇到 6002 超时，则稍延迟重试。
  1. // 这是来自 JPush Example 的设置别名的 Activity 里的代码，更详细的示例请参考 JPush Example。一般 App 的设置的调用入口，在任何方便的地方调用都可以。
  2. private void handleAction(int sequence,TagAliasBean tagAliasBean) {
  3.     if(tagAliasBean == null){
  4.         Log.w(TAG,"tagAliasBean was null");
  5.         return;
  6.     }
  7.     if(tagAliasBean.isAliasAction){
  8.         switch (tagAliasBean.action){
  9.             case ACTION_GET:
  10.                 JPushInterface.getAlias(getApplicationContext(),sequence);
  11.                 break;
  12.             case ACTION_DELETE:
  13.                 JPushInterface.deleteAlias(getApplicationContext(),sequence);
  14.                 break;
  15.             case ACTION_SET:
  16.                 JPushInterface.setAlias(getApplicationContext(),sequence,tagAliasBean.alias);
  17.                 break;
  18.             default:
  19.                 Log.w(TAG,"unsupport alias action type");
  20.                 return;
  21.         }
  22.     }else {
  23.     //tag operation
  24.     }
  25. }

自定义通知栏样式教程

关于自定义通知栏样式

JPush 通知推送到客户端时，默认使用手机的默认设置来显示通知栏，包括铃声、震动等效果。

如果开发者想要达到如下的效果，则需要使用“自定义通知栏样式”功能：

  • 通知栏样式使用与默认不一样的设置，比如想要控制：
    • 铃声、震动
    • 显示图标
    • 替换默认的通知栏样式。

推送消息指定通知栏样式编号

通知栏样式在服务器端向下推送时，只体现为一个编号（数字）。

推送通知的样式编号，应该是在客户端做了自定义通知栏样式设置的。

如果通知上的样式编号，在客户端检查不存在，则使用默认的通知栏样式。

不使用自定义通知栏样式时，此编号默认为 0。如需使用自定义的通知栏样式，编号应大于 0 小于 1000。先在客户端调 API 设置通知栏样式，推送设置 Builder ID 值即可在收到消息时得到对应的样式效果。

调 API 进行推送时，在 Notification - Android 属性下设置 builder_id 值

在 Portal 上发送通知时，首先选择推送平台为 Android，然后展开“可选设置”，开发者可指定当前要推送的通知的样式编号。如下图所示：

Android SDK 进阶教程 - 图1

客户端设置通知栏样式

自定义的通知栏样式，是在客户端进行设置的。请参考 通知栏样式定制 API 来看所支持的功能。

自定义通知栏样式设计

  • 有个 PushNotificationBuilder 概念，开发者使用 setPushNotificationBuilder 方法为某种类型的 PushNotificationBuilder 指定编号。
  • setPushNotificationBuilder 可以在 JPushInterface.init() 之后任何地方调用，可以是开发者应用的逻辑来触发调用，或者初始化时调用。
  • 只需要设置一次，JPush SDK 会记住这个设置。在下次收到推送通知时，就根据通知里指定的编号来找到 PushNotificationBuilder 来展现、执行。

API - setDefaultPushNotificationBuilder 设置默认

此 API 改变默认的编号为 0 的通知栏样式。

API - setPushNotificationBuilder 指定编号

此 API 为开发者指定的编号，设置一个自定义的 PushNotificationBuilder（通知样式构建器）。

Example - 基础的 PushNotificationBuilder

定制声音、震动、闪灯等 Notification 样式。

  1. BasicPushNotificationBuilder builder = new BasicPushNotificationBuilder(MainActivity.this);
  2. builder.statusBarDrawable = R.drawable.jpush_notification_icon;
  3. builder.notificationFlags = Notification.FLAG_AUTO_CANCEL
  4.         | Notification.FLAG_SHOW_LIGHTS;  //设置为自动消失和呼吸灯闪烁
  5. builder.notificationDefaults = Notification.DEFAULT_SOUND
  6.         | Notification.DEFAULT_VIBRATE
  7.         | Notification.DEFAULT_LIGHTS;  // 设置为铃声、震动、呼吸灯闪烁都要
  8. JPushInterface.setPushNotificationBuilder(1, builder);

定制带按钮的 Notification 样式（3.0.0 及以上版本 sdk 才支持该样式，且该样式在某些与 Android 原生系统有差异的机型上无法正常显示）。

  1. MultiActionsNotificationBuilder builder = new MultiActionsNotificationBuilder(PushSetActivity.this);
  2. //添加按钮，参数（按钮图片、按钮文字、扩展数据）
  3. builder.addJPushAction(R.drawable.jpush_ic_richpush_actionbar_back, "first", "my_extra1");
  4. builder.addJPushAction(R.drawable.jpush_ic_richpush_actionbar_back, "second", "my_extra2");
  5. builder.addJPushAction(R.drawable.jpush_ic_richpush_actionbar_back, "third", "my_extra3");
  6. JPushInterface.setPushNotificationBuilder(2, builder);

Example - 高级自定义的 PushNotificationBuilder

基于基础的 PushNotificationBuilder，可进一步地定制 Notification 的 Layout。

这里作为 example 的 customer_notitfication_layout 在我们的 example 项目的 /res/layout/ 下可以找到。你完全可以用自己的 layout。

  1.     CustomPushNotificationBuilder builder = new
  2.     CustomPushNotificationBuilder(MainActivity.this,
  3.                               R.layout.customer_notitfication_layout,
  4.                               R.id.icon,
  5.                               R.id.title,
  6.                               R.id.text,
  7.                               R.id.time); 
  8.                              // 指定定制的 Notification Layout
  9.     builder.statusBarDrawable = R.drawable.your_notification_icon;     
  10.     // 指定最顶层状态栏小图标
  11.     builder.layoutIconDrawable = R.drawable.your_2_notification_icon;  
  12.     // 指定下拉状态栏时显示的通知图标
  13.     JPushInterface.setPushNotificationBuilder(2, builder);

通知栏样式定义不符合要求？

以上提供的自定义通知栏样式的功能是有限的。比如：Android SDK 4.0 以后的 Notification 支持指定 Style ，而这种复杂的通知样式定义 JPush SDK 还未有支持。

或者你想要自定义的复杂的通知样式，但不愿意使用上述高级的自定义通知栏定制功能。

建议不要使用 JPush 提供的通知功能，而使用自定义消息功能。

即：推送自定义消息到客户端后，App 取到自定义消息全部内容，然后 App 自己来写代码做通知的展示。请参考文档：通知 vs. 自定义消息。

通知 vs 自定义消息

极光推送包含有通知与自定义消息两种类型的推送。本文描述他们的区别，以及建议的应用场景。

两者的区别 - 功能角度

通知

通知（Notification），指在手机的通知栏（状态栏）上会显示的一条通知信息。这是 Android / iOS 的基本功能。

通知主要用于提示用户。一条通知，简单的填写纯文本的通知内容即可。

应用加上通知功能，有利于提高应用的活跃度。

自定义消息

自定义消息不是通知，默认不会被 SDK 展示到通知栏上，极光推送仅负责透传给 SDK。其内容和展示形式完全由开发者自己定义。

自定义消息主要用于应用的内部业务逻辑和特殊展示需求。

两者的区别 - 开发者使用角度

通知

简单场景下的通知，用户可以不写一行代码，而完全由 SDK 来负责默认的效果展示，以及默认用户点击时打开应用的主界面。

JPush Android SDK 提供了 API 让开发者来定制通知栏的效果，请参考：自定义通知栏样式教程；也提供了接收推送消息 Receiver 让你来定制在收到通知时与用户点击通知时的不同行为。

自定义消息

SDK 不会把自定义消息展示到通知栏。所以调试时，需要到日志里才可以看到服务器端推送的自定义消息。

自定义消息一定要由开发者写接收推送消息 Receiver 来处理收到的消息。

注意：

当自定义消息内容 msg_content 为空时，SDK 不会对消息进行广播，使得 App 无法接收到推送的消息，因此建议在使用自定义消息推送时添加内容。

使用通知

请参考以下示例代码。

  1. public class MyReceiver extends BroadcastReceiver {
  2.     private static final String TAG = "MyReceiver";
  4.     private NotificationManager nm;
  6.     @Override
  7.     public void onReceive(Context context, Intent intent) {
  8.         if (null == nm) {
  9.             nm = (NotificationManager) context.getSystemService(Context.NOTIFICATION_SERVICE);
  10.         }
  12.         Bundle bundle = intent.getExtras();
  13.         Logger.d(TAG, "onReceive - " + intent.getAction() + ", extras: " + AndroidUtil.printBundle(bundle));
  15.         if (JPushInterface.ACTION_REGISTRATION_ID.equals(intent.getAction())) {
  16.             Logger.d(TAG, "JPush 用户注册成功");
  18.         } else if (JPushInterface.ACTION_MESSAGE_RECEIVED.equals(intent.getAction())) {
  19.             Logger.d(TAG, "接受到推送下来的自定义消息");
  21.         } else if (JPushInterface.ACTION_NOTIFICATION_RECEIVED.equals(intent.getAction())) {
  22.             Logger.d(TAG, "接受到推送下来的通知");
  24.             receivingNotification(context,bundle);
  26.         } else if (JPushInterface.ACTION_NOTIFICATION_OPENED.equals(intent.getAction())) {
  27.             Logger.d(TAG, "用户点击打开了通知");
  29.            openNotification(context,bundle);
  31.         } else {
  32.             Logger.d(TAG, "Unhandled intent - " + intent.getAction());
  33.         }
  34.     }
  36.    private void receivingNotification(Context context, Bundle bundle){
  37.         String title = bundle.getString(JPushInterface.EXTRA_NOTIFICATION_TITLE);
  38.         Logger.d(TAG, " title : " + title);
  39.         String message = bundle.getString(JPushInterface.EXTRA_ALERT);
  40.         Logger.d(TAG, "message : " + message);
  41.         String extras = bundle.getString(JPushInterface.EXTRA_EXTRA);
  42.         Logger.d(TAG, "extras : " + extras);
  43.     }
  45.    private void openNotification(Context context, Bundle bundle){
  46.         String extras = bundle.getString(JPushInterface.EXTRA_EXTRA);
  47.         String myValue = "";
  48.         try {
  49.             JSONObject extrasJson = new JSONObject(extras);
  50.             myValue = extrasJson.optString("myKey");
  51.         } catch (Exception e) {
  52.             Logger.w(TAG, "Unexpected: extras is not a valid json", e);
  53.             return;
  54.         }
  55.         if (TYPE_THIS.equals(myValue)) {
  56.             Intent mIntent = new Intent(context, ThisActivity.class);
  57.             mIntent.putExtras(bundle);
  58.             mIntent.setFlags(Intent.FLAG_ACTIVITY_NEW_TASK);
  59.             context.startActivity(mIntent);
  60.         } else if (TYPE_ANOTHER.equals(myValue)){
  61.             Intent mIntent = new Intent(context, AnotherActivity.class);
  62.             mIntent.putExtras(bundle);
  63.             mIntent.setFlags(Intent.FLAG_ACTIVITY_NEW_TASK);
  64.             context.startActivity(mIntent);
  65.         }
  66.     }
  67. }

使用自定义消息

使用自定义消息，在客户端 App 里一定要写代码，去接受 JPush SDK 的广播，从而取得推送下来的消息内容。具体请参考文档：接收推送消息 Receiver。

以下代码来自于推聊。

  1. public class TalkReceiver extends BroadcastReceiver {
  2.     private static final String TAG = "TalkReceiver";
  4.     private NotificationManager nm;
  6.     @Override
  7.     public void onReceive(Context context, Intent intent) {
  8.         if (null == nm) {
  9.             nm = (NotificationManager) context.getSystemService(Context.NOTIFICATION_SERVICE);
  10.         }
  12.         Bundle bundle = intent.getExtras();
  13.         Logger.d(TAG, "onReceive - " + intent.getAction() + ", extras: " + AndroidUtil.printBundle(bundle));
  15.         if (JPushInterface.ACTION_REGISTRATION_ID.equals(intent.getAction())) {
  16.             Logger.d(TAG, "JPush 用户注册成功");
  18.         } else if (JPushInterface.ACTION_MESSAGE_RECEIVED.equals(intent.getAction())) {
  19.             Logger.d(TAG, "接受到推送下来的自定义消息");
  21.             // Push Talk messages are push down by custom message format
  22.             processCustomMessage(context, bundle);
  24.         } else if (JPushInterface.ACTION_NOTIFICATION_RECEIVED.equals(intent.getAction())) {
  25.             Logger.d(TAG, "接受到推送下来的通知");
  27.             receivingNotification(context,bundle);
  29.         } else if (JPushInterface.ACTION_NOTIFICATION_OPENED.equals(intent.getAction())) {
  30.             Logger.d(TAG, "用户点击打开了通知");
  32.            openNotification(context,bundle);
  34.         } else {
  35.             Logger.d(TAG, "Unhandled intent - " + intent.getAction());
  36.         }
  37.     }
  39.     private void processCustomMessage(Context context, Bundle bundle) {
  40.         String title = bundle.getString(JPushInterface.EXTRA_TITLE);
  41.         String message = bundle.getString(JPushInterface.EXTRA_MESSAGE);
  42.         if (StringUtils.isEmpty(title)) {
  43.             Logger.w(TAG, "Unexpected: empty title (friend). Give up");
  44.             return;
  45.         }
  47.         boolean needIncreaseUnread = true;
  49.         if (title.equalsIgnoreCase(Config.myName)) {
  50.             Logger.d(TAG, "Message from myself. Give up");
  51.             needIncreaseUnread = false;
  52.             if (!Config.IS_TEST_MODE) {
  53.                 return;
  54.             }
  55.         }
  57.         String channel = null;
  58.         String extras = bundle.getString(JPushInterface.EXTRA_EXTRA);
  59.         try {
  60.             JSONObject extrasJson = new JSONObject(extras);
  61.             channel = extrasJson.optString(Constants.KEY_CHANNEL);
  62.         } catch (Exception e) {
  63.             Logger.w(TAG, "Unexpected: extras is not a valid json", e);
  64.         }
  66.         // Send message to UI (Webview) only when UI is up
  67.         if (!Config.isBackground) {
  68.             Intent msgIntent = new Intent(MainActivity.MESSAGE_RECEIVED_ACTION);
  69.             msgIntent.putExtra(Constants.KEY_MESSAGE, message);
  70.             msgIntent.putExtra(Constants.KEY_TITLE, title);
  71.             if (null != channel) {
  72.                 msgIntent.putExtra(Constants.KEY_CHANNEL, channel);
  73.             }
  75.             JSONObject all = new JSONObject();
  76.             try {
  77.                 all.put(Constants.KEY_TITLE, title);
  78.                 all.put(Constants.KEY_MESSAGE, message);
  79.                 all.put(Constants.KEY_EXTRAS, new JSONObject(extras));
  80.             } catch (JSONException e) {
  81.             }
  82.             msgIntent.putExtra("all", all.toString());
  84.             context.sendBroadcast(msgIntent);
  85.         }
  87.         String chatting = title;
  88.         if (!StringUtils.isEmpty(channel)) {
  89.             chatting = channel;
  90.         }
  92.         String currentChatting = MyPreferenceManager.getString(Constants.PREF_CURRENT_CHATTING, null);
  93.         if (chatting.equalsIgnoreCase(currentChatting)) {
  94.             Logger.d(TAG, "Is now chatting with - " + chatting + ". Dont show notificaiton.");
  95.             needIncreaseUnread = false;
  96.             if (!Config.IS_TEST_MODE) {
  97.                 return;
  98.             }
  99.         }
  101.         if (needIncreaseUnread) {
  102.             unreadMessage(title, channel);
  103.         }
  105.         NotificationHelper.showMessageNotification(context, nm, title, message, channel);
  106.     }
  108.     // When received message, increase unread number for Recent Chat
  109.     private void unreadMessage(final String friend, final String channel) {
  110.         new Thread() {
  111.             public void run() {
  112.                 String chattingFriend = null;
  113.                 if (StringUtils.isEmpty(channel)) {
  114.                     chattingFriend = friend;
  115.                 }
  117.                 Map<String, String> params = new HashMap<String, String>();
  118.                 params.put("udid", Config.udid);
  119.                 params.put("friend", chattingFriend);
  120.                 params.put("channel_name", channel);
  122.                 try {
  123.                     HttpHelper.post(Constants.PATH_UNREAD, params);
  124.                 } catch (Exception e) {
  125.                     Logger.e(TAG, "Call pushtalk api to report unread error", e);
  126.                 }
  127.             }
  128.         }.start();
  129.     }
  130. }