Basic configuration APIs (3.x)

Updated at:
Important

This document covers Android SDK 3.x. The minimum required version for each API is specified in its description. References to "and later versions" refer only to the 3.x series. For applications that use 4.x, see Basic configuration API (4.x).

Parameter

Description

Configure Application

Configures the main Application class.

Configure AppKey

Configures the AppKey. This call is not required if the AppKey is already configured in the AndroidManifest.xml file.

Configure AppSecret

Configures the AppSecret. This call is not required if the AppSecret is already configured in the AndroidManifest.xml file.

Disable channel process

Disables the channel process.

Disable channel process heartbeat

Disables the heartbeat for the channel process.

Periodically start channel process

Enables the channel process to restart periodically. By default, this feature is disabled.

Configure interval for periodic channel process start

Configures the restart interval for the channel process. This setting takes effect only when the periodic start feature is enabled. The default is 5 minutes.

Register push channel

Registers the push channel to start receiving push notifications. Registration can be delayed, for example, until the user agrees to the privacy policy.

Get device ID

Returns the unique device ID, which is required to send pushes to a specific device.

Set log level

Sets the log level before initializing the channel. The default is CloudPushService.LOG_DEBUG.

Enable push channel

Enables the push channel. Since the channel is enabled by default, this method is only used to re-enable it after a call to Disable Push Channel.

Disable push channel

Disables the push channel by notifying the server to stop sending pushes to the device. This action does not disconnect the channel. The disabled state persists even after the SDK is re-initialized. To resume receiving pushes, call Enable Push Channel.

Query push channel status

Checks whether the push channel is currently enabled or disabled.

Set message-receiving IntentService

Sets a custom IntentService, which must extend AliyunMessageIntentService, to receive push messages. This overrides the default delivery method, which uses a broadcast.

Receive SDK log output

Registers a logging interface to receive SDK logs for troubleshooting.

Configure the application

Sets the application.

Important

application is required.

application

Interface definition

PushInitConfig.Builder application(Application application)

Containing class

PushInitConfig.Builder

Parameter description

Parameter

Type

Required

Description

application

Application

Yes

The Application object.

Code example

PushInitConfig config = new PushInitConfig.Builder()
      	.application(application)
        .build();
val config = PushInitConfig.Builder()
    .application(application)
    .build()

Configure appKey

You do not need to call this method if you have already configured the appKey in the AndroidManifest.xml file.

appKey

Method signature

PushInitConfig.Builder appKey(String appKey)

Class

PushInitConfig.Builder

Parameters

Parameter

Type

Required

Description

appKey

String

Yes

The appKey for EMAS.

Code example

PushInitConfig config = new PushInitConfig.Builder()
      	.appKey(appKey)
        .build();
val config = PushInitConfig.Builder()
    .appKey(appKey)
    .build()

Configure AppSecret

Sets the AppSecret. You can skip this call if you have already configured the AppSecret in the AndroidManifest.xml file.

appSecret

API definition

PushInitConfig.Builder appSecret(String appSecret)

Class

PushInitConfig.Builder

Parameters

Parameter

Type

Required

Description

appSecret

String

Yes

The AppSecret for Enterprise Mobile Application Studio (EMAS).

Code sample

PushInitConfig config = new PushInitConfig.Builder()
      	.appSecret(appSecret)
        .build();
val config = PushInitConfig.Builder()
    .appSecret(appSecret)
    .build()

Disable channel process

Disables the channel process.

disableChannelProcess

API definition

PushInitConfig.Builder disableChannelProcess(boolean disableChannelProcess)

Warning

This API is deprecated. The channel process is disabled by default. To enable it, set the enable attribute of ChannelService and ChannelService$KernelService to true in AndroidManifest.xml.

Class

PushInitConfig.Builder

Parameters

Parameter

Type

Required

Description

disableChannelProcess

boolean

Yes

  • true: Disables the channel process.

  • false: Enables the channel process.

Code sample

PushInitConfig config = new PushInitConfig.Builder()
      	.disableChannelProcess(false)
        .build();
val config = PushInitConfig.Builder()
    .disableChannelProcess(false)
    .build()

Disable channel process heartbeat

Disables the channel process heartbeat.

disableChannelProcessHeartbeat

API definition

PushInitConfig.Builder disableChannelProcessHeartbeat(boolean disableChannelProcessHeartbeat)

Warning

This API is deprecated. The channel process heartbeat is disabled by default. To enable the channel process heartbeat, set the enable attribute of AccsJobService, EventReceiver, and ServiceReceiver to true in the AndroidManifest.xml file.

Class

PushInitConfig.Builder

Parameters

Parameter

Type

Required

Description

disableChannelProcessHeartbeat

boolean

Yes

  • true: Disables the channel process heartbeat.

  • false: Enables the channel process heartbeat.

Code example

PushInitConfig config = new PushInitConfig.Builder()
      	.disableChannelProcessHeartbeat(false)
        .build();
val config = PushInitConfig.Builder()
    .disableChannelProcessHeartbeat(false)
    .build()

Configure loop start for the channel process

Enables or disables loop start for the channel process. This feature is disabled by default.

loopStartChannel

API definition

PushInitConfig.Builder loopStartChannel(boolean enable)

Containing class

PushInitConfig.Builder

Parameters

Parameter

Type

Required

Description

enable

boolean

Yes

  • true: Enables loop start.

  • false: Disables loop start.

Code sample

PushInitConfig config = new PushInitConfig.Builder()
      	.loopStartChannel(true)
        .build();
val config = PushInitConfig.Builder()
    .loopStartChannel(true)
    .build()

Periodic start interval

This parameter sets the interval at which the Channel process periodically starts. This setting takes effect only when the periodic start feature is enabled. The default interval is 5 minutes.

loopInterval

API

PushInitConfig.Builder loopInterval(long interval)

Class

PushInitConfig.Builder

Parameters

Parameter

Type

Required

Description

interval

long

Yes

The loop interval, in milliseconds.

Code example

PushInitConfig config = new PushInitConfig.Builder()
      	.loopInterval(5 * 60 * 1000)
        .build();
val config = PushInitConfig.Builder()
    .loopInterval(5 * 60 * 1000)
    .build()

Register the push channel

Register the push channel to start receiving push notifications. You can delay registration, for example, until the user accepts the privacy policy.

register

API definition

void register(Context context, CommonCallback callback)

Containing class

CloudPushService

Parameters

Parameter

Type

Required

Description

context

Context

Yes

The application context. An ApplicationContext is required.

callback

CommonCallback

Yes

The callback to execute upon completion. For a list of error codes, see Error handling (3.x).

Code sample

CloudPushService pushService = PushServiceFactory.getCloudPushService();
pushService.register(applicationContext, new CommonCallback() {
    @Override
    public void onSuccess(String response) {
        Log.i(TAG, "init cloudchannel success  " + pushService.getDeviceId());
    }

    @Override
    public void onFailed(String errorCode, String errorMessage) {
        Log.e(TAG, "init cloudchannel failed -- errorcode:" + errorCode + " -- errorMessage:" + errorMessage);
    }
});
val pushService = PushServiceFactory.getCloudPushService()
pushService.register(applicationContext, object : CommonCallback() {
    override fun onSuccess(response: String?) {
        Log.i(TAG, "init cloudchannel success  " + pushService.deviceId)
    }

    override fun onFailed(errorCode: String, errorMessage: String) {
        Log.e(TAG, "init cloudchannel failed -- errorcode:$errorCode -- errorMessage:$errorMessage")
    }
})

register

This registration method allows you to dynamically provide the app key and app secret.

API definition

void register(Context context, String appKey, String appSecret, CommonCallback callback)

Warning

This API is deprecated.

Containing class

CloudPushService

Parameters

Parameter

Type

Required

Description

context

Context

Yes

The application context. An ApplicationContext is required.

appKey

String

Yes

The app key for Enterprise Mobile Application Studio (EMAS).

appSecret

String

Yes

The app secret for Enterprise Mobile Application Studio (EMAS).

callback

CommonCallback

Yes

The callback to execute upon completion. For a list of error codes, see Error handling (3.x).

Get device ID

Returns the unique device ID. Use this ID to send pushes to a specific device.

getDeviceId

API definition

String getDeviceId()

class

CloudPushService

return value

Type

Description

String

The unique device ID.

code example

String deviceId = PushServiceFactory.getCloudPushService().getDeviceId();
val deviceId = PushServiceFactory.getCloudPushService().deviceId

Set the log level

This section describes how to configure logs and use listening methods for version 3.x. For details about the unified log TAG, when to set the log level after initialization, and the listening scope in version 4.x, see Basic configuration API (4.x).

Set the log level before you initialize the channel. The default level is CloudPushService.LOG_DEBUG.

setLogLevel

API definition

void setLogLevel(int logLevel)

Class

CloudPushService

Parameters

Parameter

Type

Required

Description

logLevel

int

Yes

The log level. Valid values are:

CloudPushService.LOG_ERROR

CloudPushService.LOG_INFO

CloudPushService.LOG_DEBUG

CloudPushService.LOG_OFF: Disables logging.

Code sample

PushServiceFactory.getCloudPushService().setLogLevel(CloudPushService.LOG_INFO);
PushServiceFactory.getCloudPushService().setLogLevel(CloudPushService.LOG_INFO)

Enable the push channel

Enables the push channel. Since the push channel is enabled by default, you only need to call this method to re-enable a channel that was previously disabled.

Important
  • Supported in SDK v3.0.3 and later.

  • This method dynamically enables the push channel at runtime. The change takes effect immediately, except in broadcast push scenarios where it may take up to 24 hours.

turnOnPushChannel

API definition

void turnOnPushChannel(CommonCallback callback)

Containing class

CloudPushService

Parameters

Parameter

Type

Required

Description

callback

CommonCallback

Yes

A callback invoked to report the success or failure of the operation.

Code sample

PushServiceFactory.getCloudPushService().turnOnPushChannel(new CommonCallback() {
    @Override
    public void onSuccess(String s) {
        
    }

    @Override
    public void onFailed(String errorCode, String errorMsg) {
        
    }
});
PushServiceFactory.getCloudPushService().turnOnPushChannel(object : CommonCallback() {
    override fun onSuccess(s: String?) {}
    override fun onFailed(errorCode: String?, errorMsg: String?) {}
})

Turn off the push channel

Turns off the push channel. This action does not disconnect the push channel; instead, it informs the service to stop sending pushes to the device. The channel remains off even after you re-initialize the SDK. To receive pushes again, you must explicitly call the method to turn the channel on.

Important
  • Supported in SDK v3.0.3 and later.

  • Use this method to dynamically turn off the push channel at runtime. In broadcast push scenarios, it takes up to 24 hours for this change to take effect. In all other scenarios, the change takes effect immediately.

turnOffPushChannel

API definition

void turnOffPushChannel(CommonCallback callback)

Class

CloudPushService

Parameters

Parameter

Type

Required

Description

callback

CommonCallback

Yes

A callback invoked to indicate whether the operation succeeded or failed.

Code sample

PushServiceFactory.getCloudPushService().turnOffPushChannel(new CommonCallback() {
    @Override
    public void onSuccess(String s) {
        
    }

    @Override
    public void onFailed(String errorCode, String errorMsg) {
        
    }
});
PushServiceFactory.getCloudPushService().turnOffPushChannel(object : CommonCallback() {
    override fun onSuccess(s: String?) {}
    override fun onFailed(errorCode: String?, errorMsg: String?) {}
})

Check push channel status

Checks if the push channel is enabled or disabled.

checkPushChannelStatus

API definition

void checkPushChannelStatus(CommonCallback callback)

Class

CloudPushService

Parameters

Parameter

Type

Required

Description

callback

CommonCallback

Yes

A callback to handle the query result. The response string in the onSuccess method is 'on' if the push channel is enabled, and 'off' otherwise.

Sample code

PushServiceFactory.getCloudPushService().checkPushChannelStatus(new CommonCallback() {
    @Override
    public void onSuccess(String response) {
        if (response.equals("on")) {
            // The channel is enabled.
        } else {
            // The channel is disabled.
        }
    }

    @Override
    public void onFailed(String errorCode, String errorMsg) {
        
    }
});
PushServiceFactory.getCloudPushService().checkPushChannelStatus(object : CommonCallback {
    override fun onSuccess(response: String) {
        if (response == "on") {
            // The channel is enabled.
        } else {
            // The channel is disabled.
        }
    }

    override fun onFailed(errorCode: String, errorMsg: String) {}
})

Set message-receiving IntentService

Sets the service to receive push. The service must extend AliyunMessageIntentService. By default, push is received via a broadcast. Setting this service overrides the default broadcast receiver, routing push to this service instead.

Important
  • This feature is supported in SDK version 3.0.10 and later.

  • This lets you receive message callbacks through an IntentService component.

  • Once set, this component handles messages instead of MessageReceiver.

setPushIntentService

API definition

void setPushIntentService(Class messageIntentService)

Containing class

CloudPushService

Parameters

Parameter

Type

Required

Description

messageIntentService

Class

No

The custom IntentService class for receiving messages. It must extend AliyunMessageIntentService.

A null value reverts to receiving push via broadcast.

Code sample

PushServiceFactory.getCloudPushService()
      .setPushIntentService(MyMessageIntentService.class);
PushServiceFactory.getCloudPushService()
      .setPushIntentService(MyMessageIntentService.class)

Capture SDK log output

Learn how to configure and listen for SDK logs in v3.x. For v4.x, refer to basic configuration interface (v4.x) for information on the unified log TAG, the order for setting the log level, and the listening scope.

Important

When writing logs to a file or uploading them, exclude debug and info level logs and control the log volume to minimize the impact on application performance.

Register a log listener to capture SDK log messages for troubleshooting.

addListener

interface definition

static void addListener(final LoggerListener lisn)

Class

AmsLogger

code sample

AmsLogger.addListener(new LoggerListener() {
	@Override
	public void d(String TAG, String msg, Throwable tr, int flag) {

	}

	@Override
	public void i(String TAG, String msg, Throwable tr, int flag) {

	}

        @Override
	public void w(String TAG, String msg, Throwable tr, int flag) {

	}

	@Override
	public void e(String TAG, String msg, Throwable tr, int flag) {

	}
});
AmsLogger.addListener(object : LoggerListener {
    override fun d(TAG: String, msg: String, tr: Throwable, flag: Int) {}
    override fun i(TAG: String, msg: String, tr: Throwable, flag: Int) {}
    override fun w(TAG: String, msg: String, tr: Throwable, flag: Int) {}
    override fun e(TAG: String, msg: String, tr: Throwable, flag: Int) {}
})