What are the basic setting APIs for the Android SDK-Enterprise Mobile Application Studio(EMAS)-阿里云帮助中心

Configuration item	Description
Configure Application	The application must be configured.
Configure AppKey	Configure the AppKey. Skip this step if the AppKey is already configured in the `AndroidManifest.xml` file.
Configure AppSecret	Configure the AppSecret. Skip this step if the AppSecret is already configured in the `AndroidManifest.xml` file.
Configure channel process shutdown	Shut down the channel process.
Disable the channel process heartbeat	Disable the channel process heartbeat.
Periodically start the channel process	When starting the channel process, set it to start periodically. This feature is disabled by default.
Configure the interval for periodically starting the channel process	Configure the time interval for periodically starting the channel process. This setting takes effect only when periodic startup is enabled. The default interval is 5 minutes.
Register the push channel	Register the push channel to start accepting push messages. Delay the registration as needed, for example, after a user agrees to the privacy policy.
Get the device ID	Get the unique device ID. This ID is required for targeted pushes to a specific device.
Set the log level	Set the log level before channel initialization. The default level is CloudPushService.LOG_DEBUG.
Turn on the push channel	Turn on the push channel. The push channel is on by default. This operation is typically used with the operation to turn off the push channel. You only need to turn on the channel if it was previously turned off.
Turn off the push channel	Turn off the push channel. This does not disconnect the channel. It tells the service that the device will no longer accept push messages. After the channel is turned off, it will not be turned on even if you re-initialize the SDK. You must explicitly call the API to turn on the push channel to accept push messages again.
Query the push channel status	Check if the push channel is currently on or off.
Set the message-receiving IntentService	Set the service to accept push messages. The service must inherit AliyunMessageIntentService. By default, push messages are accepted through broadcast. After you set this service, push messages are accepted through the service instead.
Accept SDK log outputs	Register the log API to accept SDK log information for troubleshooting.

Configure Application

Configures the application.

Important

The application configuration is required.

`application`

API definition

PushInitConfig.Builder application(Application application)

Class

PushInitConfig.Builder

Metric descriptions

Parameter	Type	Required	Description
application	Application	Yes	The application.

Code examples

Kotlin

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

Java

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

Configure AppKey

Configures the AppKey. You can skip this call if the AppKey is already configured in the AndroidManifest.xml file.

`appKey`

API definition

PushInitConfig.Builder appKey(String appKey)

Class

PushInitConfig.Builder

Parameters

Parameter	Type	Required	Description
appKey	String	Yes	The AppKey for EMAS.

Code examples

Kotlin

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

Java

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

Configure AppSecret

Configures the AppSecret. You can skip this call if the AppSecret is already configured 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 EMAS.

Code examples

Kotlin

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

Java

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

Configure channel process shutdown

Shuts down 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 the channel process, set the enable property of ChannelService and ChannelService$KernelService to true in the AndroidManifest.xml file.

Class

PushInitConfig.Builder

Parameters

Parameter	Type	Required	Description
disableChannelProcess	boolean	Yes	true: Shuts down the channel process. false: Starts the channel process.

Code examples

Kotlin

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

Java

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

Disable the 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 property 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 examples

Kotlin

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

Java

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

Periodically start the channel process

Configures the channel process to start periodically. This feature is disabled by default.

`loopStartChannel`

API definition

PushInitConfig.Builder loopStartChannel(boolean enable)

Class

PushInitConfig.Builder

Parameters

Parameter	Type	Required	Description
loopStartChannel	boolean	Yes	true: Enables periodic startup for the channel process. false: Disables periodic startup for the channel process.

Code examples

Kotlin

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

Java

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

Configure the interval for periodically starting the channel process

Configures the time interval for the periodic startup of the channel process. This setting takes effect only if periodic startup is enabled. The default interval is 5 minutes.

`loopInterval`

API definition

PushInitConfig.Builder loopInterval(long interval)

Class

PushInitConfig.Builder

Parameters

Parameter	Type	Required	Description
loopInterval	long	Yes	The loop interval in milliseconds.

Code examples

Kotlin

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

Java

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

Register the push channel

Registers the push channel to start accepting push messages. You can delay the registration as needed, such as after a user agrees to the privacy policy.

`register`

API definition

void register(Context context, CommonCallback callback)

Class

CloudPushService

Parameters

Parameter	Type	Required	Description
context	Context	Yes	The application context. ApplicationContext is required.
callback	CommonCallback	Yes	The callback. For more information about error codes, see Error handling.

Code examples

Kotlin

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")
    }
})

Java

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);
    }
});

`register`

A registration API that supports dynamic configuration of the AppKey and AppSecret. It has the same function as the other register API.

API definition

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

Warning

This API is deprecated.

Class

CloudPushService

Parameters

Parameter	Type	Required	Description
context	Context	Yes	The application context. ApplicationContext is required.
appKey	String	Yes	The AppKey for EMAS.
appSecret	String	Yes	The AppSecret for EMAS.
callback	CommonCallback	Yes	The callback. For more information about error codes, see Error handling.

Get the device ID

Retrieves the unique device ID. This ID is required for targeted pushes to a specific device.

`getDeviceId`

API definition

String getDeviceId()

Class

CloudPushService

Return value

Type	Description
String	The unique device ID.

Code examples

Kotlin

val deviceId = PushServiceFactory.getCloudPushService().deviceId

Java

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

Set the log level

Sets the log level before channel initialization. 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. The following levels are supported:

CloudPushService.LOG_ERROR

CloudPushService.LOG_INFO

CloudPushService.LOG_DEBUG

CloudPushService.LOG_OFF: Turns off logging.

Code examples

Kotlin

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

Java

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

Turn on the push channel

Turns on the push channel. The push channel is on by default. This operation is typically used with the operation to turn off the push channel. You only need to turn on the channel if it was previously turned off.

Important

This feature is supported in SDK V3.0.3 and later.
You can use this API to dynamically turn on the push channel at runtime. In full push scenarios, this operation takes 24 hours to take effect. In other scenarios, it takes effect in real time.

`turnOnPushChannel`

API definition

void turnOnPushChannel(CommonCallback callback)

Class

CloudPushService

Metric Description

Parameter	Type	Required	Description
callback	CommonCallback	Yes	The callback for the operation result.

Code examples

Kotlin

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

Java

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

    @Override
    public void onFailed(String errorCode, String errorMsg) {
        
    }
});

Turn off the push channel

Turns off the push channel. This operation does not disconnect the channel. It informs the service that the device will no longer accept push messages. After the channel is turned off, it will not be turned on even if you re-initialize the SDK. You must explicitly call the API to turn on the push channel to accept push messages again.

Important

This feature is supported in SDK V3.0.3 and later.
You can use this API to dynamically turn off the push channel at runtime. In full push scenarios, this operation takes 24 hours to take effect. In other scenarios, it takes effect in real time.

`turnOffPushChannel`

API definition

void turnOffPushChannel(CommonCallback callback)

Class

CloudPushService

Metric Description

Parameter	Type	Required	Description
callback	CommonCallback	Yes	The callback for the operation result.

Code examples

Kotlin

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

Java

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

    @Override
    public void onFailed(String errorCode, String errorMsg) {
        
    }
});

Query the push channel status

Checks whether the push channel is currently on or off.

`checkPushChannelStatus`

API definition

void checkPushChannelStatus(CommonCallback callback)

Class

CloudPushService

Parameters

Parameter	Type	Required	Description
callback	CommonCallback	Yes	The callback for the query result. A response of "on" indicates that the push channel is on. A response of "off" indicates that the push channel is off.

Code examples

Kotlin

PushServiceFactory.getCloudPushService().checkPushChannelStatus(object : CommonCallback {
    override fun onSuccess(response: String) {
        if (response == "on") {
            // The channel is currently on.
        } else {
            // The channel is currently off.
        }
    }

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

Java

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

    @Override
    public void onFailed(String errorCode, String errorMsg) {
        
    }
});

Set the message-receiving IntentService

Sets the service to accept push messages. The service must inherit AliyunMessageIntentService. By default, push messages are accepted through a broadcast. After you set this service, push messages are accepted through the service instead.

Important

This feature is supported in SDK V3.0.10 and later.
Accepts message callbacks through the IntentService component.
After you set this service, messages are processed by this component instead of MessageReceiver.

`setPushIntentService`

API definition

void setPushIntentService(Class messageIntentService)

Class

CloudPushService

Parameters

Parameter

Type

Required

Description

messageIntentService

Class

The class of the custom IntentService for accepting messages. It must inherit AliyunMessageIntentService.

A null value indicates that push messages are accepted through broadcast.

Code examples

Kotlin

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

Java

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

Accept SDK log outputs

Important

If you want to output logs to a file or upload them, do not include debug or info level logs. This prevents an excessive log volume, which can affect application performance.

Registers the log API to accept SDK log information for troubleshooting.

`addListener`

API definition

static void addListener(final LoggerListener lisn)

Class

AmsLogger

Code examples

Kotlin

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) {}
})

Java

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) {

	}
});