Alias management API (4.x)

Updated at:

This topic describes how to add, remove, and query aliases for the current device using the Android SDK 4.x.

Note

This topic applies to Mobile Push Android SDK 4.x. The APIs and code samples are based on the released version 4.0.0. For applications that use version 3.x, see the corresponding 3.x API documentation.

Prerequisites

Before you call the APIs, initialize PushServiceFactory and register the device for push notifications. Confirm that the onSuccess callback of the register method has returned. Call PushServiceFactory.getCloudPushService() to get a CloudPushService instance. The examples use a non-null CommonCallback. If an operation fails, check the errorCode and errorMessage in the onFailed callback.

Add alias (addAlias)

Adds an alias to the current device for targeted pushes. A device supports a maximum of 128 aliases, and you can associate a single alias with up to 128 devices. The maximum length of an alias is 128 bytes.

Method signature

void addAlias(String alias, CommonCallback callback);

Class

CloudPushService

Parameters

Parameter

Type

Required

Description

alias

String

Yes

The alias to add. This parameter cannot be null or an empty string. The maximum length is 128 bytes.

callback

CommonCallback

No

The callback for the operation's result. This parameter can be null. We recommend providing a non-null callback to handle the success or failure.

Return value and callback

The method returns void. If the alias is added successfully, the system calls the onSuccess(String response) callback. If the operation fails, the system calls the onFailed(String errorCode, String errorMessage) callback, which returns the error code and error message.

Code sample

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

    @Override
    public void onFailed(String errorCode, String errorMessage) {
        Log.e("PushDemo", "addAlias failed: " + errorCode + ", " + errorMessage);
    }
});
val pushService = PushServiceFactory.getCloudPushService()
pushService.addAlias("app_alias_001", object : CommonCallback {
    override fun onSuccess(response: String?) {
        Log.i("PushDemo", "addAlias success")
    }

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

Remove alias (removeAlias)

Removes a specific alias from the current device, or clears all aliases from the current device. This operation does not affect other devices that use the same alias.

Method signature

void removeAlias(String alias, CommonCallback callback);

Class

CloudPushService

Parameters

Parameter

Type

Required

Description

alias

String

No

The alias to remove. To remove all aliases from the current device, pass null or an empty string.

callback

CommonCallback

No

The callback for the operation's result. This parameter can be null. We recommend providing a non-null callback to handle the success or failure.

Return value and callback

The method returns void. If the alias is removed successfully, the system calls the onSuccess(String response) callback. If the operation fails, the system calls the onFailed(String errorCode, String errorMessage) callback, which returns the error code and error message.

Code sample

// To remove all aliases from the current device, replace "app_alias_001" with null.
CloudPushService pushService = PushServiceFactory.getCloudPushService();
pushService.removeAlias("app_alias_001", new CommonCallback() {
    @Override
    public void onSuccess(String response) {
        Log.i("PushDemo", "removeAlias success");
    }

    @Override
    public void onFailed(String errorCode, String errorMessage) {
        Log.e("PushDemo", "removeAlias failed: " + errorCode + ", " + errorMessage);
    }
});
// To remove all aliases from the current device, replace "app_alias_001" with null.
val pushService = PushServiceFactory.getCloudPushService()
pushService.removeAlias("app_alias_001", object : CommonCallback {
    override fun onSuccess(response: String?) {
        Log.i("PushDemo", "removeAlias success")
    }

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

Query aliases (listAliases)

The result is returned in the onSuccess(response) callback. This API has only one parameter: callback. The query uses a short-term cache. To confirm the result of an add or remove operation, rely on the callback from that specific operation instead of calling this API immediately.

Method signature

void listAliases(CommonCallback callback);

Class

CloudPushService

Parameters

Parameter

Type

Required

Description

callback

CommonCallback

No

The callback for the query result. Provide a non-null callback to receive it. If you pass null, you will not receive the query result.

Return value and callback

The method returns void. If the query is successful, the system calls the onSuccess(String response) callback, and the response parameter contains the device's alias list. If the query fails, the system calls the onFailed(String errorCode, String errorMessage) callback, which returns the error code and error message.

Code sample

CloudPushService pushService = PushServiceFactory.getCloudPushService();
pushService.listAliases(new CommonCallback() {
    @Override
    public void onSuccess(String response) {
        String aliasesResult = response;
        // Process the returned list of aliases based on your business requirements.
    }

    @Override
    public void onFailed(String errorCode, String errorMessage) {
        Log.e("PushDemo", "listAliases failed: " + errorCode + ", " + errorMessage);
    }
});
val pushService = PushServiceFactory.getCloudPushService()
pushService.listAliases(object : CommonCallback {
    override fun onSuccess(response: String?) {
        val aliasesResult = response
        // Process the returned list of aliases based on your business requirements.
    }

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

Related documentation

For the integration process, see Android SDK Integration (4.x).

For applications that use version 3.x, see Alias management API (3.x).