Basic configuration APIs (3.x)
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 |
|
Configures the main Application class. |
|
|
Configures the AppKey. This call is not required if the AppKey is already configured in the |
|
|
Configures the AppSecret. This call is not required if the AppSecret is already configured in the |
|
|
Disables the channel process. |
|
|
Disables the heartbeat for the channel process. |
|
|
Enables the channel process to restart periodically. By default, this feature is disabled. |
|
|
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. |
|
|
Registers the push channel to start receiving push notifications. Registration can be delayed, for example, until the user agrees to the privacy policy. |
|
|
Returns the unique device ID, which is required to send pushes to a specific device. |
|
|
Sets the log level before initializing the channel. The default is CloudPushService.LOG_DEBUG. |
|
|
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. |
|
|
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. |
|
|
Checks whether the push channel is currently enabled or disabled. |
|
|
Sets a custom IntentService, which must extend AliyunMessageIntentService, to receive push messages. This overrides the default delivery method, which uses a broadcast. |
|
|
Registers a logging interface to receive SDK logs for troubleshooting. |
Configure the application
Sets the application.
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 |
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)
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 |
|
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)
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 |
|
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 |
|
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 |
|
callback |
CommonCallback |
Yes |
The |
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)
This API is deprecated.
Containing class
CloudPushService
Parameters
|
Parameter |
Type |
Required |
Description |
|
context |
Context |
Yes |
The application context. An |
|
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 |
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().deviceIdSet 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.
-
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 pushscenarios 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.
-
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.
-
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.
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) {}
})