Basic configuration API-Enterprise Mobile Application Studio(EMAS)-阿里云帮助中心

Initial configuration

The initial configuration includes the configuration items required for Application Performance Monitoring (APM).

`setAppKey`

Sets the appKey for the EMAS platform. This parameter is required.

API definition

ApmOptions.Builder setAppKey(@NonNull String appKey)

Class

ApmOptions.Builder

Parameters

Parameter	Type	Required	Description
appKey	String	Yes	The appKey for the EMAS platform. This value cannot be null.

`setAppSecret`

Sets the appSecret for the EMAS platform. This parameter is required.

API definition

ApmOptions.Builder setAppSecret(@NonNull String appSecret)

Class

ApmOptions.Builder

Parameters

Parameter	Type	Required	Description
appSecret	String	Yes	The appSecret for the EMAS platform. This value cannot be null.

`setAppRsaSecret`

Sets the appRsaSecret for the EMAS platform. This parameter is required.

API definition

ApmOptions.Builder setAppRsaSecret(@NonNull String appRsaSecret)

Class

ApmOptions.Builder

Parameters

Parameter	Type	Required	Description
appRsaSecret	String	Yes	The appRsaSecret for the EMAS platform. This value cannot be null.

`setApplication`

Sets the application instance. This parameter is required.

API definition

ApmOptions.Builder setApplication(@NonNull Application application)

Class

ApmOptions.Builder

Parameters

Parameter	Type	Required	Description
application	Application	Yes	This value cannot be null.

`addComponent`

Adds an APM component. You must add at least one component.

Important

You must add a component to enable its corresponding feature.

The following components are available:

com.aliyun.emas.apm.crash.ApmCrashAnalysisComponent.class
com.aliyun.emas.apm.remote.log.ApmRemoteLogComponent.class
com.aliyun.emas.apm.performance.ApmPerformanceComponent

API definition

ApmOptions.Builder addComponent(@NonNull Class<? extends BaseComponent> component)

Class

ApmOptions.Builder

Parameters

Parameter	Type	Required	Description
component	Class<? extends BaseComponent>	Yes	The component type.

`addProductOptions`

Adds product-specific options.

API definition

ApmOptions.Builder addProductOptions(@NonNull ApmProductOptions productOptions)

Class

ApmOptions.Builder

Parameters

Parameter	Type	Required	Description
productOptions	ApmProductOptions	No	Product-specific options.

Code example

Kotlin

import com.aliyun.emas.apm.Apm
import com.aliyun.emas.apm.ApmOptions
import com.aliyun.emas.apm.remote.log.RemoteLogOptions

Apm.preStart(ApmOptions.Builder()
        .addProductOptions(RemoteLogOptions.Builder()
            .setRemoteLogFileMaxSize(30)
            .build()
        ).build()
)

Java

import com.aliyun.emas.apm.Apm;
import com.aliyun.emas.apm.ApmOptions;
import com.aliyun.emas.apm.remote.log.RemoteLogOptions;

Apm.preStart(new ApmOptions.Builder()
        .addProductOptions(new RemoteLogOptions.Builder()
                // Set the maximum size of the local file for remote logs to 30 MB.
                .setRemoteLogFileMaxSize(30)
                .build())
        .build()
);

`setUserId`

Sets the user ID. Use this method when the user ID is available at configuration time. To update the user ID after initialization, call Apm#setUserId.

API definition

ApmOptions.Builder setUserId(@Nullable String userId)

Class

ApmOptions.Builder

Parameters

Parameter	Type	Required	Description
userId	String	No	The user ID. The value cannot exceed 128 characters. If this limit is exceeded, debug builds throw an `IllegalArgumentException`, while release builds discard the data.

`setUserNick`

Sets the user nickname. Use this method when the user nickname is available at configuration time. To update the user nickname after initialization, call Apm#setUserNick.

API definition

ApmOptions.Builder setUserNick(@Nullable String userNick)

Class

ApmOptions.Builder

Parameters

Parameter	Type	Required	Description
userNick	String	No	The user nickname. The value cannot exceed 128 characters. If this limit is exceeded, debug builds throw an `IllegalArgumentException`, while release builds discard the data.

`setChannel`

Sets the channel.

API definition

ApmOptions.Builder setChannel(@Nullable String channel)

Class

ApmOptions.Builder

Parameters

Parameter	Type	Required	Description
channel	String	No	The channel. The value cannot exceed 128 characters. If this limit is exceeded, debug builds throw an `IllegalArgumentException`, while release builds discard the data.

`setNoCollectionDataType`

Excludes specified data types from collection.

API definition

ApmOptions.Builder setNoCollectionDataType(int dataType)

Class

ApmOptions.Builder

Parameters

Parameter	Type	Required	Description
dataType	int	No	ApmOptions.NO_DEVICE_DATA: Prevents the collection of device data. ApmOptions.NO_OS_DATA: Prevents the collection of OS data. ApmOptions.NO_NETWORK_DATA: Prevents the collection of network data.

`openDebug`

Enables the debug log. This feature is disabled by default.

API definition

ApmOptions.Builder openDebug(boolean open)

Class

ApmOptions.Builder

Parameters

Parameter	Type	Required	Description
open	boolean	Yes	true: Enables debug logging. false: Disables debug logging.

`build`

Builds an ApmOptions instance.

Return value

ApmOptions build()

Class

ApmOptions.Builder

Return value

Type	Description
ApmOptions	The built ApmOptions instance.

Code example

Kotlin

val apmOptions = ApmOptions.Builder() 
        // Required. The application instance.
        .setApplication(application) 
        // Required. The appKey for the EMAS platform.
        .setAppKey(APP_KEY) 
        // Required. The appSecret for the EMAS platform.
        .setAppSecret(APP_SECRET) 
        // Required for performance analysis or remote log.
        .setAppRsaSecret(RSA_PUBLIC_KEY) 
        // Enables the crash analysis feature.
        .addComponent(ApmCrashAnalysisComponent::class.java) 
        // Enables the remote log feature.
        .addComponent(ApmRemoteLogComponent::class.java) 
        // Enables the performance analysis feature.
        .addComponent(ApmPerformanceComponent::class.java) 
        // Optional. Sets the user ID.
        .setUserId(userId) 
        // Optional. Sets the user nickname.
        .setUserNick(userNick) 
        // Optional. Sets the app channel.
        .setChannel(channel) 
        // Optional. This feature is disabled by default.
        .openDebug(true) 
        // Optional. Prevents collection of specified data types. This data will not be visible on the console.
        .setNoCollectionDataType(ApmOptions.NO_DEVICE_DATA or ApmOptions.NO_OS_DATA or ApmOptions.NO_NETWORK_DATA) // Builds the instance.
        .build()

Java

import com.aliyun.emas.apm.ApmOptions;

ApmOptions apmOptions = new ApmOptions.Builder()
        // Required. The application instance.
        .setApplication(application)  
        // Required. The appKey for the EMAS platform.
        .setAppKey(APP_KEY)    
        // Required. The appSecret for the EMAS platform.
        .setAppSecret(APP_SECRET)
        // Required for performance analysis or remote log.
        .setAppRsaSecret(RSA_PUBLIC_KEY)
        // Enables the crash analysis feature.
        .addComponent(ApmCrashAnalysisComponent.class)
        // Enables the remote log feature.
        .addComponent(ApmRemoteLogComponent.class)
        // Enables the performance analysis feature.
        .addComponent(ApmPerformanceComponent.class)
        // Optional. Sets the user ID.
        .setUserId(userId)
        // Optional. Sets the user nickname.
        .setUserNick(userNick)
        // Optional. Sets the app channel.
        .setChannel(channel)
        // Optional. This feature is disabled by default.
        .openDebug(true)
        // Optional. Prevents collection of specified data types. This data will not be visible on the console.
        .setNoCollectionDataType(ApmOptions.NO_DEVICE_DATA | ApmOptions.NO_OS_DATA | ApmOptions.NO_NETWORK_DATA)
        // Builds the instance.
        .build();

Enable mobile monitoring

Enabling mobile monitoring involves two phases: pre-start and start.

Note

Pre-start: For parameter configuration. Can be called before the user accepts the privacy agreement.
Start: For initialization. Must be called after the user accepts the privacy agreement.

`preStart`

This method applies the parameter configuration without performing initialization. It can be called before the user accepts the privacy agreement.

Signature

static void preStart(@NonNull ApmOptions options)

Class

Apm

Parameters

Parameter	Type	Required	Description
options	ApmOptions	Yes	The ApmOptions object for parameter configuration.

`start`

Starts mobile monitoring and completes the initialization. This method must be called after the user accepts the privacy agreement.

Important

Call the preStart method before the start method. Otherwise, the initialization fails.

Signature

static boolean start()

Class

Apm

Returns

Type	Description
boolean	true: The initialization was successful. false: The initialization failed.

Set user information

`setUserId`

Sets the user ID at runtime so you can update it when user information changes.

API

static void setUserId(@Nullable String userId)

Class

Apm

Parameters

Parameter	Type	Required	Description
userId	String	Optional	The user ID. The maximum length is 128 characters. If the ID exceeds this length, a test app throws an `IllegalArgumentException` and a production app discards the data.

`setUserNick`

Sets the user nickname at runtime so you can update it when user information changes.

API

static void setUserNick(@Nullable String userNick)

Class

Apm

Parameters

Parameter	Type	Required	Description
userNick	String	Optional	The user nickname. The maximum length is 128 characters. If the nickname exceeds this length, a test app throws an `IllegalArgumentException` and a production app discards the data.

Add custom dimensions

Use the following API to add a custom dimension across multiple products.

Note

This API is available in version 2.3.0 and later.

If you need to add different custom dimensions for each product, use each product's specific custom dimension API.

Crash analysis: Add custom dimension.
Memory analysis: Add custom dimension.

`setCustomKey`

This API adds a custom dimension to both crash analysis and memory analysis.

API definition

static void setCustomKey(@NonNull String key, @NonNull String value)

Class

Apm

Parameters

Parameter	Type	Required	Description
key	String	Required	The key for the custom dimension. Truncated if longer than 1024 characters.
value	String	Required	The value for the custom dimension. Truncated if longer than 1024 characters.

Set the log level

By default, the Application Real-Time Monitoring Service SDK logs at the INFO level and higher. Use the following API to set a different log level.

Note

This API is available in version 2.3.0 and later.

`setLoggerLevel`

Sets the log level.

API definition

static void setLoggerLevel(@NonNull LoggerLevel loggerLevel)

Class

Apm

Parameters

Parameter	Type	Required	Description
loggerLevel	LoggerLevel	Yes	The log level to set.

public enum LoggerLevel {
    VERBOSE(Log.VERBOSE),
    DEBUG(Log.DEBUG),
    INFO(Log.INFO),
    WARN(Log.WARN),
    ERROR(Log.ERROR),
    NONE(0);
}

Privacy data collection settings

To comply with regulatory requirements for privacy data collection, this feature provides switches to control it. By default, data collection is enabled.

setPrivacySwitch

Sets the switch for privacy data collection. This setting applies to all subsequent data collection operations.

API definition

static void setPrivacySwitch(int privacySwitch)

Class

Apm

Parameters

Parameter

Type

Required

Description

privacySwitch

int

Yes

To disable the collection of specific data types, use the following constants. You can combine multiple constants by using a bitwise operation.

Apm.DISABLE_DEVICE_MODEL
Apm.DISABLE_OS_VERSION
Apm.DISABLE_SCREEN_RESOLUTION
Apm.DISABLE_NETWORK_INFO

// Disable collection for device model and screen resolution.
Apm.setPrivacySwitch(Apm.DISABLE_DEVICE_MODEL | Apm.DISABLE_SCREEN_RESOLUTION);