如何使用别名与标签
最近更新:2022-04-29
展开全部

如何使用别名与标签

别名与标签

别名:可以近似地被认为,是用户帐号里的昵称。使用别名推送指给某特定用户推送消息。
标签:类似于博客里为文章打上 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);
          public static void setAlias(Context context, int sequence, String alias);

        
此代码块在浮窗中显示

iOS 接口:

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

        
此代码块在浮窗中显示

设置标签

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

Android 接口:

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

        
此代码块在浮窗中显示

iOS 接口:

+ (void)setTags:(NSSet<NSString *> *)tags completion:(JPUSHTagsOperationCompletion)completion seq:(NSInteger)seq;
          + (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 获取方法:AndroidiOS

Rest API 查询

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

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

        
此代码块在浮窗中显示

Response Data

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

        
此代码块在浮窗中显示

使用别名/标签进行推送

控制台推送

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

标签推送:目标人群选择“设备标签(Tag)”,选择标签规则并添加标签,按 Enter 键结束。

Rest API 推送

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

关键字 类型 含义 说明 备注
tag JSON Array 标签 OR 数组。多个标签之间是 OR 的关系,即取并集。
  • 用标签来进行大规模的设备属性、用户属性分群,此功能为 VIP 用户功能。
  • 一次推送最多 20 个。
  • 有效的 tag 组成:字母(区分大小写)、数字、下划线、汉字、特殊字符 @!#$&*+=.|¥。
  • 限制:每一个 tag 的长度限制为 40 字节。(判断长度需采用 UTF-8 编码)
  • tag_and JSON Array 标签 AND 数组。多个标签之间是 AND 关系,即取交集。
  • 此功能为 VIP 用户功能, 注意与 tag 区分。
  • 一次推送最多 20 个。
  • tag_not JSON Array 标签 NOT 数组。多个标签之间,先取多标签的并集,再对该结果取补集。
  • 此功能为 VIP 用户功能。
  • 一次推送最多 20 个。
  • alias JSON Array 别名 数组。多个别名之间是 OR 关系,即取并集。
  • 用别名来标识一个用户,一个设备只能绑定一个别名,但多个设备可以绑定同一个别名。
  • 一次推送最多 1000 个。
  • 有效的 alias 组成:字母(区分大小写)、数字、下划线、汉字、特殊字符 @!#$&*+=.|¥。
  • 限制:每一个 alias 的长度限制为 40 字节。(判断长度需采用 UTF-8 编码)
    • 推送给多个标签(只要在任何一个标签范围内都满足):在深圳、广州、或者北京
    { "audience" : {"tag" : [ "深圳", "广州", "北京"] } }
              {
        "audience" : {"tag" : [ "深圳", "广州", "北京"]
        }
    }
    
            
    此代码块在浮窗中显示
    • 推送给多个标签(需要同时在多个标签范围内):在深圳并且是“女”
    { "audience" : {"tag_and" : [ "深圳", "女"] } }
              {
        "audience" : {"tag_and" : [ "深圳", "女"]
        }
    }
    
            
    此代码块在浮窗中显示
    • 推送给多个别名:
    { "audience" : {"alias" : [ "4314", "892", "4531"] } }
              {
        "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 } }
              // 这是来自 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
        }
    }
    
            
    此代码块在浮窗中显示
    文档内容是否对您有帮助?

    Copyright 2011-2022, jiguang.cn, All Rights Reserved. 粤ICP备12056275号-13 深圳市和讯华谷信息技术有限公司

    在文档中心打开