帮你快速理解、总结文档立即下载
文档中心>腾讯云可观测平台>前端性能监控>接入指南>React Native 应用场景>配置文档

配置文档

最近更新时间：2026-09-28 17:02:02
我的收藏

本页目录：

配置说明

配置文档各配置项说明如下：
配置
描述
id
必须，string，默认无。前端性能监控分配的应用 ID（上报 ID）。
uin
建议，string，默认无。当前用户的唯一标识符，白名单上报时将根据该字段判定用户是否在白名单中，字段仅支持字母数字 @=._-，正则表达式：/^[@=.0-9a-zA-Z_-]{1,60}$/。
aid
可选，boolean 或 string，默认 true。当前实例是否生成 aid。RN 环境下通过 AsyncStorage（key AEGIS_ID）持久化，用于区分用户设备、计算 uv。未安装 @react-native-async-storage/async-storage（可选 peerDependency）时降级为不持久化的 aid。
onError
可选，boolean，默认 true。当前实例是否需要进行错误监听，获取错误日志（JS 执行错误、Promise 错误、接口请求异常、retcode 异常）。
env
可选，enum，默认 Aegis.environment.production。当前应用运行所处的环境。
version
可选，string，默认 SDK 版本号。当前上报版本，当应用存在离线包时，可用来判断当前的上报是来自哪一个版本的代码，仅支持字母数字 .,:_-，长度在 60 位以内 /^[0-9a-zA-Z.,:_-]{1,60}$/。
delay
可选，number，默认1000ms。上报节流时间，在该时间段内的上报将会合并到一个上报请求中。
repeat
可选，number，默认60。重复上报次数限制（同一个错误 / 同一条测速超过多少次后不上报），传入0则不限制。
random
可选，number，默认1。0 - 1抽样率，0表示全部不上报。
speedSample
可选，boolean，默认 true。测速日志是否抽样（限制每条 url 只上报一次测速日志）。
pageUrl
可选，默认 -。修改上报数据中页面地址（from 字段），开发者可以主动对数据进行聚合和降低维度。
urlHandler
可选，Function。自定义页面地址（from 字段）计算函数，返回值长度上限2048。
hostUrl
可选，默认 https://rumt-zh.com。影响全部上报数据的 host 地址（国内 rumt-zh.com、新加坡 rumt-sg.com、硅谷 rumt-us.com）。
api
可选，object，默认为 {}。相关的配置：
apiDetail：可选，boolean，默认 false。上报 API 信息的时候，是否上报 API 的请求参数和返回值；
retCodeHandler：Function(data: String, url: String, xhr: Object): {isErr: boolean, code: string}，返回码上报钩子函数，会传入接口返回数据、请求 url 和 xhr 对象，详见示例 api.retCodeHandler；
reqParamHandler：Function(data: any, url: String)，上报请求参数的处理函数，方便过滤上报请求参数的信息；
resBodyHandler：Function(data: any, url: String)，上报 response 返回 body 的处理函数，只上报关键信息；
resourceTypeHandler：Function，请求资源类型修正钩子函数，会传入接口 url，返回值为 static 或 fetch；
reportRequest：boolean，默认 false，开启后 aegis.info 会变成全量上报，不需要白名单配置，并且会上报所有接口的信息（上报接口需开启 reportApiSpeed）；
reqHeaders / resHeaders：Array，需要上报的 HTTP 请求 / 响应 headers 列表。
beforeRequest
可选，Function。日志上报前执行的钩子，返回 false 拦截该条上报，返回修改后的数据则按修改后的内容上报。
afterRequest
可选，Function。数据上报后执行的钩子。
device
可选，boolean，默认 true。是否采集设备信息（platform / vp / sr / netType；品牌机型通过 User-Agent 上报）。
ext1 - ext3
可选，string，自定义上报的额外维度，上报的时候可以被覆盖，长度限制为1024，超过1024时会被截断。
ext4 - ext10
可选，string，自定义上报的额外维度。使用前需要在 前端性能监控 > 应用管理 > 字段映射配置 模块上传自定义字段枚举表；上报的内容不在枚举表内会被改写为 undefined。
reportApiSpeed
可选，boolean，默认 false。是否开启接口测速（同时按 Content-Type 采集静态资源测速）。开启后还需在 白名单管理 页面将用户添加为白名单用户，才会将采集到的正常 API 请求记录到日志中，否则仅在指标分析模块聚合消费。
beforeReportSpeed
可选，Function。测速日志上报前的过滤钩子，返回 false 可阻止本条测速上报。
enableAppStart
可选，boolean 或 AppStartConfig，默认 true。是否开启冷/热启动监控。对象形式的配置：
maxDurationMs：可选，number，默认 180000。启动指标最大有效耗时（ms），duration 达到该值视为异常并丢弃；
appLoadedTimeoutMs：可选，number，默认 3000。等待业务调用 appLoaded() 作为启动结束点的最长时间，超时回退到 first-frame；
enablePreWarmedAppStartTracing：可选，boolean，默认 false。是否上报 iOS 系统预热（ActivePrewarm）触发的冷启动数据；Android 无此机制，该开关只影响 iOS。
enablePagePerf
可选，boolean，默认 true。是否开启页面性能上下文基础采集（为 TTID/TTFD/路由切换提供统一上下文），没有接入路由开始/结束点时不会产生上下文。
enableRouteSwitch
可选，boolean 或 RouteSwitchConfig，默认 true。是否开启路由切换耗时监控。对象形式的配置：
maxDurationMs：可选，number，默认5000。路由切换最大有效耗时（ms），超出丢弃；
ignoreBackNavigation：可选，boolean，默认 true。是否忽略返回到已访问页面的路由切换测速。
enableTTID
可选，boolean 或 PageDisplayConfig，默认 true。是否开启页面级 TTID（首帧）/ TTFD（完整展示）监控。对象形式的配置：
maxDurationMs：可选，number，默认 60000。页面显示指标最大有效耗时（ms），超出或负值丢弃；
includeAppStartTTID：可选，boolean，默认 true。是否把冷/热启动首屏作为页面 TTID 上报；
includeAppStartTTFD：可选，boolean，默认 true。是否在冷启动首屏 TTFD 中包含 App Start 耗时；
reportSeenRoutes：可选，boolean，默认 false。是否对"已访问过的路由"上报 TTID/TTFD（返回已访问页默认跳过）；
aggregateTimeoutMs：可选，number，默认10000。聚合上报等待时间（ms），页面加载后超过该时间未收到 TTFD 时自动用已采集指标触发聚合上报，设为0立即上报，有效范围 [0, 60000]。
spa
可选，boolean，默认 false。是否开启页面流转监控（PV 上报）。开启后需配合 aegis.reportPageView()、useAegisPageView 或路由框架集成使用。

示例

api.retCodeHandler

假如后台返回数据为：
{
   body: {
      code: 200,
      retCode: 0,
      data: {
          // xxx
      }
   }
}
业务需要：code 不为200，或者 retCode 不为0，此次请求就是错误的。此时只需进行以下配置：
new Aegis({
    id: 'pGUVFTCZyewhxxxxxx',
    reportApiSpeed: true, // 需要开启，不然不会有返回码上报
    api: {
        retCodeHandler(data, url, xhr) {
            // data 是 string 类型，如果需要对象需要手动 parse 下
            // url 为请求 url
            // xhr 响应，可以通过 xhr.response 拿到完整的后台响应
            try {
                data = JSON.parse(data)
            } catch(e) {}
            return {
                // isErr 如果是 true 的话，会上报一条 retcode 异常的日志。
                isErr: data.body.code !== 200 || data.body.retCode !== 0,
                code:  data.body.code
            }
        }
    }
})

api.resourceTypeHandler

假如接口为 http://example.com/test-api，返回的 Content-Type 为 text/html，这将导致 Aegis 认为该接口返回的是静态资源，可以通过以下方法修正：
new Aegis({
    id: 'pGUVFTCZyewhxxxxxx',
    reportApiSpeed: true,
    api: {
        resourceTypeHandler(url) {
            if (url?.indexOf('http://example.com/test-api') != -1) {
                return 'fetch';
            }
        }
    }
})

urlHandler（restful 页面地址聚合）

假如您的页面路由是 restful 风格的，例如 /user/1000、/user/1001，在上报时需要将这些页面地址聚合：
new Aegis({
    id: 'pGUVFTCZyewhxxxxxx',
    urlHandler() {
        const name = /* 从当前路由获取路由名，如 getCurrentRoute().name */;
        if (/^\\/user\\/\\d*/.test(name)) {
            return '/user/:id';
        }
        return name;
    }
})

beforeRequest（上报拦截 / 修改）

const aegis = new Aegis({
    id: 'pGUVFTCZyewhxxxxxx',
    beforeRequest(data) {
        // 入参 data 的数据结构：{logs: {…}, logType: "log"}
        if (data.logType === 'log' && data.logs.msg.indexOf('internal.example.com') > -1) {
            // 返回 false 拦截该条上报
            return false;
        }
        // 修改入参并返回，按修改后的内容上报
        return data;
    }
});
中国站