将第三方包与 EAS Observe 集成

将 expo-observe 添加为可选的对等依赖

🌐 Add expo-observe as an optional peer dependency

将 expo-observe 添加为可选的同行依赖，这样在它未安装时你的包仍然能正常工作。同时，将其作为开发依赖添加，以用于 TypeScript 类型和测试。不要将其添加为必需的运行时依赖。

🌐 Add expo-observe as an optional peer dependency so your package continues to work when it is not installed. Also, add it as a development dependency for TypeScript types and tests. Do not add it as a required runtime dependency.

{
  "peerDependencies": {
    "expo-observe": ">=58.0.0"
  },
  "peerDependenciesMeta": {
    "expo-observe": {
      "optional": true
    }
  },
  "devDependencies": {
    "expo-observe": "^58.0.0"
  }
}

把带有 require() 的包放到 try/catch 块里。用 typeof import() 来保留它的 TypeScript 类型：

🌐 Load the package with require() inside a try/catch block. Use typeof import() to preserve its TypeScript types:

let observeModule: typeof import('expo-observe') | undefined;

try {
  observeModule = require('expo-observe') as typeof import('expo-observe');
} catch {
  // The integration remains disabled when expo-observe is not installed.
}

声明集成配置

🌐 Declare the integration configuration

使用声明合并把你的包集成密钥添加到 expo-observe:

🌐 Use declaration merging to add your package's integration key to expo-observe:

export type YourPackageIntegrationConfig = {
  thresholdMs?: number;
};

declare module 'expo-observe' {
  interface ObserveIntegrationsConfig {
    'your-package'?: boolean | YourPackageIntegrationConfig;
  }
}

从你的包入口点导出这个声明，这样当用户导入你的包时 TypeScript 就会加载它。

🌐 Export this declaration from your package entry point so TypeScript loads it when users import your package.

使用你这个包的开发者随后可以启用与 Observe.configure() 的集成：

🌐 Developers using your package can then enable the integration with Observe.configure():

import { Observe } from 'expo-observe';

Observe.configure({
  integrations: {
    'your-package': true,
  },
});

如果这个集成支持选项，开发者可以传一个配置对象，而不是 true：

🌐 If the integration accepts options, developers can pass a configuration object instead of true:

Observe.configure({
  integrations: {
    'your-package': {
      thresholdMs: 1500,
    },
  },
});

注册集成

🌐 Register the integration

使用你的集成密钥调用 Observe.registerIntegration()。回调会收到你的集成配置：

🌐 Call Observe.registerIntegration() with your integration key. The callback receives the configuration for your integration:

export function initObserveIntegration() {
  // The `typeof window` check skips initialization during server-side rendering on web.
  if (typeof window !== 'undefined' && observeModule) {
    const { Observe } = observeModule;

    Observe.registerIntegration('your-package', config => {
      if (config) {
        enableObserveIntegration(config === true ? {} : config);
      }
    });
  }
}

let enabled = false;

function enableObserveIntegration() {
  // Initialize the integration here
  // For example:
  enabled = true;
}

在你的包里实现 enableObserveIntegration()。当未集成或者设置为 false 时，回调不会运行。

🌐 Implement enableObserveIntegration() in your package. The callback does not run when the integration is omitted or set to false.

从你的包入口点调用初始化函数：

🌐 Call the initialization function from your package entry point:

import { initObserveIntegration } from './observe';

export type { YourPackageIntegrationConfig } from './observe.types';

initObserveIntegration();

记录事件

🌐 Log events

当你的包检测到可操作的问题时，调用 Observe.logEvent()。使用小写事件名，第一个部分为包名。使用点号分隔各部分：

🌐 Call Observe.logEvent() when your package detects an actionable issue. Use a lowercase event name with the package name as the first segment. Separate segments with periods:

export function logExpensiveOperation(durationMs: number, thresholdMs: number) {
  if (!observeModule || !enabled) {
    return;
  }

  const { Observe } = observeModule;

  Observe.logEvent('your-package.expensive-operation', {
    severity: 'warn',
    body: 'Reduce the work performed by this operation or increase the configured threshold.',
    attributes: {
      durationMs,
      thresholdMs,
    },
  });
}

想了解更多关于命名事件和添加细节的信息，请参见 用户自定义事件。

🌐 For more information about naming events and adding details, see User-defined events.