标签管理接口（4.x）-阿里云帮助中心

调用前准备

调用前，请完成 PushServiceFactory.init 和推送注册，并确认 register 的 onSuccess 已返回。通过 PushServiceFactory.getCloudPushService() 获取 CloudPushService。示例使用非空 CommonCallback；失败时查看 onFailed 的 errorCode 和 errorMessage。

说明

4.x 仅支持设备标签。接口不再包含 target 和 alias 参数，不支持通过客户端接口绑定账号标签或别名标签。

与 3.x 的接口变化

4.x 仅操作当前设备的标签，移除了带 target、alias 参数的旧接口。使用旧签名的代码需要按下表修改后才能编译。

3.x 接口	4.x 接口
`bindTag(int target, String[] tags, String alias, CommonCallback callback)`	`bindTag(String[] tags, CommonCallback callback)`
`unbindTag(int target, String[] tags, String alias, CommonCallback callback)`	`unbindTag(String[] tags, CommonCallback callback)`
`listTags(int target, CommonCallback callback)`	`listTags(CommonCallback callback)`

原来使用 DEVICE_TARGET 操作设备标签时，删除 target 和 alias 实参，按上述新签名调用。DEVICE_TARGET、ACCOUNT_TARGET、ALIAS_TARGET 常量均已移除；账号标签和别名标签不再支持，使用这两类标签的业务需调整分组方式。

绑定设备标签（bindTag）

为当前设备添加标签，用于按标签推送。数组不能为空，标签名不能为空。单个应用最多支持 1 万个标签，单个标签名最多 128 字符；标签绑定可能存在生效延迟。

接口定义

void bindTag(String[] tags, CommonCallback callback);

所属类

CloudPushService

参数说明

参数	类型	是否必填	说明
tags	String[]	是	待绑定的标签数组，不能为 null 或空数组；标签名不能为空，长度不超过 128 个字符。
callback	CommonCallback	否	操作结果回调。可为 null；建议传入非空回调，以获取成功结果或失败原因。

返回值与回调

返回值为 void。标签绑定成功时触发 onSuccess(String response)；操作失败时触发 onFailed(String errorCode, String errorMessage)，分别返回错误码和错误信息。

代码示例

Java

CloudPushService pushService = PushServiceFactory.getCloudPushService();
pushService.bindTag(new String[]{"news", "sports"}, new CommonCallback() {
    @Override
    public void onSuccess(String response) {
        Log.i("PushDemo", "bindTag success");
    }

    @Override
    public void onFailed(String errorCode, String errorMessage) {
        Log.e("PushDemo", "bindTag failed: " + errorCode + ", " + errorMessage);
    }
});

Kotlin

val pushService = PushServiceFactory.getCloudPushService()
pushService.bindTag(arrayOf("news", "sports"), object : CommonCallback {
    override fun onSuccess(response: String?) {
        Log.i("PushDemo", "bindTag success")
    }

    override fun onFailed(errorCode: String?, errorMessage: String?) {
        Log.e("PushDemo", "bindTag failed: $errorCode, $errorMessage")
    }
})

解绑设备标签（unbindTag）

解除当前设备与指定标签的关联，保留应用中的标签。

接口定义

void unbindTag(String[] tags, CommonCallback callback);

所属类

CloudPushService

参数说明

参数	类型	是否必填	说明
tags	String[]	是	待解绑的标签数组，不能为 null 或空数组。每个元素为需要与当前设备解除关联的标签名。
callback	CommonCallback	否	操作结果回调。可为 null；建议传入非空回调，以获取成功结果或失败原因。

返回值与回调

返回值为 void。标签解绑成功时触发 onSuccess(String response)；操作失败时触发 onFailed(String errorCode, String errorMessage)，分别返回错误码和错误信息。

代码示例

Java

CloudPushService pushService = PushServiceFactory.getCloudPushService();
pushService.unbindTag(new String[]{"sports"}, new CommonCallback() {
    @Override
    public void onSuccess(String response) {
        Log.i("PushDemo", "unbindTag success");
    }

    @Override
    public void onFailed(String errorCode, String errorMessage) {
        Log.e("PushDemo", "unbindTag failed: " + errorCode + ", " + errorMessage);
    }
});

Kotlin

val pushService = PushServiceFactory.getCloudPushService()
pushService.unbindTag(arrayOf("sports"), object : CommonCallback {
    override fun onSuccess(response: String?) {
        Log.i("PushDemo", "unbindTag success")
    }

    override fun onFailed(errorCode: String?, errorMessage: String?) {
        Log.e("PushDemo", "unbindTag failed: $errorCode, $errorMessage")
    }
})

查询设备标签（listTags）

查询当前设备绑定的标签，接口仅接收 callback 参数，结果从 onSuccess(response) 获取。查询结果可能来自 SDK 的短时缓存，绑定和解绑结果请以对应操作的回调为准。

接口定义

void listTags(CommonCallback callback);

所属类

CloudPushService

参数说明

参数	类型	是否必填	说明
callback	CommonCallback	否	查询结果回调。请传入非空回调以获取结果；传入 null 时无法接收查询结果。

返回值与回调

返回值为 void。查询成功时触发 onSuccess(String response)，response 为当前设备的标签列表结果；查询失败时触发 onFailed(String errorCode, String errorMessage)，分别返回错误码和错误信息。

代码示例

Java

CloudPushService pushService = PushServiceFactory.getCloudPushService();
pushService.listTags(new CommonCallback() {
    @Override
    public void onSuccess(String response) {
        String tagsResult = response;
        // 按业务需要处理返回的标签列表。
    }

    @Override
    public void onFailed(String errorCode, String errorMessage) {
        Log.e("PushDemo", "listTags failed: " + errorCode + ", " + errorMessage);
    }
});

Kotlin

val pushService = PushServiceFactory.getCloudPushService()
pushService.listTags(object : CommonCallback {
    override fun onSuccess(response: String?) {
        val tagsResult = response
        // 按业务需要处理返回的标签列表。
    }

    override fun onFailed(errorCode: String?, errorMessage: String?) {
        Log.e("PushDemo", "listTags failed: $errorCode, $errorMessage")
    }
})

使用建议

按业务划分设备标签；面向全部设备发送时使用全量推送。标签名使用非敏感业务标识。

调用前准备

与 3.x 的接口变化

绑定设备标签（bindTag）

解绑设备标签（unbindTag）

查询设备标签（listTags）

使用建议

相关文档