如何使用别名与标签

别名与标签

别名：可以近似地被认为，是用户帐号里的昵称。使用别名推送指给某特定用户推送消息。
标签：类似于博客里为文章打上 tag ，即为某资源分类。使用标签推送指给某一群人推送消息。

为什么使用别名与标签

推送消息时，要指定推送的对象：全部，某一个人，或者某一群人。
全部指针对某应用“广播所有人”，控制台与 API 都支持向指定的 AppKey 广播消息。
要指定向某一个特定的人，或者某一群特定的人，则相对复杂。因为对于 JPush 来说，某一个人就是一个注册 ID（Registration ID），这个注册 ID 与开发者 App 没有任何关系，或者说对开发者 App 是没有意义的。
如果要对开发者 App 有意义的某个特定的用户推送消息，则需要：把 JPush 注册用户与开发者 App 用户绑定起来。
这个绑定有两个基本思路：

• 把绑定关系保存到 JPush 服务器端
• 把绑定关系保存到开发者应用服务器中

前者，就是这里要说到的：别名与标签的功能。这个机制简单易用，适用于大多数开发者。
后者，则是 JPush 提供的另外一套 Registration ID 机制。这套机制开发者需要有应用服务器来维护绑定关系，不适用于普通开发者。Android SDK 1.6.0 版本开始支持。

使用方式

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

• 客户端开发者 App 调用 setAlias 或者 setTags API 来设置注册用户和 App 用户的关系。
• JPush SDK 把该关系设置保存到 JPush Server 上。
• 在服务器端推送消息时，指定向之前设置过的别名或者标签推送。

客户端设置

SDK 支持的 Alias 与 Tags 接口请参考相应的文档：别名与标签 API（Android）、标签与别名 API（iOS），部分接口如下：

设置别名

这个接口是覆盖逻辑，而不是增加逻辑，调用此接口会覆盖之前设置的别名。

Android 接口：

          public static void setAlias(Context context, int sequence, String alias);

        

iOS 接口：

          + (void)setAlias:(NSString *)alias
  completion:(JPUSHAliasOperationCompletion)completion
         seq:(NSInteger)seq;

        

设置标签

这个接口是覆盖逻辑，而不是增加逻辑，调用此接口会覆盖之前设置的全部标签。

Android 接口：

          public static void setTags(Context context, int sequence,Set<String> tags);

        

iOS 接口：

          + (void)setTags:(NSSet<NSString *> *)tags
 completion:(JPUSHTagsOperationCompletion)completion
        seq:(NSInteger)seq;

        

注意事项

• 1.5.0 版本开始提供的旧版 tag、alias 设置接口已不再维护，建议开发者使用 3.0.7 版本开始提供的新的 tag、alias 接口，支持对别名标签进行增删改查。
  • init 后直接 set 操作有极大可能导致失败，可能会在回调里拿到 6022，6002 等，测试的时候可以做个 7、8 秒的延时，正式业务里一般配合用户注册使用，延时基本上够用。
  • 在 callback 返回结果中如果返回 6002 （超时）或 6014（服务繁忙）则建议重试，具体错误码定义请参考 错误码定义。
• 极光于 2020/03/10 对「别名设置」的上限进行限制，最多允许绑定 10 个设备。如需更高上限，请 联系商务，详情请阅读 公告。
  • JPush Android v3.5.8 及以上、JPush iOS v3.3.2 及以上版本将返回错误码：6027。
  • JPush Android v3.5.8 以下、JPush iOS v3.3.2 以下版本将会返回错误码：6017。
• 控制台上推送或者 API 调用向别名或者标签推送时，可能会报错：显示“1011”错误码或提示“没有满足条件的推送目标”。该报错表明，JPush Server 上还没有针对你所推送的别名或者标签的用户绑定关系，所以没有推送目标。这时请开发者检查确认，开发者 App 是否正确地调用了 alias 和 tags API，以及调用时是否网络不好，JPush SDK 暂时未能保存成功。

查询绑定状态

控制台查询

查询别名：进入【极光推送】-【别名管理】页面，选择“别名/Registration ID”，选择对应的别名点击“详情”，查看当前 Registration ID 是否有绑定该别名。
查询标签：进入【极光推送】-【标签管理】页面，选择“标签/Registration ID”，选择对应的标签点击“详情”，查看当前 Registration ID 是否有绑定该标签。

Registration ID 获取方法：Android、iOS。

Rest API 查询

调用地址：https://device.jpush.cn
此接口可以获取当前设备的所有属性，包含 tags, alias 和手机号码 mobile，详情参考 查询设备的别名与标签。
Request Header

          GET /v3/devices/{registration_id}
  Authorization: Basic (base64 auth string)
  Accept: application/json

        

Response Data

          {
    "tags": [
        "1122"
    ],
    "alias": "112233",
    "mobile": "13333333333"
}

        

使用别名/标签进行推送

控制台推送

别名推送：目标人群选择“设备别名(Alias)”，添加别名后按 Enter 键结束。

标签推送：目标人群选择“设备标签（Tag）”，选择标签规则并添加标签，按 Enter 键结束。

Rest API 推送

API 推送 时推送目标 audience 字段填写标签/别名进行下发，详细的参数说明如下：

• 推送给多个标签（只要在任何一个标签范围内都满足）：在深圳、广州、或者北京

          {
    "audience" : {"tag" : [ "深圳", "广州", "北京"]
    }
}

        

• 推送给多个标签（需要同时在多个标签范围内）：在深圳并且是“女”

          {
    "audience" : {"tag_and" : [ "深圳", "女"]
    }
}

        

• 推送给多个别名：

          {
    "audience" : {"alias" : [ "4314", "892", "4531"]
    }
}

        

高级场景

动态标签

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 超时，则稍延迟重试。

          // 这是来自 JPush Example 的设置别名的 Activity 里的代码，更详细的示例请参考 JPush Example。一般 App 的设置的调用入口，在任何方便的地方调用都可以。
private void handleAction(int sequence,TagAliasBean tagAliasBean) {
    if(tagAliasBean == null){
        Log.w(TAG,"tagAliasBean was null");
        return;
    }
    if(tagAliasBean.isAliasAction){
        switch (tagAliasBean.action){
            case ACTION_GET:
                JPushInterface.getAlias(getApplicationContext(),sequence);
                break;
            case ACTION_DELETE:
                JPushInterface.deleteAlias(getApplicationContext(),sequence);
                break;
            case ACTION_SET:
                JPushInterface.setAlias(getApplicationContext(),sequence,tagAliasBean.alias);
                break;
            default:
                Log.w(TAG,"unsupport alias action type");
                return;
        }
    }else {
    //tag operation
    }
}