高级配置

概述

FlashCat Android RUM SDK 提供多种高级配置选项,允许您根据需求修改收集的数据和上下文,支持以下场景:

• 丰富用户会话:添加自定义视图、操作、资源和错误信息
• 保护敏感数据:屏蔽个人身份信息等敏感数据
• 关联用户会话:将用户会话与内部用户标识关联,便于支持和问题排查
• 控制数据量:通过采样和事件过滤优化数据收集
• 增强上下文:为数据添加比默认属性更丰富的上下文信息

丰富用户会话

自定义视图

当使用 ActivityViewTrackingStrategy 或 FragmentViewTrackingStrategy 时,RUM SDK 会自动追踪视图。您也可以在视图变为可见或可交互时手动发送自定义 RUM 视图:

import cloud.flashcat.android.rum.GlobalRum

fun onResume() {
    GlobalRum.get().startView(viewKey, viewName, attributes)
}

fun onPause() {
    GlobalRum.get().stopView(viewKey, attributes)
}

import cloud.flashcat.android.rum.GlobalRum;

public void onResume() {
    GlobalRum.get().startView(viewKey, viewName, attributes);
}

public void onPause() {
    GlobalRum.get().stopView(viewKey, attributes);
}

参数说明:

• viewKey (String): 视图的唯一标识符。同一个 viewKey 用于调用 startView() 和 stopView()
• viewName (String): 视图的名称
• attributes (Map<String, Any?>): 附加到视图的属性,可选

自定义操作

除了自动追踪的用户交互,您还可以追踪特定的自定义用户操作(如点击、滑动、点赞):

import cloud.flashcat.android.rum.GlobalRum
import cloud.flashcat.android.rum.RumActionType

fun onUserInteraction() {
    GlobalRum.get().addAction(
        RumActionType.TAP,
        name,
        attributes
    )
}

import cloud.flashcat.android.rum.GlobalRum;
import cloud.flashcat.android.rum.RumActionType;

public void onUserInteraction() {
    GlobalRum.get().addAction(
        RumActionType.TAP,
        name,
        attributes
    );
}

RumActionType 可选值:

• RumActionType.TAP: 点击操作
• RumActionType.SCROLL: 滚动操作
• RumActionType.SWIPE: 滑动操作
• RumActionType.CLICK: 单击操作
• RumActionType.CUSTOM: 自定义操作

自定义资源

除了自动追踪的资源,您还可以手动追踪特定的自定义资源(如网络请求、第三方库加载):

import cloud.flashcat.android.rum.GlobalRum
import cloud.flashcat.android.rum.RumResourceKind

fun loadResource() {
    GlobalRum.get().startResource(
        resourceKey,
        method,
        url,
        attributes
    )
}

fun resourceLoadSuccess() {
    GlobalRum.get().stopResource(
        resourceKey,
        statusCode,
        size,
        RumResourceKind.NATIVE,
        attributes
    )
}

fun resourceLoadError() {
    GlobalRum.get().stopResourceWithError(
        resourceKey,
        statusCode,
        message,
        source,
        throwable
    )
}

import cloud.flashcat.android.rum.GlobalRum;
import cloud.flashcat.android.rum.RumResourceKind;

public void loadResource() {
    GlobalRum.get().startResource(
        resourceKey,
        method,
        url,
        attributes
    );
}

public void resourceLoadSuccess() {
    GlobalRum.get().stopResource(
        resourceKey,
        statusCode,
        size,
        RumResourceKind.NATIVE,
        attributes
    );
}

public void resourceLoadError() {
    GlobalRum.get().stopResourceWithError(
        resourceKey,
        statusCode,
        message,
        source,
        throwable
    );
}

RumResourceKind 可选值:

• RumResourceKind.BEACON: 信标请求
• RumResourceKind.FETCH: Fetch 请求
• RumResourceKind.XHR: XHR 请求
• RumResourceKind.DOCUMENT: 文档资源
• RumResourceKind.IMAGE: 图片资源
• RumResourceKind.JS: JavaScript 资源
• RumResourceKind.FONT: 字体资源
• RumResourceKind.CSS: CSS 资源
• RumResourceKind.MEDIA: 媒体资源
• RumResourceKind.OTHER: 其他资源
• RumResourceKind.NATIVE: 原生资源

自定义错误

要记录特定错误,当异常发生时通知 RUM SDK:

import cloud.flashcat.android.rum.GlobalRum

GlobalRum.get().addError(
    message,
    source,
    throwable,
    attributes
)

import cloud.flashcat.android.rum.GlobalRum;

GlobalRum.get().addError(
    message,
    source,
    throwable,
    attributes
);

RumErrorSource 可选值:

• RumErrorSource.NETWORK: 网络错误
• RumErrorSource.SOURCE: 源码错误
• RumErrorSource.CONSOLE: 控制台错误
• RumErrorSource.LOGGER: 日志错误
• RumErrorSource.AGENT: Agent 错误
• RumErrorSource.WEBVIEW: WebView 错误
• RumErrorSource.CUSTOM: 自定义错误

自定义计时

除了 RUM SDK 默认的性能指标,您还可以使用 addTiming API 测量应用花费时间。计时是相对于当前 RUM 视图开始时间的偏移量。

例如,您可以计时主角图片显示所需的时间:

import cloud.flashcat.android.rum.GlobalRum

fun onHeroImageLoaded() {
    GlobalRum.get().addTiming("hero_image")
}

import cloud.flashcat.android.rum.GlobalRum;

public void onHeroImageLoaded() {
    GlobalRum.get().addTiming("hero_image");
}

一旦设置了计时,该计时可通过 @view.custom_timings.<timing_name> 访问,例如 @view.custom_timings.hero_image。

添加用户属性

RUM SDK 会自动追踪用户属性。您还可以添加额外的自定义用户属性,例如用户计划、用户组等:

import cloud.flashcat.android.rum.GlobalRum

GlobalRum.get().setUserInfo(
    id = "1234",
    name = "John Doe",
    email = "john@doe.com",
    extraInfo = mapOf(
        "plan" to "premium",
        "group" to "vip"
    )
)

import cloud.flashcat.android.rum.GlobalRum;
import java.util.HashMap;
import java.util.Map;

Map<String, Object> extraInfo = new HashMap<>();
extraInfo.put("plan", "premium");
extraInfo.put("group", "vip");

GlobalRum.get().setUserInfo(
    "1234",
    "John Doe",
    "john@doe.com",
    extraInfo
);

事件和数据管理

清除所有数据

使用 clearAllData 清除当前存储在 SDK 中的所有未发送数据:

import cloud.flashcat.android.Flashcat

Flashcat.clearAllData()

import cloud.flashcat.android.Flashcat;

Flashcat.clearAllData();

停止数据收集

使用 stopInstance 停止收集数据并清除所有本地数据:

import cloud.flashcat.android.Flashcat

Flashcat.stopInstance()

import cloud.flashcat.android.Flashcat;

Flashcat.stopInstance();

控制事件批量上传

RUM SDK 会自动批量上传事件。您可以通过配置参数控制批量上传的行为:

import cloud.flashcat.android.core.configuration.Configuration
import cloud.flashcat.android.core.configuration.UploadFrequency

val configuration = Configuration.Builder(
    clientToken = clientToken,
    env = environmentName,
    variant = appVariantName
)
    .setBatchSize(batchSize)
    .setUploadFrequency(UploadFrequency.FREQUENT)
    .build()

import cloud.flashcat.android.core.configuration.Configuration;
import cloud.flashcat.android.core.configuration.UploadFrequency;

Configuration configuration = new Configuration.Builder(clientToken, environmentName, appVariantName)
    .setBatchSize(batchSize)
    .setUploadFrequency(UploadFrequency.FREQUENT)
    .build();

UploadFrequency 可选值:

• UploadFrequency.FREQUENT: 频繁上传
• UploadFrequency.AVERAGE: 平均上传(默认)
• UploadFrequency.RARE: 少量上传

设置远程日志阈值

您可以为远程记录的消息定义最低日志级别。低于该级别的日志不会发送到 FlashCat:

import cloud.flashcat.android.log.Logs
import cloud.flashcat.android.log.LogsConfiguration
import android.util.Log

val logsConfig = LogsConfiguration.Builder()
    .setRemoteSampleRate(100f)
    .setRemoteLogThreshold(Log.WARN)
    .build()
Logs.enable(logsConfig)

import cloud.flashcat.android.log.Logs;
import cloud.flashcat.android.log.LogsConfiguration;
import android.util.Log;

LogsConfiguration logsConfig = new LogsConfiguration.Builder()
    .setRemoteSampleRate(100f)
    .setRemoteLogThreshold(Log.WARN)
    .build();
Logs.enable(logsConfig);

追踪自定义全局属性

除了由 RUM SDK 自动捕获的默认属性外,您还可以向 RUM 事件添加额外的上下文信息,例如自定义属性。自定义属性允许您根据应用的代码级信息(如购物车状态、商家层级、广告活动)过滤和分组观察到的用户行为。

追踪用户会话

将用户信息添加到 RUM 会话可以:

• 跟踪特定用户的浏览路径
• 了解哪些用户受错误影响最大
• 监控关键用户的性能

以下属性是可选的,建议至少提供一个:

• id (String): 唯一用户标识符
• name (String): 用户友好名称,默认在 RUM UI 中显示
• email (String): 用户电子邮件,若无名称则显示邮件

要识别用户会话,在初始化 SDK 后使用 setUserInfo API:

import cloud.flashcat.android.rum.GlobalRum

GlobalRum.get().setUserInfo(
    id = "1234",
    name = "John Doe",
    email = "john@doe.com"
)

import cloud.flashcat.android.rum.GlobalRum;

GlobalRum.get().setUserInfo("1234", "John Doe", "john@doe.com", null);

追踪属性

添加全局属性

import cloud.flashcat.android.rum.GlobalRum

GlobalRum.get().addAttribute("key", "value")

import cloud.flashcat.android.rum.GlobalRum;

GlobalRum.get().addAttribute("key", "value");

删除全局属性

import cloud.flashcat.android.rum.GlobalRum

GlobalRum.get().removeAttribute("key")

import cloud.flashcat.android.rum.GlobalRum;

GlobalRum.get().removeAttribute("key");

追踪 Widgets

Widgets 不会自动追踪。要手动从 Widget UI 发送交互,可以调用 FlashCat API:

import cloud.flashcat.android.rum.GlobalRum

fun onWidgetClicked() {
    GlobalRum.get().addAction(
        RumActionType.TAP,
        "widget_clicked",
        mapOf("widget_name" to "HomeWidget")
    )
}

import cloud.flashcat.android.rum.GlobalRum;
import java.util.HashMap;
import java.util.Map;

public void onWidgetClicked() {
    Map<String, Object> attributes = new HashMap<>();
    attributes.put("widget_name", "HomeWidget");
    GlobalRum.get().addAction(
        RumActionType.TAP,
        "widget_clicked",
        attributes
    );
}

初始化参数

在初始化 FlashCat Android SDK 时,您可以使用 Configuration.Builder 中的以下方法配置 SDK:

自动追踪视图

要自动追踪视图(Activities、Fragments),在初始化时使用 useViewTrackingStrategy:

import cloud.flashcat.android.rum.RumConfiguration
import cloud.flashcat.android.rum.tracking.ActivityViewTrackingStrategy

val rumConfig = RumConfiguration.Builder(applicationId)
    .useViewTrackingStrategy(ActivityViewTrackingStrategy(true))
    .build()

import cloud.flashcat.android.rum.RumConfiguration;
import cloud.flashcat.android.rum.tracking.ActivityViewTrackingStrategy;

RumConfiguration rumConfig = new RumConfiguration.Builder(applicationId)
    .useViewTrackingStrategy(new ActivityViewTrackingStrategy(true))
    .build();

可用的追踪策略:

• ActivityViewTrackingStrategy(trackExtras): 追踪每个 Activity 为一个单独的视图。trackExtras 参数决定是否追踪 Activity 的 Intent extras
• FragmentViewTrackingStrategy(trackArguments): 追踪每个 Fragment 为一个单独的视图。trackArguments 参数决定是否追踪 Fragment 的参数
• MixedViewTrackingStrategy(trackExtras, trackArguments): 混合追踪 Activities 和 Fragments。同时追踪 Activity 和 Fragment 作为单独视图
• NavigationViewTrackingStrategy(navigationViewId): 用于 Android Navigation 组件。追踪导航目的地为视图

自动追踪网络请求

要自动追踪网络请求,请参考 SDK 接入指南 中的 OkHttp 拦截器配置。

自动追踪 Apollo GraphQL 请求

如果您使用 Apollo GraphQL 客户端进行网络调用,可以通过以下步骤启用自动追踪:

步骤 1: 添加 fc-sdk-android-apollo 依赖到您的应用的 build.gradle 文件:

dependencies {
    implementation "cloud.flashcat:fc-sdk-android-apollo:x.x.x"
}

步骤 2: 添加 FlashCat 拦截器到 Apollo Client 配置:

import com.apollographql.apollo.ApolloClient
import com.apollographql.apollo.network.okHttpClient
import cloud.flashcat.android.apollo.FlashcatApolloInterceptor

val apolloClient = ApolloClient.Builder()
    .serverUrl("GraphQL endpoint")
    .addInterceptor(FlashcatApolloInterceptor())
    .okHttpClient(okHttpClient)
    .build()

import com.apollographql.apollo.ApolloClient;
import cloud.flashcat.android.apollo.FlashcatApolloInterceptor;

ApolloClient apolloClient = new ApolloClient.Builder()
    .serverUrl("GraphQL endpoint")
    .addInterceptor(new FlashcatApolloInterceptor())
    .okHttpClient(okHttpClient)
    .build();

这将自动为您的 GraphQL 请求添加 FlashCat 追踪头,使其能够被 FlashCat 追踪。

注意:

• 该集成仅支持 Apollo 版本 4
• 仅追踪 query 和 mutation 类型的操作,不追踪 subscription 操作
• GraphQL payload 发送默认禁用。要启用,请在 FlashcatApolloInterceptor 构造函数中设置 sendGraphQLPayloads 标志:

FlashcatApolloInterceptor(sendGraphQLPayloads = true)

new FlashcatApolloInterceptor(true)

自动追踪长任务

在主线程上执行的长时间运行的操作可能会影响应用的视觉性能和响应性。要追踪这些操作,请定义任务被视为过长的持续时间阈值:

import cloud.flashcat.android.rum.RumConfiguration

val rumConfig = RumConfiguration.Builder(applicationId)
    .trackLongTasks(durationThreshold)
    .build()

import cloud.flashcat.android.rum.RumConfiguration;

RumConfiguration rumConfig = new RumConfiguration.Builder(applicationId)
    .trackLongTasks(durationThreshold)
    .build();

例如,要替换默认的 100 ms 持续时间,可以在配置中设置自定义阈值:

val rumConfig = RumConfiguration.Builder(applicationId)
    .trackLongTasks(250L) // 追踪超过250ms的任务为长任务
    .build()

RumConfiguration rumConfig = new RumConfiguration.Builder(applicationId)
    .trackLongTasks(250L) // 追踪超过250ms的任务为长任务
    .build();

修改或丢弃 RUM 事件

要在批量处理之前修改 RUM 事件的某些属性,或完全丢弃某些事件,请在初始化 RUM Android SDK 时提供 EventMapper<T> 的实现:

import cloud.flashcat.android.rum.RumConfiguration

val rumConfig = RumConfiguration.Builder(applicationId)
    .setErrorEventMapper(rumErrorEventMapper)
    .setActionEventMapper(rumActionEventMapper)
    .setResourceEventMapper(rumResourceEventMapper)
    .setViewEventMapper(rumViewEventMapper)
    .setLongTaskEventMapper(rumLongTaskEventMapper)
    .build()

import cloud.flashcat.android.rum.RumConfiguration;

RumConfiguration rumConfig = new RumConfiguration.Builder(applicationId)
    .setErrorEventMapper(rumErrorEventMapper)
    .setActionEventMapper(rumActionEventMapper)
    .setResourceEventMapper(rumResourceEventMapper)
    .setViewEventMapper(rumViewEventMapper)
    .setLongTaskEventMapper(rumLongTaskEventMapper)
    .build();

当实现 EventMapper<T> 接口时,每种事件类型只有部分属性可以修改:

事件类型	可修改的属性键	描述
ViewEvent	view.referrer	链接到页面初始视图的 URL
	view.url	视图的 URL
	view.name	视图的名称
ActionEvent	action.target.name	目标名称
	view.referrer	链接到页面初始视图的 URL
	view.url	视图的 URL
	view.name	视图的名称
ErrorEvent	error.message	错误消息
	error.stack	错误的堆栈跟踪
	error.resource.url	资源的 URL
	view.referrer	链接到页面初始视图的 URL
	view.url	视图的 URL
	view.name	视图的名称
ResourceEvent	resource.url	资源的 URL
	view.referrer	链接到页面初始视图的 URL
	view.url	视图的 URL
	view.name	视图的名称
LongTaskEvent	view.referrer	链接到页面初始视图的 URL
	view.url	视图的 URL
	view.name	视图的名称

注意: 如果从 EventMapper<T> 实现中返回 null,则事件将保持原样并按原样发送。

示例:丢弃敏感错误

val rumConfig = RumConfiguration.Builder(applicationId)
    .setErrorEventMapper { errorEvent ->
        if (errorEvent.error.message?.contains("sensitive_data") == true) {
            null // 丢弃包含敏感数据的错误
        } else {
            errorEvent
        }
    }
    .build()

RumConfiguration rumConfig = new RumConfiguration.Builder(applicationId)
    .setErrorEventMapper(errorEvent -> {
        if (errorEvent.error.message != null &&
            errorEvent.error.message.contains("sensitive_data")) {
            return null; // 丢弃包含敏感数据的错误
        } else {
            return errorEvent;
        }
    })
    .build();

获取 RUM Session ID

检索 RUM Session ID 对于故障排查很有帮助。例如,您可以将 Session ID 附加到支持请求、电子邮件或错误报告中,以便支持团队稍后在 FlashCat 中找到用户会话。

您可以在运行时访问 RUM Session ID,而无需等待 sessionStarted 事件:

import cloud.flashcat.android.rum.GlobalRum

GlobalRum.get().getCurrentSessionId { sessionId ->
    currentSessionId = sessionId
}

import cloud.flashcat.android.rum.GlobalRum;

GlobalRum.get().getCurrentSessionId(sessionId -> {
    currentSessionId = sessionId;
});

采样

默认情况下,FlashCat RUM 会收集所有会话的数据。您可以在初始化时通过 sessionSampleRate 参数设置采样率(百分比)来减少收集的会话数量:

import cloud.flashcat.android.rum.RumConfiguration

val rumConfig = RumConfiguration.Builder(applicationId)
    .setSessionSampleRate(90.0f) // 采集 90% 的会话
    .build()

import cloud.flashcat.android.rum.RumConfiguration;

RumConfiguration rumConfig = new RumConfiguration.Builder(applicationId)
    .setSessionSampleRate(90.0f) // 采集 90% 的会话
    .build();

被采样的会话将不收集任何页面视图及其相关遥测数据。

用户跟踪同意

为遵守 GDPR、CCPA 等隐私法规,FlashCat RUM 允许在初始化时设置用户跟踪同意状态。可选值:

• TrackingConsent.GRANTED: 开始收集数据并发送到 FlashCat
• TrackingConsent.NOT_GRANTED: 不收集任何数据
• TrackingConsent.PENDING: 开始收集数据但不发送到 FlashCat

如果初始化时使用 TrackingConsent.PENDING,SDK 将开始收集数据,但在同意状态更改为 TrackingConsent.GRANTED 之前不会发送。

您可以通过 setTrackingConsent API 在初始化后更改同意状态:

import cloud.flashcat.android.Flashcat
import cloud.flashcat.android.privacy.TrackingConsent

Flashcat.setTrackingConsent(TrackingConsent.GRANTED)

import cloud.flashcat.android.Flashcat;
import cloud.flashcat.android.privacy.TrackingConsent;

Flashcat.setTrackingConsent(TrackingConsent.GRANTED);

注意事项

• 确保在适当的生命周期方法中调用 startView 和 stopView,避免视图重复追踪
• 使用自定义资源追踪时,确保每个 startResource 都有对应的 stopResource 或 stopResourceWithError 调用
• 修改事件时,只有上述表格中列出的属性可以修改,其他属性的修改将被忽略
• 合理设置采样率和批量上传频率,平衡数据量与性能开销

更多阅读

• Android SDK 接入指南: 了解如何接入 Android RUM SDK
• Android 数据收集: 了解 SDK 收集的数据类型和内容
• RUM 应用管理: 了解如何创建和管理 RUM 应用