AI 助理
文档备案控制台
官方文档
首页 云监控 云监控2.0 接入中心 终端应用 Android应用监控 SDK配置参考

SDK配置参考

更新时间：
复制 MD 格式
产品详情
我的收藏

用户体验监控提供了一系列SDK配置项，让您能够通过设置参数来满足额外需求。本文介绍Android应用常用的SDK配置。

启动配置

启动配置类的接口，通过链式调用方式随AlibabaCloudRum.withServiceId(serviceId).withWorkspace(workspace).withEndpoint(endpoint).start(getApplicationContext());一同配置，需要在调用start函数之前，withServiceId之后进行相关配置。可同时配置多项，start函数之后配置无效。

设置Endpoint地址

每个应用都需要关联对应的Endpoint地址。

AlibabaCloudRum withEndpoint(String endpoint)

参数

说明

参数限制

失败结果

endpoint

Endpoint 地址

字符串长度大于0且小于2083

接口调用失败，SDK停止

设置 Workspace 地址

每个应用都需要关联对应的Workspace。

AlibabaCloudRum withWorkspace(String workspace)

参数

说明

参数限制

失败结果

workspace

工作空间

字符串长度大于0且小于2083

接口调用失败，SDK停止

设置自定义设备ID

可以通过此方法设置自定义设备ID，设置成功后，SDK将不再使用默认获取的设备ID。

AlibabaCloudRum withDeviceID(String deviceID)

参数

说明

参数限制

失败结果

deviceID

自定义的设备ID

字符串长度大于0且小于256，且不包含特殊字符，仅支持字母、数字、下划线（_）和英文半角连接号（-）。

接口调用失败，当次设置无效。

设置自定义App版本号

通过此方法设置了自定义App版本号，那么SDK将会上报此版本号，不再使用默认获取的版本号。

AlibabaCloudRum withAppVersion(String appVersion)

参数

说明

参数限制

失败结果

appVersion

自定义的App版本号

字符串长度大于0且小于64。

接口调用失败，当次设置无效。

设置用户渠道ID

区分应用发布的渠道。

AlibabaCloudRum withChannelID(String channelID)

参数

说明

参数限制

失败结果

channelID

自定义的渠道号

字符串长度大于0且小于256。

接口调用失败，当次设置无效。

设置应用环境

区分应用的环境。通过此方法可以指定应用的环境，如LOCAL、DAILY、PROD等。

AlibabaCloudRum withEnvironment(Env env)

参数

说明

参数限制

失败结果

env

应用环境的枚举值。需要在withAppID方法之后调用。

Env枚举：

  • LOCAL：本地

  • DAILY：日常

  • PRE：预发

  • GRAY：灰度

  • PROD（默认）：线上

  • NONE：无

接口调用失败，当次设置无效。

禁用/开启自监控采集

SDK 会采集自身监控数据，用于持续提升 SDK 性能和体验。SDK 默认采集自身监控数据，您需要通过此开关关闭或开启该能力。

void setSelfMonitor(boolean enabled)

参数

说明

参数限制

失败结果

enabled

禁用/开启 SDK 自身监控数据采集。

需要为 boolean 类型

当次设置无效。

采集配置

ARMS 控制台支持对 Android 应用的采集项进行配置。登录 ARMS 控制台，在左侧导航栏选择用户体验监控 > 应用列表，单击目标 Android 应用名称，在应用详情页选择应用设置 > 采集配置页签。

采集配置页面包含以下配置区域：

  • 会话配置：会话采样率，使用百分号表示，默认 100%。

  • 链路追踪：开关控制，可开启或关闭链路追踪功能。

  • 功能配置：包含采集总开关和以下采集器类别：

    • 行为事件：采集用户点击、滑动、输入等操作行为。包含采样率配置。

    • 网络请求：监控接口耗时、成功率和失败原因。包含采样率配置。

    • 异常问题：捕获崩溃、ANR、卡顿、内存溢出等异常，为核心能力，推荐保持开启。包含采样率配置。

    • 页面监控：采集页面加载性能和 PV/UV，包含原生视图、WebView 页面、单页面三个子项，可分别开关并设置采样率。

    • 自定义上报：支持自定义事件、日志和指标上报。包含采样率配置。

每个采集项均可通过复选框开关，并可配置采样率百分比。

说明

会话追踪（Session）基于上报数据自动生成，无法单独关闭，仅支持通过会话采样率控制。Android SDK 不支持 SDK 级别 collectors 参数，采集项控制仅通过控制台实现。

自定义信息

自定义用户名称

SDK支持设置与用户相关的信息，从而完成数据分析与实际用户相关联的需求场景。

void setUserName(String userName)

参数

说明

参数限制

失败结果

userName

用户名称标识

字符串可为null或空串。

字符串小于等于256，且不包含特殊字符，只允许数字、字母、英文半角冒号（:）、空格、正斜线（/）、下划线（_）、英文半角连接号（-）、英文半角句号（.）和@。

接口调用失败，当次设置无效。

自定义用户扩展信息

SDK支持设置与用户相关的信息，从而完成数据分析与实际用户相关联的需求场景。

void setUserExtraInfo(Map<String, Object> extraInfo)

参数

说明

参数限制

失败结果

extraInfo

用户扩展信息

Map可为空或空集。

转JSON后长度在7000字符以内，否则接口调用失败。

接口调用失败，当次设置无效。

自定义全局属性

SDK支持设置自定义全局业务属性。自定义全局属性设置后，新产生的数据会自动携带该业务属性信息，可以完成数据分析与业务属性相关联的需求场景。

void setExtraInfo(Map<String, Object> extraInfo)

void addExtraInfo(Map<String, Object> extraInfo)

参数

说明

参数限制

失败结果

extraInfo

属性信息

Map可为空或空集。转JSON后长度在7000字符以内，否则接口调用失败。

接口调用失败，当次设置无效。

说明

调用 setExtraInfo 方法时会清空历史设置的属性信息。如您需要追加新的属性信息，建议您通过 addExtraInfo 方法。

自定义异常

调用自定义异常接口，并传入相应的参数，可完成自定义异常数据的统计功能。

void setCustomException(Throwable exception) // 推荐使用，直接将Exception或Throwable对象传入即可

参数

说明

参数限制

失败结果

exception

异常对象

系统抛出或自行构造的异常对象，非null。

接口调用失败，当次设置无效。

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

参数

说明

参数限制

失败结果

type

异常类型（必要）

字符串长度大于0且小于等于256。

接口调用失败，当次设置无效。

causeBy

异常原因

字符串可为null或空串。

字符串小于等于512，超长会截取。

不涉及

errorDump

异常信息

字符串可为null或空串。

字符串小于等于10000，超长会截取。

不涉及

自定义事件

SDK支持上报自定义事件。调用相应的接口，并传入相应的参数，可完成自定义事件数据的统计功能。

void setCustomEvent(String eventName)

参数

说明

参数限制

失败结果

eventName

事件名称（必要）

字符串小于等于512，超长会截取。

接口调用失败，当次设置无效。

void setCustomEvent(String eventName, String group)

参数

说明

参数限制

失败结果

eventName

事件名称（必要）

字符串小于等于512，超长会截取。

接口调用失败，当次设置无效。

group

事件分组

字符串可为null或空串。

字符串小于等于256，超长会截取。

不涉及

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

参数

说明

参数限制

失败结果

eventName

事件名称（必要）

字符串小于等于512，超长会截取。

接口调用失败，当次设置无效。

group

事件分组

字符串可为null或空串。

字符串小于等于256，超长会截取。

不涉及

snapshots

事件快照

字符串可为null或空串。

字符串小于等于7000，超长会截取。

不涉及

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

参数

说明

参数限制

失败结果

eventName

事件名称（必要）

字符串小于等于512，超长会截取。

接口调用失败，当次设置无效。

group

事件分组

字符串可为null或空串。

字符串小于等于256，超长会截取。

不涉及

value

事件值

Double类型

不涉及

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

参数

说明

参数限制

失败结果

eventName

事件名称（必要）

字符串小于等于512，超长会截取。

接口调用失败，当次设置无效。

group

事件分组

字符串可为null或空串。

字符串小于等于256，超长会截取。

不涉及

attributes

KV存储信息

转JSON后长度在7000字符以内。

不涉及

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

参数

说明

参数限制

失败结果

eventName

事件名称（必要）

字符串小于等于512，超长会截取。

接口调用失败，当次设置无效。

group

事件分组

字符串可为null或空串。

字符串小于等于256，超长会截取。

不涉及

snapshots

事件快照

字符串可为null或空串。

字符串小于等于7000，超长截取。

不涉及

value

事件值

Double类型

不涉及

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

参数

说明

参数限制

失败结果

eventName

事件名称（必要）

字符串小于等于512，超长会截取。

接口调用失败，当次设置无效。

group

事件分组

字符串可为null或空串。

字符串小于等于256，超长会截取。

不涉及

snapshots

事件快照

字符串可为null或空串。

字符串小于等于7000，超长截取。

不涉及

attributes

KV存储信息

转JSON后长度在7000字符以内。

不涉及

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

参数

说明

参数限制

失败结果

eventName

事件名称（必要）

字符串小于等于512，超长会截取。

接口调用失败，当次设置无效

group

事件分组

字符串可为null或空串。

字符串小于等于256，超长会截取。

不涉及

value

事件值

Double类型

不涉及

attributes

KV存储信息

转JSON后长度在7000字符以内。

不涉及

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

参数

说明

参数限制

失败结果

eventName

事件名称（必要）

字符串小于等于512，超长会截取。

接口调用失败，当次设置无效。

group

事件分组

字符串可为null或空串。

字符串小于等于256，超长会截取。

不涉及

snapshots

事件快照

字符串可为null或空串。

字符串小于等于7000，超长截取。

不涉及

value

事件值

Double类型

不涉及

attributes

KV存储信息

转JSON后长度在7000字符以内。

不涉及

自定义日志

SDK支持上报自定义日志信息。调用相应的接口，并传入相应的参数，可完成自定义日志数据的统计功能。

void setCustomLog(String content)

参数

说明

参数限制

失败结果

content

日志信息（必要）

字符串长度大于0且小于等于10000，超长会被截取。

接口调用失败，当次设置无效。

void setCustomLog(String content, String name)

参数

说明

参数限制

失败结果

content

日志信息（必要）

字符串长度大于0且小于等于10000，超长会被截取。

接口调用失败，当次设置无效。

name

日志名称

字符串长度大于0且小于等于256。

不涉及

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

参数

说明

参数限制

失败结果

content

日志信息（必要）

字符串长度大于0且小于等于10000，超长会被截取。

接口调用失败，当次设置无效。

name

日志名称

字符串长度大于0且小于等于256。

不涉及

snapshots

日志快照

字符串可为null或空串。

字符串小于等于7000，超长会截取。

不涉及

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

参数

说明

参数限制

失败结果

content

日志信息（必要）

字符串长度大于0且小于等于10000，超长会被截取。

接口调用失败，当次设置无效。

name

日志名称

字符串长度大于0且小于等于256。

不涉及

snapshots

日志快照

字符串可为null或空串。

字符串小于等于7000，超长会截取。

不涉及

level

日志等级

字符串长度大于0且小于等于256，默认为INFO。

不涉及

info

日志附加信息

Map可为空或空集。

转JSON后，字符串长度与content共享，否则接口调用失败。

不涉及

自定义资源

SDK支持上报自定义网络资源请求数据，可以记录 HTTP/HTTPS 等类型请求的详细信息，包括请求状态、性能指标和链路追踪信息。

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

参数

类型

说明

参数限制

失败结果

type

String

资源类型，例如："js"、"media"、"api" 等

字符串长度大于0

接口调用失败，当次设置无效

url

String

请求的完整 URL 地址

字符串长度大于0

method

String

HTTP 请求方法

字符串长度大于0且小于等于24，超长截取。

statusCode

int

HTTP 响应状态码

HTTP 状态码，如：200、404、500等。

errorMessage

String

请求失败报错信息

可为null

success

boolean

请求是否成功

true、false

provider

String

服务提供商标识，如："CDN"

字符串长度大于0且小于等于128，超长截取。可为 null 。

traceContext

TraceContext

链路打通信息

TraceContext类型，可为 null 。

measuring

Measuring

资源请求性能信息

Measuring类型，可为 null 。

TraceContext 类

用户可设置trace数据

参数

类型

说明

traceId

String

自定义traceId，可以使用 TraceIdGenerator.generateTraceId(TraceProtocol traceProtocol) 方法生成

spanId

String

自定义spanId，可以使用 TraceIdGenerator.generateSpanId(TraceProtocol traceProtocol) 方法生成

traceProtocol

TraceProtocol

协议，TraceProtocol.W3C 或 TraceProtocol.SKYWALKING

Measuring 类

指标数据

参数

类型

说明

duration

long

资源加载的全部耗时，单位ms

size

long

资源大小，单位Byte

connectDuration

long

与服务器建连耗时，单位ms

sslDuration

long

TLS握手耗时，单位ms

dnsDuration

long

DNS解析耗时，单位ms

redirectDuration

long

重定向耗时，单位ms

firstByteDuration

long

首包耗时，单位ms

downloadDuration

long

下载响应耗时，单位ms

使用示例：

// (可选) SDK 当前支持 W3C 和 SkyWalking trace协议的自定义，以下为生成 W3C trace 协议信息的示例：
String traceId = TraceIdGenerator.generateTraceId(TraceProtocol.W3C);
String spanId = TraceIdGenerator.generateSpanId(TraceProtocol.W3C);

// (可选) 您需要手动把 traceId 和 spanId 存入到 TraceContext 中，便于后续处理。
TraceContext traceContext = new TraceContext(traceId, spanId, TraceProtocol.W3C);

// (可选) 支持将生成的trace信息写入请求头，支持 OkHttp、HttpURLConnection，以OkHttp为例：
TraceHeaderWriter.setTraceHeaders(okhttp3.Request.Builder requestBuilder , TraceContext traceContext);

// (可选) 记录指标数据
Measuring measuring = new Measuring(200, 100, 30, 10, 10, 0, 145, 2);

// 上报自定义资源
AlibabaCloudRum.reportCustomResource("api", "https://example.com/xx", "GET", 200, "", true, "cdn", traceContext, measuring);

Session Replay功能

启动 Session Replay

使用默认配置启动 Session Replay 录制。

void startSessionReplay()

调用前请确保 Alibaba Cloud RUM SDK 已启动，并使用 Application 作为 SDK Context。SDK 默认采用最大隐私保护和 100% Session Replay 采样率；不满足启动条件时，不会开始录制。

启动 Session Replay（自定义配置）

启动 Session Replay 录制，并传入 Session Replay 配置。

void startSessionReplay(SessionReplayConfiguration config)

参数

类型

是否必填

说明

config

SessionReplayConfiguration

否

Session Replay 配置对象。不传或传入 null 时，等同于调用无参 startSessionReplay()。

启动条件与无参 startSessionReplay() 相同。

示例：

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

配置参数说明

SessionReplayConfiguration 用于配置 Session Replay 的隐私保护、采样策略和图片处理性能参数。未显式设置的配置项使用默认值。

privacy

设置 Session Replay 的总体隐私保护级别。

Builder privacy(SessionReplayPrivacy privacy)

参数

说明

参数限制

失败结果

privacy

Session Replay 的总体隐私保护级别

privacy 不得为 null；可选 ALLOW、MASK_USER_INPUT、MASK

参数非法时接口调用失败

可选值：

枚举值

说明

ALLOW

最小隐私保护。仅掩盖 EditText 及其子类中通过 Android InputType 标识的敏感输入；不掩盖图片，并显示触摸轨迹。请仅在完成隐私与合规评估后使用。

MASK_USER_INPUT

中等隐私保护。掩盖所有用户输入内容；仅掩盖大尺寸图片，并隐藏触摸轨迹。

MASK

最大隐私保护。掩盖所有文本和图片，并隐藏触摸轨迹。该值为默认值。

在 ALLOW 模式下，SDK 识别以下敏感输入类型：

  • 电话输入：InputType.TYPE_CLASS_PHONE

  • 邮箱输入：InputType.TYPE_TEXT_VARIATION_EMAIL_ADDRESS、InputType.TYPE_TEXT_VARIATION_WEB_EMAIL_ADDRESS

  • 邮政地址：InputType.TYPE_TEXT_VARIATION_POSTAL_ADDRESS

  • 密码输入：InputType.TYPE_TEXT_VARIATION_PASSWORD、InputType.TYPE_TEXT_VARIATION_VISIBLE_PASSWORD、InputType.TYPE_TEXT_VARIATION_WEB_PASSWORD、InputType.TYPE_NUMBER_VARIATION_PASSWORD

sampleRate

设置 Session Replay 采样率。

Builder sampleRate(int sampleRate)

参数

单位

取值范围

默认值

说明

sampleRate

百分比

严格限制为整数 0-100

100

控制录制的 Session 比例。0 表示不录制，100 表示全部录制。

示例：

.sampleRate(20) // 录制 20% 的 Session

默认配置

获取默认 Session Replay 配置。

SessionReplayConfiguration getDefault()

默认值：

配置项

功能

单位

取值范围

默认值

privacy

控制文本、图片和触摸轨迹的隐私保护策略

无

ALLOW、MASK_USER_INPUT、MASK

SessionReplayPrivacy.MASK

sampleRate

控制录制的 Session 比例

百分比

严格限制为整数 0-100

100

停止 Session Replay

停止 Session Replay 录制并清理相关资源。

void stopSessionReplay()

如果 Session Replay 或 SDK 未启动，或者 SDK 已停止，本次调用不执行任何操作。

上一篇：接入Android应用下一篇：SDK版本说明