配置 Expo 观察

控制 Expo Observe 如何收集和发送指标，包括环境设置、开发模式和自定义端点。

For the complete documentation index, see llms.txt. Use this file to discover all available pages.

在运行时配置 Expo Observe 以适应你的应用构建设置、环境和数据路由。本页涵盖 configure() 和 dispatchEvents()，启用开发环境中的指标、使用自定义端点以及按环境分离数据。

🌐 Configure Expo Observe at runtime to fit your app's build setup, environment, and data routing. This page covers the configure() and dispatchEvents(), enabling metrics in development, using a custom endpoint, and separating data by environment.

configure()

使用 configure() 方法来控制 Expo Observe 在运行时的行为：

🌐 Use the configure() method to control how Expo Observe behaves at runtime:

import ExpoObserve from 'expo-observe';

ExpoObserve.configure({
  environment: 'production',
  dispatchingEnabled: true,
});

dispatchEvents()

当应用进入后台时，事件会自动分发。在 Android 上，一旦网络连接可用，后台工作线程就会分发事件。在 iOS 上，当应用失去活跃状态或即将终止时，会发生这种情况。

🌐 Events are automatically dispatched when the app moves to the background. On Android, a background worker dispatches events once network connectivity is available. On iOS, this happens when the app resigns active state or is about to terminate.

要手动刷新事件（例如，在测试期间或为了确保事件在特定时间点之前发送），请调用 dispatchEvents()：

🌐 To flush events manually (for example, during testing or to ensure events are sent before a specific point), call dispatchEvents():

import ExpoObserve from 'expo-observe';

await ExpoObserve.dispatchEvents();

采样

🌐 Sampling

默认情况下，每个安装都会发送其指标。对于高流量应用，你可以通过将 sampleRate 设置为介于 0 和 1 之间的值来抽样部分安装：

🌐 By default, every installation dispatches its metrics. For high-volume apps, you can sample a fraction of installations by setting sampleRate to a value between 0 and 1:

import ExpoObserve from 'expo-observe';

// Dispatch metrics from ~25% of installations.
ExpoObserve.configure({
  sampleRate: 0.25,
});

采样决策是针对每个安装确定的。每个安装对于给定的比率要么永久处于样本内，要么永久处于样本外，因此该选择在应用启动时是稳定的，并且你获得的是一部分稳定的安装，而不是会话的随机子集。

🌐 The sampling decision is deterministic per installation. Each installation is either permanently in-sample or out-of-sample for a given rate, so the choice is stable across app launches and you get a consistent slice of installations rather than a random subset of sessions.

值得了解的一些细节：

🌐 A few details worth knowing:

• 超出 [0, 1] 范围的值会被限制到最近的边界。0 总是下降；1 总是分发。
• 样本外设备会放弃待处理的指标，而不是累积它们。稍后降低速率不会追溯发送之前的会话。
• 采样取决于dispatchingEnabled。如果dispatchingEnabled是false，无论sampleRate如何，都不会派发任何内容。

在开发中启用指标

🌐 Enable metrics in development

默认情况下，从调试构建收集的指标不会被分发。要无论如何分发它们（例如，在测试你的 Expo Observe 集成时），在调用 configure() 时将 dispatchInDebug 设置为 true：

🌐 By default, metrics collected from debug builds are not dispatched. To dispatch them anyway (for example, while testing your Expo Observe integration), set dispatchInDebug to true when calling configure():

import ExpoObserve from 'expo-observe';

ExpoObserve.configure({
  dispatchInDebug: true,
});

如果本地应用是调试版本或 JS 包是开发包（__DEV__ 是 true），构建将被视为调试构建。这种检测独立于 environment 的值（参见 Environments）。

🌐 A build is treated as a debug build if either the native app is a debug build or the JS bundle is a development bundle (__DEV__ is true). This detection is independent of the environment value (see Environments).

dispatchInDebug 对发布版本没有影响，发布版本总是会派发（受 dispatchingEnabled 和 sampleRate 的约束）。如果 dispatchingEnabled 是 false 或者该安装属于样本外，则无论 dispatchInDebug 如何，都不会派发。

警告 仅在测试你的 Expo Observe 集成时启用此功能。开发/调试性能与生产环境差异显著，因此收集开发/调试指标可能会扭曲仪表板中显示的结果。

自定义端点

🌐 Custom endpoint

如果你需要更改可观测性 API 的端点，请在你的 应用配置 中设置 endpointUrl 值：

🌐 If you need to change the endpoint for the observability API, set the endpointUrl value in your app config:

{
  "expo": {
    "extra": {
      "eas": {
        "observe": {
          "endpointUrl": "https://your-custom-endpoint.com"
        }
      }
    }
  }
}

端点 URL 在应用的原生层中于构建时内置，因此更改它需要重新生成原生代码。更新应用配置后，运行 npx expo prebuild 并创建一个新构建以应用更改。

🌐 The endpoint URL is baked into the native layer of the app at build time, so changing it requires regenerating native code. After updating your app config, run npx expo prebuild and create a new build to apply the change.

环境

🌐 Environments

所有指标按环境分组。环境值默认由 process.env.NODE_ENV 导出（如果未设置，则回退到 'production'）。要覆盖它，请使用 configure({ environment })。

🌐 All metrics are grouped by environment. The environment value is derived from process.env.NODE_ENV by default (falling back to 'production' if unset). To override it, use configure({ environment }).

环境是附加到每个指标的元数据标签，与打包包的构建方式无关。要控制是否发送调试构建的指标，请参见 在开发中启用指标。要在全局范围内禁用所有发送，请使用 configure({ dispatchingEnabled: false })。

🌐 The environment is a metadata tag attached to each metric and is independent of how the bundle was built. To control whether debug-build metrics are dispatched, see Enable metrics in development. To disable all dispatching globally, use configure({ dispatchingEnabled: false }).