配置 EAS Observe

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

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

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

configure()

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

import { Observe } from 'expo-observe';

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

dispatchEvents()

当应用切换到后台时，事件会自动分发。在 Android 上，一旦网络连接可用，后台 worker 就会分发事件。在 iOS 上，这发生在应用失去活跃状态或即将终止时。

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

import { Observe } from 'expo-observe';

await Observe.dispatchEvents();

抽样

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

import { Observe } from 'expo-observe';

// 从大约 25% 的安装中分发指标。
Observe.configure({
  sampleRate: 0.25,
});

抽样决策对每次安装是确定性的。对于给定的抽样率，每次安装要么永久处于样本内，要么永久处于样本外，因此该选择在应用启动之间保持稳定，你获得的是一组一致的安装切片，而不是会话的随机子集。

有几点细节值得了解：

• 超出 [0, 1] 范围的值会被限制到最近的边界。0 始终丢弃；1 始终分发。
• 样本外设备会丢弃待处理的指标，而不是累积它们。稍后降低抽样率不会追溯发送更早的会话。
• 抽样依赖于 dispatchingEnabled。如果 dispatchingEnabled 为 false，无论 sampleRate 是多少，都不会分发任何内容。

在开发中启用指标

默认情况下，从调试构建中收集的指标不会被分发。不过，如果你想仍然分发它们（例如，在测试 EAS Observe 集成时），请在调用 configure() 时将 dispatchInDebug 设置为 true：

import { Observe } from 'expo-observe';

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

如果原生应用是调试构建，或者 JS bundle 是开发包（__DEV__ 为 true），则会将构建视为调试构建。此检测与 environment 值无关（参见 环境）。

dispatchInDebug 对发布构建没有影响；发布构建始终会分发（受 dispatchingEnabled 和 sampleRate 约束）。如果 dispatchingEnabled 为 false，或者此安装处于样本外，则无论 dispatchInDebug 如何，都不会分发任何内容。

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

自定义端点

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

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

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

环境

所有指标都会按环境分组。默认情况下，环境值由 process.env.NODE_ENV 派生（如果未设置，则回退为 'production'）。若要覆盖它，请使用 configure({ environment })。

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