iOS开发-进阶:JPush设置标签与别名的API

标签与别名 API (iOS)

功能说明

温馨提示,设置标签别名请注意处理call back结果。

只有call back 返回值为 0 才设置成功,才可以向目标推送。否则服务器 API 会返回1011错误。所有回调函数都在主线程运行。


提供几个相关 API 用来设置别名(alias)与标签(tags)。

这几个 API 可以在 App 里任何地方调用。

别名 alias

为安装了应用程序的用户,取个别名来标识。以后给该用户 Push 消息时,就可以用此别名来指定。

每个用户只能指定一个别名。

同一个应用程序内,对不同的用户,建议取不同的别名。这样,尽可能根据别名来唯一确定用户。

系统不限定一个别名只能指定一个用户。如果一个别名被指定到了多个用户,当给指定这个别名发消息时,服务器端API会同时给这多个用户发送消息。

举例:在一个用户要登录的游戏中,可能设置别名为 userid。游戏运营时,发现该用户 3 天没有玩游戏了,则根据 userid 调用服务器端API发通知到客户端提醒用户。

标签 tag

为安装了应用程序的用户,打上标签。其目的主要是方便开发者根据标签,来批量下发 Push 消息。

可为每个用户打多个标签。

举例: game, old_page, women

Method - setTagsWithAlias (with Callback)

调用此 API 来同时设置别名与标签,支持回调函数。

需要理解的是,这个接口是覆盖逻辑,而不是增量逻辑。即新的调用会覆盖之前的设置。

在之前调用过后,如果需要再次改变别名与标签,只需要重新调用此 API 即可。

支持的版本

开始支持的版本:1.4.0

接口定义
+ (void)setTags:(NSSet *)tags alias:(NSString *)alias callbackSelector:(SEL)cbSelector object:(id)theTarget;
参数说明
  • alias

    • nil 此次调用不设置此值。
    • 空字符串 (@"")表示取消之前的设置。
    • 每次调用设置有效的别名,覆盖之前的设置。
    • 有效的别名组成:字母(区分大小写)、数字、下划线、汉字。
    • 限制:alias 命名长度限制为 40 字节。(判断长度需采用UTF-8编码)
  • tags

    • nil 此次调用不设置此值。
    • 空集合([NSSet set])表示取消之前的设置。
    • 集合成员类型要求为NSString类型
    • 每次调用至少设置一个 tag,覆盖之前的设置,不是新增。
    • 有效的标签组成:字母(区分大小写)、数字、下划线、汉字。
    • 限制:每个 tag 命名长度限制为 40 字节,最多支持设置 100 个 tag,但总长度不得超过1K字节。(判断长度需采用UTF-8编码)
    • 单个设备最多支持设置 100 个 tag。App 全局 tag 数量无限制。
  • callbackSelector 

    • nil 此次调用不需要 Callback。
    • 用于回调返回对应的参数 alias, tags。并返回对应的状态码:0为成功,其他返回码请参考错误码定义。
    • 回调函数请参考SDK 实现。
  • theTarget

    • 参数值为实现了callbackSelector的实例对象。
    • nil 此次调用不需要 Callback。
-(void)tagsAliasCallback:(int)iResCode
                    tags:(NSSet*)tags
                   alias:(NSString*)alias
{
    NSLog(@"rescode: %d, \ntags: %@, \nalias: %@\n", iResCode, tags , alias);
}

Method - setTagsWithAlias (background)

调用此 API 在后台同时设置别名与标签,不需要处理设置结果,SDK会自动进行失败重试

需要理解的是,这个接口是覆盖逻辑,而不是增量逻辑。即新的调用会覆盖之前的设置。

在之前调用过后,如果需要再次改变别名与标签,只需要重新调用此 API 即可。

需要注意,该background模式的设置和非background的设置是两种不同的设置,互相不影响,意味着,非background的设置不会终止当前进行的background设置,除非另一个background设置发生。

支持的版本

开始支持的版本:2.1.0

接口定义
+ (void)setTags:(NSSet *)tags aliasInbackground:(NSString *)alias;
参数说明
  • alias

    • nil 此次调用不设置此值。
    • 空字符串 (@"")表示取消之前的设置。
    • 每次调用设置有效的别名,覆盖之前的设置。
    • 有效的别名组成:字母(区分大小写)、数字、下划线、汉字。
    • 限制:alias 命名长度限制为 40 字节。(判断长度需采用UTF-8编码)
  • tags

    • nil 此次调用不设置此值。
    • 空集合([NSSet set])表示取消之前的设置。
    • 集合成员类型要求为NSString类型
    • 每次调用至少设置一个 tag,覆盖之前的设置,不是新增。
    • 有效的标签组成:字母(区分大小写)、数字、下划线、汉字。
    • 限制:每个 tag 命名长度限制为 40 字节,最多支持设置 100 个 tag,但总长度不得超过1K字节。(判断长度需采用UTF-8编码)
    • 单个设备最多支持设置 100 个 tag。App 全局 tag 数量无限制。

[JPUSHService setTags:tags aliasInbackground:alias];

Method - setTagsWithAlias (with block)

调用此 API 来同时设置别名与标签,通过block来返回设置别名与标签的结果。

需要理解的是,这个接口是覆盖逻辑,而不是增量逻辑。即新的调用会覆盖之前的设置。

在之前调用过后,如果需要再次改变别名与标签,只需要重新调用此 API 即可。

支持的版本

开始支持的版本:2.1.0

接口定义
+ (void)setTags:(NSSet *)tags alias:(NSString *)alias fetchCompletionHandle:(void (^)(int iResCode, NSSet *iTags, NSString *iAlias))completionHandler
参数说明
  • alias

    • nil 此次调用不设置此值。
    • 空字符串 (@"")表示取消之前的设置。
    • 每次调用设置有效的别名,覆盖之前的设置。
    • 有效的别名组成:字母(区分大小写)、数字、下划线、汉字。
    • 限制:alias 命名长度限制为 40 字节。(判断长度需采用UTF-8编码)
  • tags

    • nil 此次调用不设置此值。
    • 空集合([NSSet set])表示取消之前的设置。
    • 集合成员类型要求为NSString类型
    • 每次调用至少设置一个 tag,覆盖之前的设置,不是新增。
    • 有效的标签组成:字母(区分大小写)、数字、下划线、汉字。
    • 限制:每个 tag 命名长度限制为 40 字节,最多支持设置 100 个 tag,但总长度不得超过1K字节。(判断长度需采用UTF-8编码)
    • 单个设备最多支持设置 100 个 tag。App 全局 tag 数量无限制。
  • (void (^)(int iResCode, NSSet iTags, NSString iAlias))completionHandler

    • completionHandler用于处理设置返回结果
    • iResCode返回的结果状态码
    • iTags和iAlias返回设置的tag和alias
[JPUSHService setTags:tags alias:alias fetchCompletionHandle:^(int iResCode, NSSet *iTags, NSString *iAlias){
 NSLog(@"rescode: %d, \ntags: %@, \nalias: %@\n", iResCode, iTags, iAlias);
}];

Method - setTags

调用此 API 来设置标签,支持回调函数。

该方法是 setTagsWithAlias (with Callback) 的简化版本,用于只变更标签的情况。

使用建议 

如果待设置的 alias / tags 是动态的,有可能在调用 setTagsWithAlias 时因为 alias / tags 无效而整调用失败。 

调用此方法只设置 tags,可以排除可能的无效的 alias 对本次调用的影响。

支持的版本

开始支持的版本:1.4.0

接口定义
+ (void)setTags:(NSSet *)tags callbackSelector:(SEL)cbSelector object:(id)theTarget;
参数说明
  • tags

    • nil 此次调用不设置此值。
    • 空集合([NSSet set])表示取消之前的设置。
    • 每次调用至少设置一个 tag,覆盖之前的设置,不是新增。
    • 有效的标签组成:字母(区分大小写)、数字、下划线、汉字。
    • 限制:每个 tag 命名长度限制为 40 字节,最多支持设置 100 个tag,但总长度不得超过1K字节。(判断长度需采用UTF-8编码)
    • 单个设备最多支持设置 100 个 tag。App 全局 tag 数量无限制。
  • callbackSelector

    • nil 此次调用不需要 Callback。
    • 用于回调返回对应的参数 alias, tags。并返回对应的状态码:0为成功,其他返回码请参考错误码定义。
    • 回调函数请参考SDK 实现。
  • theTarget

  • 参数值为实现了callbackSelector的实例对象。

  • nil 此次调用不需要 Callback。

    • (void)tagsAliasCallback:(int)iResCode tags:(NSSet)tags alias:(NSString)alias { NSLog(@"rescode: %d, \ntags: %@, \nalias: %@\n", iResCode, tags , alias);}

Method - setAlias

调用此 API 来设置别名,支持回调函数。

该方法是 setTagsWithAlias (with Callback) 的简化版本,用于只变更别名的情况。

支持的版本

开始支持的版本:1.4.0

接口定义
    + (void)setAlias:(NSString *)alias callbackSelector:(SEL)cbSelector object:(id)theTarget;
参数说明
  • alias 
    • 空字符串 (@"")表示取消之前的设置。
    • 每次调用设置有效的别名,覆盖之前的设置。
    • 有效的别名组成:字母(区分大小写)、数字、下划线、汉字。
    • 限制:alias 命名长度限制为 40 字节。(判断长度需采用UTF-8编码)
  • callbackSelector 
    • nil 此次调用不需要 Callback。
    • 用于回调返回对应的参数 alias, tags。并返回对应的状态码:0为成功,其他返回码请参考错误码定义。
    • 回调函数请参考SDK 实现。
  • theTarget

    • 参数值为实现了callbackSelector的实例对象。
    • nil 此次调用不需要 Callback。

    • (void)tagsAliasCallback:(int)iResCode tags:(NSSet)tags alias:(NSString)alias { NSLog(@"rescode: %d, \ntags: %@, \nalias: %@\n", iResCode, tags , alias) }

Method - filterValidTags

用于过滤出正确可用的 tags。

如果总数量超出最大限制则返回最大数量的靠前的可用tags。

使用建议 

设置 tags 时,如果其中一个 tag 无效,则整个设置过程失败。 

如果 App 的 tags 会在运行过程中动态设置,并且存在对 JPush SDK tag 规定的无效字符,则有可能一个 tag 无效导致这次调用里所有的 tags 更新失败。 

这时你可以调用本方法 filterValidTags 来过滤掉无效的 tags,得到有效的 tags,再调用 JPush SDK 的 set tags / alias 方法。

支持的版本

开始支持的版本:1.4.0

接口定义
+ (NSSet*)filterValidTags:(NSSet*)tags;
参数说明
  • tags 
    • 原 tag 集合。
接口返回

有效的 tag 集合。

错误码定义

Code 描述 详细解释
6001 无效的设置,tag/alias 不应参数都为 null  
6002 设置超时 建议重试
6003 alias 字符串不合法 有效的别名、标签组成:字母(区分大小写)、数字、下划线、汉字。
6004 alias超长。最多 40个字节 中文 UTF-8 是 3 个字节
6005 某一个 tag 字符串不合法 有效的别名、标签组成:字母(区分大小写)、数字、下划线、汉字。
6006 某一个 tag 超长。一个 tag 最多 40个字节 中文 UTF-8 是 3 个字节
6007 tags 数量超出限制。最多 100个 这是一台设备的限制。一个应用全局的标签数量无限制。
6008 tag 超出总长度限制 总长度最多 1K 字节
6011 10s内设置tag或alias大于10次 短时间内操作过于频繁

你可能感兴趣的:(ios)