Tag management API (4.x)
This topic describes how to use the Android SDK 4.x to bind, unbind, and list tags for the current device.
The APIs and examples in this topic are for Mobile Push Android SDK 4.x, based on version 4.0.0. If you are using SDK 3.x, refer to the corresponding 3.x API documentation.
Before you begin
Before making any calls, complete the PushServiceFactory.init process and push registration. Confirm that the onSuccess callback for registration has returned. Obtain the CloudPushService instance by calling PushServiceFactory.getCloudPushService(). In case of failure, check the error code and error message in the onFailed callback.
Version 4.x only supports device tags. The APIs no longer include the target and alias parameters. Binding an account tag or alias tag through client-side APIs is no longer supported.
API changes from 3.x
Version 4.x APIs only operate on tags for the current device and have removed the legacy APIs that included target and alias parameters. Code that uses the old method signatures must be updated as shown in the following table to compile.
|
3.x API |
4.x API |
|
|
|
|
|
|
|
|
|
If you previously used DEVICE_TARGET to manage device tags, remove the target and alias arguments and call the method using the new signature. The DEVICE_TARGET, ACCOUNT_TARGET, and ALIAS_TARGET constants have been removed. Support for account tags and alias tags has been discontinued. If your service relies on these tag types, you must adjust your grouping strategy.
Bind device tags (bindTag)
Binds one or more tags to the current device to enable targeted pushes. The tags array cannot be empty, and tag names must be non-empty strings. Each application can have a maximum of 10,000 tags, and each tag name can be up to 128 characters long. Note that there might be a short delay before a newly bound tag becomes effective.
API definition
void bindTag(String[] tags, CommonCallback callback);
Class
CloudPushService
Parameters
|
Parameter |
Type |
Required |
Description |
|
tags |
String[] |
Yes |
An array of tags to bind. The array cannot be null or empty. Each tag name cannot be an empty string and must be 128 characters or fewer. |
|
callback |
CommonCallback |
No |
A callback for the operation result. This parameter can be |
Return value and callback
This method has a void return value. On success, the onSuccess(String response) callback is triggered. On failure, the onFailed(String errorCode, String errorMessage) callback is triggered, providing an error code and an error message.
Code example
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);
}
});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")
}
})Unbind device tags (unbindTag)
Unbinds specified tags from the current device. This action does not delete the tags from the application.
API definition
void unbindTag(String[] tags, CommonCallback callback);
Class
CloudPushService
Parameters
|
Parameter |
Type |
Required |
Description |
|
tags |
String[] |
Yes |
An array of tag names to unbind from the device. The array cannot be null or empty. |
|
callback |
CommonCallback |
No |
A callback for the operation result. This parameter can be |
Return value and callback
This method has a void return value. On success, the onSuccess(String response) callback is triggered. On failure, the onFailed(String errorCode, String errorMessage) callback is triggered, providing an error code and an error message.
Code example
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);
}
});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")
}
})List device tags (listTags)
Lists all tags bound to the current device. The API accepts only a callback parameter, and the result is returned in the onSuccess(response) callback. The query result may be returned from a local SDK cache. For the definitive status of bind or unbind operations, rely on their respective callbacks.
API definition
void listTags(CommonCallback callback);
Class
CloudPushService
Parameters
|
Parameter |
Type |
Required |
Description |
|
callback |
CommonCallback |
No |
A callback to receive the query result. You must provide a non-null callback because the result is returned asynchronously and is only available through this callback. |
Return value and callback
This method has a void return value. On success, the onSuccess(String response) callback is triggered, and response contains the list of tags for the current device. On failure, the onFailed(String errorCode, String errorMessage) callback is triggered, providing an error code and an error message.
Code example
CloudPushService pushService = PushServiceFactory.getCloudPushService();
pushService.listTags(new CommonCallback() {
@Override
public void onSuccess(String response) {
String tagsResult = response;
// Process the returned tag list based on your business needs.
}
@Override
public void onFailed(String errorCode, String errorMessage) {
Log.e("PushDemo", "listTags failed: " + errorCode + ", " + errorMessage);
}
});val pushService = PushServiceFactory.getCloudPushService()
pushService.listTags(object : CommonCallback {
override fun onSuccess(response: String?) {
val tagsResult = response
// Process the returned tag list based on your business needs.
}
override fun onFailed(errorCode: String?, errorMessage: String?) {
Log.e("PushDemo", "listTags failed: $errorCode, $errorMessage")
}
})Recommendations
Organize device tags based on your business logic. Use the broadcast push feature to send notifications to all devices. Use non-sensitive business identifiers for tag names.
References
For the integration process, see Get started with Android SDK (4.x).
For applications that use SDK 3.x, refer to Tag management API (3.x).