一、启动监控（冷启动 / 热启动）
注意：说明：
标记业务首屏就绪：
·无需手动调用：使用 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：
·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, // 聚合上报等待时间 },});
三、路由切换耗时
注意：说明：
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.tsxconst 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 修正（见 配置文档 示例）。