Android SDK configuration reference - Application Real-Time Monitoring Service

This topic provides the API reference for the Android SDK of Real User Monitoring (RUM), covering startup configuration, custom information reporting, and Session Replay.

Startup configuration

Configure startup options by chaining methods between withServiceId and start. Options configured after start do not take effect.

The following example shows a complete initialization call with all required parameters:

AlibabaCloudRum
    .withServiceId(serviceId)
    .withWorkspace(workspace)
    .withEndpoint(endpoint)
    .start(getApplicationContext());

You can insert additional configuration methods (such as withDeviceID or withAppVersion) into the chain before start. Multiple options can be configured simultaneously.

The setSelfMonitor method is a standalone call that does not participate in the builder chain. You can call it at any time after start.

Set endpoint

Associates the application with a corresponding endpoint address.

AlibabaCloudRum withEndpoint(String endpoint)

Parameter	Description	Constraint	Failure result
endpoint	Endpoint address	String length must be greater than 0 and less than 2083	API call fails and the SDK stops

Set workspace

Associates the application with a corresponding workspace.

AlibabaCloudRum withWorkspace(String workspace)

Parameter	Description	Constraint	Failure result
workspace	Workspace	String length must be greater than 0 and less than 2083	API call fails and the SDK stops

Set custom device ID

Sets a custom device ID. After a successful call, the SDK no longer uses the default device ID.

AlibabaCloudRum withDeviceID(String deviceID)

Parameter	Description	Constraint	Failure result
deviceID	Custom device ID	String length must be greater than 0 and less than 256. Only letters, digits, underscores (`_`), and hyphens (`-`) are allowed.	API call fails and the current setting does not take effect

Set custom app version

Sets a custom app version number. After a successful call, the SDK reports this version number and no longer uses the default version number.

AlibabaCloudRum withAppVersion(String appVersion)

Parameter	Description	Constraint	Failure result
appVersion	Custom app version number	String length must be greater than 0 and less than 64	API call fails and the current setting does not take effect

Set user channel ID

Distinguishes the channel through which the application is distributed.

AlibabaCloudRum withChannelID(String channelID)

Parameter	Description	Constraint	Failure result
channelID	Custom channel ID	String length must be greater than 0 and less than 256	API call fails and the current setting does not take effect

Set app environment

Specifies the app environment, such as LOCAL, DAILY, or PROD.

AlibabaCloudRum withEnvironment(Env env)

Parameter	Description	Constraint	Failure result
env	Enum value for the app environment. Must be called after the `withServiceId` method.	`Env` enum; default is `PROD`: `LOCAL` (local), `DAILY` (daily), `PRE` (pre-release), `GRAY` (canary), `PROD` (production), `NONE` (none)	API call fails and the current setting does not take effect

Enable or disable self-monitoring

The SDK collects self-monitoring data to continuously improve SDK performance and experience. Self-monitoring is enabled by default. Use this method to disable or re-enable this feature.

This method is a standalone call that returns void. It is not part of the builder chain. Call it after start.

void setSelfMonitor(boolean enabled)

Parameter	Description	Constraint	Failure result
enabled	Enables or disables SDK self-monitoring data collection	Must be a boolean value	The current setting does not take effect

Collection configuration

ARMS lets you configure data collection items for your Android application in the console. Log on to the ARMS console, choose User Experience Monitoring > Application List in the left-side navigation pane, click the name of the target Android application, and then go to App Settings > Collection Configuration.

The Collection Configuration tab includes the following configuration areas:

Session configuration: the session sampling rate, expressed as a percentage. The default value is 100%.
Tracing Analysis: a switch that turns the tracing feature on or off.
Feature configuration: includes a global collection switch and the following collector categories:
- Behavior events: collects user actions such as taps, swipes, and text input. Supports a sampling rate.
- Network requests: monitors API latency, success rate, and failure causes. Supports a sampling rate.
- Exceptions: captures crashes, ANRs, freezes (janks), and out-of-memory (OOM) errors. This is a core capability; keep it enabled. Supports a sampling rate.
- Page monitoring: collects page load performance and PV/UV data. Includes three sub-items — native views, WebView pages, and single pages — each of which can be individually enabled or disabled and configured with its own sampling rate.
- Custom reporting: supports custom events, logs, and metrics. Supports a sampling rate.

Each collection item can be individually enabled or disabled by selecting its check box, and you can configure a sampling rate (as a percentage) for each item.

Note

Session tracking is automatically generated based on reported data and cannot be disabled separately. You can control it only by adjusting the session sampling rate. The Android SDK does not support a collectors parameter. You can control collection items only through the console.

Custom information

Set custom username

Sets a username to associate data analytics with actual users.

void setUserName(String userName)

Parameter	Description	Constraint	Failure result
userName	Username identifier	Can be null or an empty string. Must be less than or equal to 256 characters. Only digits, letters, colons, spaces, slashes, underscores, hyphens, periods, and `@` are allowed.	API call fails and the current setting does not take effect

Set custom user extended info

Sets user-related extended information to associate data analytics with actual users.

void setUserExtraInfo(Map<String, Object> extraInfo)

Parameter	Description	Constraint	Failure result
extraInfo	User extended information	The map can be null or empty. The JSON-serialized length must be within 7000 characters.	API call fails and the current setting does not take effect

Set custom global attributes

Sets custom global business attributes. After global attributes are set, newly generated data automatically carries these attributes, enabling data analytics to be associated with business attributes.

void setExtraInfo(Map<String, Object> extraInfo)

void addExtraInfo(Map<String, Object> extraInfo)

Parameter	Description	Constraint	Failure result
extraInfo	Attribute information	The map can be null or empty. The JSON-serialized length must be within 7000 characters.	API call fails and the current setting does not take effect

Calling setExtraInfo clears all previously set attribute information. To append new attributes, use addExtraInfo instead.

Set custom exception

Reports custom exception data by passing an exception object or explicit error fields.

Method signatures:

void setCustomException(Throwable exception)

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

The first overload is recommended. Pass an Exception or Throwable object directly.

Parameters (Throwable overload):

Parameter	Description	Constraint	Failure result
exception	Exception object	A system-thrown or manually constructed exception object; must not be null	API call fails and the current setting does not take effect

Parameters (String overload):

Parameter	Description	Constraint	Failure result
type	Exception type (required)	String length must be greater than 0 and less than or equal to 256	API call fails and the current setting does not take effect
causeBy	Exception cause	Can be null or an empty string. Must be less than or equal to 512 characters; excess is truncated.	—
errorDump	Exception details	Can be null or an empty string. Must be less than or equal to 10000 characters; excess is truncated.	—

Set custom event

Reports custom events. Use the overload that matches the data you need to include.

Parameters:

Parameter	Required	Description	Constraint	Failure result
eventName	Yes	Event name	Must be less than or equal to 512 characters; excess is truncated.	API call fails and the current setting does not take effect
group	No	Event group	Can be null or an empty string. Must be less than or equal to 256 characters; excess is truncated.	—
snapshots	No	Event snapshot	Can be null or an empty string. Must be less than or equal to 7000 characters; excess is truncated.	—
value	No	Event value	double type	—
attributes	No	Key-value attributes	JSON-serialized length must be within 7000 characters.	—

Method signatures:

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

Set custom log

Reports custom log information. Use the overload that matches the data you need to include.

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

Parameters:

Parameter	Required	Description	Constraint	Failure result
content	Yes	Log content	String length must be greater than 0 and less than or equal to 10000 characters; excess is truncated.	API call fails and the current setting does not take effect
name	No	Log name	String length must be greater than 0 and less than or equal to 256	—
snapshots	No	Log snapshot	Can be null or an empty string. Must be less than or equal to 7000 characters; excess is truncated.	—
level	No	Log level	String length must be greater than 0 and less than or equal to 256; default is `INFO`	—
attributes	No	Log supplementary information	The map can be null or empty. The JSON-serialized length must be within 7000 characters.	—

Report custom resource

Reports custom network resource request data, recording detailed information for HTTP/HTTPS requests, including request status, performance metrics, and Tracing Analysis information.

void reportCustomResource(String type, String url, String method, int statusCode, String errorMessage, boolean success, String provider, TraceContext traceContext, Measuring measuring)

Parameter	Type	Description	Constraint	Failure result
type	String	Resource type, such as `"js"`, `"media"`, or `"api"`	String length must be greater than 0	API call fails and the current setting does not take effect
url	String	Full URL of the request	String length must be greater than 0
method	String	HTTP request method	String length must be greater than 0 and less than or equal to 24 characters; excess is truncated.
statusCode	int	HTTP response status code	HTTP status code, such as 200, 404, or 500
errorMessage	String	Error message when the request fails	Can be `null`
success	boolean	Whether the request succeeded	`true` or `false`
provider	String	Service provider identifier, such as `"CDN"`	String length must be greater than 0 and less than or equal to 128 characters; excess is truncated. Can be `null`.
traceContext	TraceContext	Tracing Analysis context	`TraceContext` type; can be `null`
measuring	Measuring	Resource request performance metrics	`Measuring` type; can be `null`

TraceContext class

Use this class to set trace data.

Parameter	Type	Description
traceId	String	Custom trace ID. You can use `TraceIdGenerator.generateTraceId(TraceProtocol traceProtocol)` to generate one.
spanId	String	Custom span ID. You can use `TraceIdGenerator.generateSpanId(TraceProtocol traceProtocol)` to generate one.
traceProtocol	TraceProtocol	Protocol: `TraceProtocol.W3C` or `TraceProtocol.SKYWALKING`

Measuring class

Performance metric data.

Parameter	Type	Description
duration	long	Total resource load time, in milliseconds
size	long	Resource size, in bytes
connectDuration	long	Time to establish a connection to the server, in milliseconds
sslDuration	long	TLS handshake duration, in milliseconds
dnsDuration	long	DNS resolution duration, in milliseconds
redirectDuration	long	Redirect duration, in milliseconds
firstByteDuration	long	Time to first byte, in milliseconds
downloadDuration	long	Response download duration, in milliseconds

Example:

// (Optional) Generate W3C trace protocol information
String traceId = TraceIdGenerator.generateTraceId(TraceProtocol.W3C);
String spanId = TraceIdGenerator.generateSpanId(TraceProtocol.W3C);

// (Optional) Store the traceId and spanId in a TraceContext object
TraceContext traceContext = new TraceContext(traceId, spanId, TraceProtocol.W3C);

// (Optional) Write trace information to request headers (OkHttp example)
TraceHeaderWriter.setTraceHeaders(okhttp3.Request.Builder requestBuilder, TraceContext traceContext);

// (Optional) Record performance metrics
Measuring measuring = new Measuring(200, 100, 30, 10, 10, 0, 145, 2);

// Report custom resource
AlibabaCloudRum.reportCustomResource("api", "https://example.com/xx", "GET", 200, "", true, "cdn", traceContext, measuring);

Session Replay

Start Session Replay

Starts Session Replay recording with default configurations.

void startSessionReplay()

Before you call this method, make sure that the Alibaba Cloud RUM SDK is started and an Application is used as the SDK Context. The SDK applies maximum privacy protection and a 100% Session Replay sampling rate by default. If the prerequisites are not met, recording does not start.

Start Session Replay with custom configuration

Starts Session Replay recording with a custom configuration.

void startSessionReplay(SessionReplayConfiguration config)

Parameter	Type	Required	Description
config	`SessionReplayConfiguration`	No	Session Replay configuration object. If you do not pass this parameter or pass `null`, the call is equivalent to the no-argument `startSessionReplay()`.

The prerequisites are the same as those for the no-argument startSessionReplay().

Example:

AlibabaCloudRum.startSessionReplay(
    new SessionReplayConfiguration.Builder()
        .privacy(SessionReplayPrivacy.MASK)
        .sampleRate(20)
        .build()
);

Configuration parameters

SessionReplayConfiguration configures the privacy protection, sampling strategy, and image processing performance parameters of Session Replay. Configuration items that are not explicitly set use their default values.

privacy

Sets the overall privacy protection level of Session Replay.

Builder privacy(SessionReplayPrivacy privacy)

The privacy parameter must not be null. Valid values:

Enum value	Description
`ALLOW`	Minimal privacy protection. Masks only sensitive input identified through Android `InputType` in `EditText` and its subclasses. Does not mask images, and shows touch trails. Use this value only after you complete a privacy and compliance assessment.
`MASK_USER_INPUT`	Medium privacy protection. Masks all user input. Masks only large images, and hides touch trails.
`MASK`	Maximum privacy protection. Masks all text and images, and hides touch trails. This is the default value.

In ALLOW mode, the SDK identifies the following sensitive input types:

Phone input: InputType.TYPE_CLASS_PHONE
Email input: InputType.TYPE_TEXT_VARIATION_EMAIL_ADDRESS, InputType.TYPE_TEXT_VARIATION_WEB_EMAIL_ADDRESS
Postal address: InputType.TYPE_TEXT_VARIATION_POSTAL_ADDRESS
Password input: InputType.TYPE_TEXT_VARIATION_PASSWORD, InputType.TYPE_TEXT_VARIATION_VISIBLE_PASSWORD, InputType.TYPE_TEXT_VARIATION_WEB_PASSWORD, InputType.TYPE_NUMBER_VARIATION_PASSWORD

sampleRate

Sets the Session Replay sampling rate.

Builder sampleRate(int sampleRate)

Parameter	Unit	Valid values	Default	Description
sampleRate	Percentage	Integer `0–100` only	`100`	Controls the percentage of sessions to record. `0` records no sessions, and `100` records all sessions.

Example:

.sampleRate(20) // Record 20% of sessions

Default configurations

Retrieves the default Session Replay configuration.

SessionReplayConfiguration getDefault()

Default values:

Configuration item	Function	Unit	Valid values	Default
privacy	Controls the privacy protection policy for text, images, and touch trails	N/A	`ALLOW`, `MASK_USER_INPUT`, `MASK`	`SessionReplayPrivacy.MASK`
sampleRate	Controls the percentage of sessions to record	Percentage	Integer `0–100` only	`100`

Stop Session Replay

Stops Session Replay recording and cleans up related resources.

void stopSessionReplay()

If Session Replay or the SDK has not been started, or the SDK has already stopped, this call performs no action.