tencent cloud

腾讯云可观测平台

文档腾讯云可观测平台前端性能监控接入指南React Native 应用场景性能监控

性能监控

下载
聚焦模式
字号
最后更新时间： 2026-10-20 11:59:59
您可以通过本文了解启动监控、页面测速（TTID/TTFD）、路由切换耗时、页面流转监控、接口测速的统计方式和传入配置等信息。

启动监控（冷启动 / 热启动）

说明：
打开方式：初始化 时传入配置 enableAppStart: true（默认开启，可关闭或传对象精细控制）。
启动结束点来源 endSource：
app-loaded：业务（或 navigation 集成）调用了 aegis.appLoaded()；
first-frame：未调用或超时（默认 3000ms），回退到系统首帧。
标记业务首屏就绪：
无需手动调用：使用 createReactNavigationIntegration / createExpoRouterIntegration 接入路由时，SDK 会在首屏路由就绪后自动调用 aegis.appLoaded()。
需要手动调用：未接入路由集成（如 react-native-navigation、自定义路由）时，SDK 无法感知首屏就绪时机，需业务在首屏就绪后手动调用。默认 3000ms（appLoadedTimeoutMs）内未调用时，SDK 回退以系统首帧（first-frame）作为启动结束点；若首屏依赖异步数据，建议手动调用以贴近真实体验。
// 默认使用 JS Date.now()
aegis.appLoaded();

// 需要与 native 时间点完全同域时（消除个别 ROM 的 JS/native 时钟偏差）
await aegis.appLoadedAsync();
AppStartConfig 配置项说明：
配置项
类型
默认值
说明
maxDurationMs
number
180000
启动指标最大有效耗时（ms），duration 达到该值视为异常并丢弃
appLoadedTimeoutMs
number
3000
等待业务调用 appLoaded() 作为启动结束点的最长时间，超时回退到 first-frame
enablePreWarmedAppStartTracing
boolean
false
是否上报 iOS 14+ 系统预热（ActivePrewarm）触发的冷启动数据；true 时自动把耗时起点切换为 runtimeInitTime 并标记 prewarm=1。Android 无此机制，该开关只影响 iOS
使用示例：
const aegis = new Aegis({
  id: 'pGUVFTCZyewhxxxxxx',
  enableAppStart: {
    maxDurationMs: 180000,      // 最大有效耗时
    appLoadedTimeoutMs: 3000,   // 等待 appLoaded 超时时间
    enablePreWarmedAppStartTracing: false,  // 是否上报 iOS 14+ 预热冷启动（仅 iOS 生效）
  },
});

页面测速（TTID / TTFD）

说明：
页面测速用于统计页面「首帧可见」（TTID）到「完整可交互」（TTFD）的耗时，帮助定位页面加载慢、首屏数据迟迟未就绪等问题。
打开方式：初始化 时传入配置 enableTTID: true（默认开启）。TTID 由 SDK 自动采集，无需额外接入；TTFD 需业务标记「数据已就绪」的时机（SDK 无法自行感知），二选一即可：
在页面中接入 <TimeToFullDisplay record={ready} />（推荐）。
数据就绪后手动调用 reportTTFD() 上报。两者都不做时 TTFD 缺失，上报侧会用 TTID 兜底。
TTID 与 TTFD：
TTID（Time To Initial Display）：页面首帧渲染时间。起点：冷启动首屏为 processStartTime，普通页面切换为路由切换开始时间（routeSwitchStart）。
TTFD（Time To Full Display）：页面完整可交互时间，由业务标记数据就绪时机后采集；TTFD 缺失或小于 TTID 时，上报侧自动用 TTID 兜底。
组件接入示例：
import { TimeToInitialDisplay, TimeToFullDisplay } from 'aegis-rn-sdk';

export default function HomeScreen() {
  const [ready, setReady] = useState(false);
  useEffect(() => {
    // 模拟业务数据加载完成
    fetchData().then(() => setReady(true));
  }, []);

  return (
    <View>
      {/* 首帧渲染标记（默认 record=true） */}
      <TimeToInitialDisplay route="Home" />
      {/* 数据 ready 后才标记完整展示 */}
      <TimeToFullDisplay record={ready} route="Home" />
      {/* ... 页面内容 ... */}
    </View>
  );
}
PageDisplayConfig 配置项说明：
配置项
类型
默认值
说明
maxDurationMs
number
60000
页面显示指标最大有效耗时（ms），超出或负值丢弃
includeAppStartTTID
boolean
true
是否把冷启动首屏 TTID 起点改写为 processStartTime
includeAppStartTTFD
boolean
true
是否把冷启动首屏 TTFD 起点改写为 processStartTime
reportSeenRoutes
boolean
false
是否对"已访问过的路由"上报 TTID/TTFD（返回已访问页默认跳过）
aggregateTimeoutMs
number
10000
聚合上报等待时间（ms），页面加载后超过该时间未收到 TTFD 时自动用已采集指标触发聚合上报；设为 0 立即上报。有效范围 [0, 60000]
timeoutMs
number
-
已废弃，保留仅为向后兼容，不再产生任何行为
使用示例：
const aegis = new Aegis({
  id: 'pGUVFTCZyewhxxxxxx',
  enableTTID: {
    maxDurationMs: 60000,     // 最大有效耗时
    aggregateTimeoutMs: 10000, // 聚合上报等待时间
  },
});

路由切换耗时

说明：
打开方式：初始化时传入配置 enableRouteSwitch: true（默认开启）。
Aegis 通过页面性能上下文（enablePagePerf，默认开启）记录路由切换开始/结束时间，上报 pageRouteTiming 路由切换耗时。需要接入路由框架集成以提供 routeSwitchStart / routeSwitchEnd 上下文。
RouteSwitchConfig 配置项说明：
配置项
类型
默认值
说明
maxDurationMs
number
5000
路由切换最大有效耗时（ms），超出丢弃
ignoreBackNavigation
boolean
true
是否忽略返回已访问页面的路由切换测速
使用示例：
const aegis = new Aegis({
  id: 'pGUVFTCZyewhxxxxxx',
  enableRouteSwitch: {
    maxDurationMs: 5000,          // 路由切换最大有效耗时（ms），超出丢弃
    ignoreBackNavigation: true,   // 是否忽略返回已访问页面的路由切换测速
  },
});

路由框架接入方式
：
路由框架
接入 API
说明
React Navigation
createReactNavigationIntegration(aegis)
推荐，onReady 时注册容器 ref，自动触发 PV、路由切换耗时与 appLoaded()
Expo Router
createExpoRouterIntegration(aegis)
与 React Navigation 等价，额外提供 remove() 卸载订阅
react-native-navigation（Wix）
createReactNativeNavigationIntegration(aegis)
基于 Navigation.events() 的 command / component-did-appear 事件
任意 pathname 框架
useAegisPageView(aegis, pathname)
兜底方案，仅做 PV 上报/去重，不承诺完整路由切换耗时
接入示例：
React Navigation：
import { NavigationContainer, createNavigationContainerRef } from '@react-navigation/native';
import Aegis, { createReactNavigationIntegration } from 'aegis-rn-sdk';

const navigationRef = createNavigationContainerRef();
const navIntegration = createReactNavigationIntegration(aegis);

export default function App() {
  return (
    <NavigationContainer
      ref={navigationRef}
      onReady={() => navIntegration.registerNavigationContainer(navigationRef)}
    >
      {/* ... 您的 Navigator ... */}
    </NavigationContainer>
  );
}
Expo Router：
import { useNavigationContainerRef } from 'expo-router';
import { createExpoRouterIntegration } from 'aegis-rn-sdk';

const integration = createExpoRouterIntegration(aegis, { routeChangeTimeoutMs: 1000 });

// expo-router/_layout.tsx
const navigationRef = useNavigationContainerRef();
useEffect(() => {
  integration.registerNavigationContainer(navigationRef);
  return () => integration.remove();
}, [navigationRef]);
react-native-navigation（Wix）：
import { Navigation } from 'react-native-navigation';
import { createReactNativeNavigationIntegration } from 'aegis-rn-sdk';

const integration = createReactNativeNavigationIntegration(aegis, {
  navigation: Navigation,
  routeChangeTimeoutMs: 1000,
  enableTabsInstrumentation: true,
});

// 应用退出 / 业务侧需要主动卸载时
integration.remove();
任意 pathname 框架（兜底）：
import { useAegisPageView } from 'aegis-rn-sdk';

function NavigationListener() {
  const pathname = /* 任意方式获取当前路由路径，如 usePathname() */;
  useAegisPageView(aegis, pathname, { ignore: ['/modal', /^\\/sheet/] });
  return null;
}

页面流转监控（PV）

说明：
打开方式：初始化 时传入配置 spa: true（默认关闭）。
开启后，Aegis 会在路由切换时上报页面 PV（pvUrl），同步更新全局 from 字段（后续所有日志携带当前页面信息），相同路由自动去重。接入方式（三选一）：
方式1：路由切换处手动上报
aegis.reportPageView('Home');
方式2：使用 Hook（任意可获取 pathname 的框架）
import { useAegisPageView } from 'aegis-rn-sdk';

useAegisPageView(aegis, pathname, { ignore: ['/modal', /^\\/sheet/] });
方式3： 使用路由框架集成，自动上报。
注意：
spa: true 仅表示启用 PV 插件，不会自动发现 RN 路由变化，必须配合上述接入方式之一，否则 PV 不会上报。

接口测速

说明：
按以下步骤打开并开始使用：
1. 初始化 时传入配置 reportApiSpeed: true，开启接口测速；
2. 在 白名单管理 页面将用户添加为白名单用户，采集到的正常 API 请求才会记录到日志中，否则仅在指标分析模块聚合消费。
Aegis 通过劫持 XHR 及 fetch 进行接口测速，同时会按响应 Content-Type 判断请求是接口还是静态资源，分别按接口（type: fetch）与静态资源（type: static）口径上报测速数据。Aegis 认为以下情况是异常请求：
http status 大于等于 400；
请求超时、abort、跨域、cancel；
请求结束时 http status 仍然是 0（通常发生于请求失败）。
开启 api.apiDetail: true 时，会同时上报接口的请求参数和返回信息。返回码（retcode）会从响应 body 第一层（取不到再取第二层）的 code、ret、retcode、errcode 中获取，默认 0 为正常、非 0 为异常，可通过 api.retCodeHandler 修正（见 配置文档 示例）。

上一篇: 错误监控下一篇: 环境控制

帮助和支持

本页内容是否解决了您的问题？

填写满意度调查问卷，共创更好文档体验。

文档反馈

搜索
    请输入关键词搜索文档