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 为 Expo Router 提供了一个可选集成，用于收集按路由标记的每路由指标（例如 /(tabs)/sessions/[sessionId]）。这样你就可以在仪表盘中按路由比较导航性能，而不只是查看应用整体汇总。

前提条件

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 (/* 你的屏幕内容 */);
}

过滤敏感的 URL 参数

在 SDK 57 及更高版本中可用。

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

import { Observe } from 'expo-observe';

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

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

指标

按路由首屏渲染（cold_ttr）

衡量内容： 从发出导航动作（例如点击链接）到目标屏幕第一次获得焦点所用的时间。对于应用启动后的第一次聚焦，测量从 JS bundle 加载开始计算，并且事件包含 isAppLaunch: true。

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

事件参数：

按路由热渲染（warm_ttr）

衡量内容： 与 cold_ttr 相同，但适用于在获得焦点之前已经渲染过的屏幕，通常是因为它们通过 <Link prefetch /> 预加载，或者用户返回到了这些屏幕。

事件参数：

按路由可交互时间（tti）

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

事件参数：

查看导航指标

在仪表盘中打开你的项目，前往 Observe，然后选择 Navigation 页面。该页面会显示按路由划分的导航耗时，包括冷启动和热启动首屏渲染时间以及可交互时间。

在 CLI 中，你可以运行以下命令：

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

注意事项和故障排查

• 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 的常规问题，请参阅 故障排查。