Android SDK configuration reference - Application Real-Time Monitoring Service

ARMS Real User Monitoring provides a series of software development kit (SDK) configuration items. You can set parameters to meet specific requirements. This topic describes common SDK configurations for Android applications.

Startup configuration

Important

You can configure startup interfaces using method chaining with AlibabaCloudRum.withServiceId(serviceId).withWorkspace(workspace).withEndpoint(endpoint).start(getApplicationContext());.
You must call the startup configuration methods after the withServiceId method and before the start method.
You can configure multiple items at the same time. Any configurations made after the start method is called will be ignored.

Set the Endpoint address

Each application must be associated with a corresponding Endpoint address.

AlibabaCloudRum withEndpoint(String endpoint)

Parameter	Description	Limit	Result if failed
endpoint	Endpoint address	The string must be greater than 0 and less than 2,083 characters in length.	The API call fails and the SDK stops.

Set the workspace address

Each application must be associated with a corresponding workspace.

AlibabaCloudRum withWorkspace(String workspace)

Parameter	Description	Limit	Result if failed
workspace	Workspace	The string must be greater than 0 and less than 2,083 characters in length.	The API call fails and the SDK stops.

Set a custom device ID

You can set a custom device ID. After a custom ID is set, the SDK no longer uses the default device ID.

AlibabaCloudRum withDeviceID(String deviceID)

Parameter	Description	Limit	Result if failed
deviceID	Custom device ID	The string must be greater than 0 and less than 256 characters in length. It must not contain special characters. Only letters, digits, underscores (_), and hyphens (-) are supported.	The API call fails and the current setting is invalid.

Set a custom app version number

You can set a custom app version number. The SDK then reports this version number instead of the default version number.

AlibabaCloudRum withAppVersion(String appVersion)

Parameter	Description	Limit	Result if failed
appVersion	Custom app version number	The string must be greater than 0 and less than 64 characters in length.	The API call fails and the current setting is invalid.

Set a user channel ID

You can differentiate between the application's publishing channels.

AlibabaCloudRum withChannelID(String channelID)

Parameter	Description	Limit	Result if failed
channelID	Custom channel number	The string must be greater than 0 and less than 256 characters in length.	The API call fails and the current setting is invalid.

Set the application environment

You can set the application environment to distinguish between different environments, such as LOCAL, DAILY, and PROD.

AlibabaCloudRum withEnvironment(Env env)

Parameter

Description

Constraints

Result on failure

env

The enumeration value for the application environment. You must set this value after calling the withAppID method.

Env enumeration:

LOCAL: Local
DAILY: Daily
PRE: Pre-production
GRAY: Grayscale
PROD (default): Production
NONE: None

The API call fails. The setting is not applied.

Custom information

Set a custom username

The SDK lets you set user-related information to associate data analytics with actual users.

void setUserName(String userName)

Parameter

Description

Limit

Result if failed

userName

Username identity

The string can be null or empty.

The string can be null or empty. The string must be 256 characters or less and must not contain special characters. Only digits, letters, colons (:), spaces, forward slashes (/), underscores (_), hyphens (-), periods (.), and at signs (@) are allowed.

The API call fails and the current setting is invalid.

Set custom user extension information

The SDK lets you set user-related information to associate data analytics with actual users.

void setUserExtraInfo(Map<String, Object> extraInfo)

Parameter

Description

Limit

Result if failed

extraInfo

User extension information

The Map can be null or empty.

The converted JSON string must not exceed 7000 characters, or the API call will fail.

The API call fails and the current setting is invalid.

Set custom global properties

After you set custom global properties, newly generated data automatically includes these business properties. This helps you analyze data based on these properties.

void setExtraInfo(Map<String, Object> extraInfo)

void addExtraInfo(Map<String, Object> extraInfo)

Parameter	Description	Limit	Result if failed
extraInfo	Property information	The map can be null or empty. After being converted to JSON, the length must be 7,000 characters or less. Otherwise, the API call fails.	The API call fails and the current setting is invalid.

Note

The setExtraInfo method replaces all existing properties. To append new properties, use the addExtraInfo method.

Custom exceptions

You can call the custom exception API and pass the corresponding parameters to collect custom exception data.

void setCustomException(Throwable exception) // Recommended. Directly pass the Exception or Throwable object.

Parameter	Description	Limit	Result if failed
exception	Exception object	A system-thrown or self-constructed exception object. It cannot be null.	The API call fails and the current setting is invalid.

void setCustomException(String type, String causeBy, String errorDump)

Parameter	Description	Limit	Result if failed
type	Exception type (Required)	The string must be greater than 0 and 256 characters or less.	The API call fails and the current setting is invalid.
causeBy	Exception cause	The string can be null or empty. The string can be null or empty. The string must be 512 characters or less. Longer strings are truncated.	N/A
errorDump	Exception information	The string can be null or empty. The string can be null or empty. The string must be 10,000 characters or less. Longer strings are truncated.	N/A

Custom events

The SDK supports reporting custom events. You can call the corresponding API and pass the required parameters to collect custom event data.

void setCustomEvent(String eventName)

Parameter	Description	Limit	Result if failed
eventName	Event name (Required)	The string must be 512 characters or less. Longer strings are truncated.	The API call fails and the current setting is invalid.

void setCustomEvent(String eventName, String group)

Parameter

Description

Limit

Result if failed

eventName

Event name (Required)

The string must be 512 characters or less. Longer strings are truncated.

The API call fails and the current setting is invalid.

group

Event group

The string can be null or empty.

The string can be null or empty. The string must be 256 characters or less. Longer strings are truncated.

N/A

void setCustomEvent(String eventName, String group, String snapshots)

Parameter	Description	Limit	Result if failed
eventName	Event name (Required)	The string must be 512 characters or less. Longer strings are truncated.	The API call fails and the current setting is invalid.
group	Event group	The string can be null or empty. The string can be null or empty. The string must be 256 characters or less. Longer strings are truncated.	N/A
snapshots	Event snapshot	The string can be null or empty. The string can be null or empty. The string must be 7,000 characters or less. Longer strings are truncated.	N/A

void setCustomEvent(String eventName, String group, double value)

Parameter	Description	Limit	Result if failed
eventName	Event name (Required)	The string must be 512 characters or less. Longer strings are truncated.	The API call fails and the current setting is invalid.
group	Event group	The string can be null or empty. The string can be null or empty. The string must be 256 characters or less. Longer strings are truncated.	N/A
value	Event value	Double type	N/A

void setCustomEvent(String eventName, String group, Map<String, Object> attributes)

Parameter	Description	Limit	Result if failed
eventName	Event name (Required)	The string must be 512 characters or less. Longer strings are truncated.	The API call fails and the current setting is invalid.
group	Event group	The string can be null or empty. The string can be null or empty. The string must be 256 characters or less. Longer strings are truncated.	N/A
attributes	KV storage information	After being converted to JSON, the length must be 7,000 characters or less.	N/A

void setCustomEvent(String eventName, String group, String snapshots, double value)

Parameter	Description	Limit	Result if failed
eventName	Event name (Required)	The string must be 512 characters or less. Longer strings are truncated.	The API call fails and the current setting is invalid.
group	Event group	The string can be null or empty. The string can be null or empty. The string must be 256 characters or less. Longer strings are truncated.	N/A
snapshots	Event snapshot	The string can be null or empty. The string can be null or empty. The string must be 7,000 characters or less. Longer strings are truncated.	N/A
value	Event value	Double type	N/A

void setCustomEvent(String eventName, String group, String snapshots, Map<String, Object> attributes)

Parameter	Description	Limit	Result if failed
eventName	Event name (Required)	The string must be 512 characters or less. Longer strings are truncated.	The API call fails and the current setting is invalid.
group	Event group	The string can be null or empty. The string can be null or empty. The string must be 256 characters or less. Longer strings are truncated.	N/A
snapshots	Event snapshot	The string can be null or empty. The string can be null or empty. The string must be 7,000 characters or less. Longer strings are truncated.	N/A
attributes	KV storage information	After being converted to JSON, the length must be 7,000 characters or less.	N/A

void setCustomEvent(String eventName, String group, double value, Map<String, Object> attributes)

Parameter	Description	Limit	Result if failed
eventName	Event name (Required)	The string must be 512 characters or less. Longer strings are truncated.	The API call fails and the current setting is invalid.
group	Event group	The string can be null or empty. The string can be null or empty. The string must be 256 characters or less. Longer strings are truncated.	N/A
value	Event value	Double type	N/A
attributes	KV storage information	After being converted to JSON, the length must be 7,000 characters or less.	N/A

void setCustomEvent(String eventName, String group, String snapshots, double value, Map<String, Object> attributes)

Parameter	Description	Limit	Result if failed
eventName	Event name (Required)	The string must be 512 characters or less. Longer strings are truncated.	The API call fails and the current setting is invalid.
group	Event group	The string can be null or empty. The string can be null or empty. The string must be 256 characters or less. Longer strings are truncated.	N/A
snapshots	Event snapshot	The string can be null or empty. The string can be null or empty. The string must be 7,000 characters or less. Longer strings are truncated.	N/A
value	Event value	Double type	N/A
attributes	KV storage information	After being converted to JSON, the length must be 7,000 characters or less.	N/A

Custom logs

The SDK supports reporting custom log information. You can call the corresponding API and pass the required parameters to collect custom log data.

void setCustomLog(String content)

Parameter	Description	Limit	Result if failed
content	Log information (Required)	The string must be greater than 0 and 10,000 characters or less. Longer strings are truncated.	The API call fails and the current setting is invalid.

void setCustomLog(String content, String name)

Parameter	Description	Limit	Result if failed
content	Log information (Required)	The string must be greater than 0 and 10,000 characters or less. Longer strings are truncated.	The API call fails and the current setting is invalid.
name	Log name	The string must be greater than 0 and 256 characters or less.	N/A

void setCustomLog(String content, String name, String snapshots)

Parameter	Description	Limit	Result if failed
content	Log information (Required)	The string must be greater than 0 and 10,000 characters or less. Longer strings are truncated.	The API call fails and the current setting is invalid.
name	Log name	The string must be greater than 0 and 256 characters or less.	N/A
snapshots	Log snapshot	The string can be null or empty. The string can be null or empty. The string must be 7,000 characters or less. Longer strings are truncated.	N/A

void setCustomLog(String content, String name, String snapshots, String level, Map<String, Object> attributes)

Parameter	Description	Constraints	Result on failure
content	The log content. This parameter is required.	The string must contain 1 to 10,000 characters. Longer strings are truncated.	If the API call fails, the settings for the call are not applied.
name	The log name.	The string must contain 1 to 256 characters.	Not applicable.
snapshots	The log snapshot.	The string can be null or empty. The string must not exceed 7,000 characters. Longer strings are truncated.	Not applicable.
level	The log level.	The string must contain 1 to 256 characters. The default value is INFO.	Not applicable.
info	Additional log information.	The map can be null or empty. This map is converted to a JSON string. The combined length of this string and the `content` string is subject to a shared limit. If this limit is exceeded, the API call fails.	Not applicable.