This documentation is available as Markdown for AI agents and LLMs. See the full Markdown index or append .md to any documentation URL.

通过启用 EAS Observe 的 Expo Router 集成来跟踪每个路由的渲染和交互时间。

EAS Observe ships 是一个针对 Expo Router 的可选集成，它会收集按路由模式标记的每个路由的指标（例如，/(tabs)/sessions/[sessionId]）。这让你可以在仪表板中按路由比较导航性能，而不仅仅是查看整个应用的汇总数据。

🌐 EAS Observe ships an opt-in integration for Expo Router that collects per-route metrics tagged with the route pattern (for example, /(tabs)/sessions/[sessionId]). This lets you compare navigation performance by route in the dashboard instead of looking only at app-wide aggregates.

先决条件

🌐 Prerequisites

import { Observe } from 'expo-observe';

Observe.configure({
  integrations: { 'expo-router': true },
});

import { useObserve } from 'expo-observe';
import { useEffect } from 'react';

export default function Home() {
  const { markInteractive } = useObserve();

  useEffect(() => {
    markInteractive();
  }, [markInteractive]);

  return (/* your screen content */);
}

过滤敏感的 URL 参数

🌐 Filter sensitive URL parameters

信息 可用于 SDK 57及更高版本。

默认情况下，集成会包含已解析的 url 以及 routeParams 中所有可序列化的路由和查询参数。如果你的应用在 URL 参数中包含敏感值，请将它们的键传给 filteredParams：

🌐 By default, the integration includes the resolved url and all serializable route and query parameters in routeParams. If your app includes sensitive values in URL parameters, pass their keys to filteredParams:

import { Observe } from 'expo-observe';

Observe.configure({
  integrations: {
    'expo-router': {
      filteredParams: ['userId', 'token'],
    },
  },
});

这个集成会从 routeParams 中移除被过滤的键，事件会省略 url，而改为包含 urlHidden: true。routeName 不受影响，因为它是一个模式，从不包含参数值。

🌐 The integration removes filtered keys from routeParams, and the event omits url and includes urlHidden: true instead. routeName is not affected because it is a pattern and never contains parameter values.

指标

🌐 Metrics

每路由首次渲染（cold_ttr）

🌐 Per-route first render (cold_ttr)

它衡量的内容： 从导航操作被触发（例如点击链接）到目的屏幕首次获得焦点的时间。对于应用启动后的第一次焦点，测量从 JS 包加载时开始，该事件包括 isAppLaunch: true。

在一次会话中的每个屏幕实例最多发出一次。

🌐 Emitted at most once per screen instance within a session.

事件参数：

每路预热渲染（warm_ttr）

🌐 Per-route warm render (warm_ttr)

它的衡量指标: 与 cold_ttr 相同，但针对那些在获取焦点之前已经渲染的屏幕，通常是因为它们通过 <Link prefetch /> 预加载，或用户导航回到它们。

事件参数：

每条路由到可交互的时间（tti）

🌐 Per-route time to interactive (tti)

它测量的内容： 从导航操作被分发到目标屏幕上调用 markInteractive() 的时间。每次导航只记录第一次调用，因此可以安全地多次调用 markInteractive()。

事件参数：

查看导航指标

🌐 View navigation metrics

在仪表板中，打开你的项目，导航到 Observe，然后选择 Navigation 页面。它显示了每条路由的导航时间，包括冷启动和热启动的首次渲染时间以及可交互时间。

🌐 In the dashboard, open your project, navigate to Observe, and select the Navigation page. It shows per-route navigation timings with cold and warm time to first render and time to interactive.

在命令行接口里，你可以运行以下命令：

🌐 In the CLI, you can run the following commands:

运行 eas observe:routes --help 可获取完整的标志列表（时间范围、平台、应用版本等）。其他 eas observe 命令请参阅 使用 EAS CLI 查询。

🌐 Run eas observe:routes --help for the full list of flags (time range, platform, app version, and more). See Querying with EAS CLI for the other eas observe commands.

注意事项与故障排除

🌐 Notes and troubleshooting

• routeName 是一个模式（/(tabs)/sessions/[sessionId]），而不是已解析的 URL（/sessions/abc）。这样可以在不同的参数值之间保持指标的稳定，因此仪表板会将它们归为一类。解析后的值仍然可以通过 url 和 routeParams 在事件中获取。
• 对 router.prefetch() 的调用不计为用户导航，也从不触发 cold_ttr 或 warm_ttr 测量。下一次用户驱动的到该路由的导航会触发 warm_ttr，因为屏幕已经渲染。
• 该集成仅在运行时安装了 expo-router 时才会激活。如果未安装，useObserve() 和 ObserveRoot 将继续工作，但不会发出每条路由的导航指标。
• 必须在通过 Observe.configure({ integrations: { 'expo-router': true } }) 挂载之前启用该集成。应用挂载后切换它会抛出错误。
• 如果 markInteractive() 记录了 Calling markInteractive on unmounted screen 或 No metadata available for the current screen，则表示该调用在屏幕组件之外或卸载后运行。将调用移到屏幕组件内的 useEffect 中。
• 有关 EAS Observe 的一般问题，请参阅 故障排除。