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

关于安装和配置 PostHog 用于产品分析、会话回放和错误跟踪的指南。

PostHog 是一个具有会话回放、功能标志和错误跟踪的产品分析平台。

EAS CLI 集成自动化了标准的 PostHog React Native 设置：安装 SDK、创建 PostHog 组织和项目，以及配置环境变量。你也可以手动设置并使用本指南的其他部分而无需更改。

🌐 The EAS CLI integration automates the standard PostHog React Native setup: installing the SDK, creating a PostHog organization and project, and configuring your environment variables. You can also set it up manually and use the rest of this guide unchanged.

你将学到什么

🌐 What you'll learn

本指南涵盖了将 PostHog 集成到你的 Expo 项目中：

🌐 This guide covers integrating PostHog with your Expo project:

• 在你的 React Native 应用中安装和配置 PostHog
• 错误跟踪 使用源映射和本地崩溃符号化
• 发布标签、标准 EAS 属性、功能标记 和 故障排除

安装并配置 PostHog

🌐 Install and configure PostHog

import { PostHogProvider } from 'posthog-react-native';
import { Slot } from 'expo-router';

export default function RootLayout() {
  return (
    <PostHogProvider
      apiKey={process.env.EXPO_PUBLIC_POSTHOG_API_KEY}
      options={{
        host: process.env.EXPO_PUBLIC_POSTHOG_HOST,
        enableSessionReplay: false, // set to true if you enabled session replay
        // Capture JS exceptions (remove if you didn't enable error tracking):
        errorTracking: {
          autocapture: { uncaughtExceptions: true, unhandledRejections: true },
        },
        // disabled: __DEV__, // uncomment to stop sending events from development builds
      }}>
      <Slot />
    </PostHogProvider>
  );
}

import { Button } from 'react-native';
import { usePostHog } from 'posthog-react-native';

// Inside a component
const posthog = usePostHog();
<Button title="发送测试事件" onPress={() => posthog?.capture('test_event')} />

错误跟踪

🌐 Error tracking

如果你启用了错误追踪，PostHog 会符号化两个不同的东西，并且你是独立设置它们的：

🌐 If you enabled error tracking, PostHog symbolicates two separate things, and you set them up independently:

• JavaScript 源映射 用于 JS/TS 异常，包括 Hermes 字节码。请参阅 Source maps。
• 本地调试符号 用于本地 Android 和 iOS 崩溃（ProGuard/R8 映射和 dSYM 文件）。可选。参见 本地崩溃符号化。

源映射

🌐 Source maps

源映射可以使 JavaScript 堆栈跟踪（包括 Hermes 字节码）指向你的原始源代码，而不是压缩后的输出。

🌐 Source maps make JavaScript stack traces (including Hermes bytecode) point to your original source instead of minified output.

首先，设置注入，以便每个包都被标记为上传。在项目根目录下将此内容添加到 metro.config.js（如果文件不存在，请创建它）:

🌐 First, set up injection so each bundle is tagged for upload. Add this to metro.config.js in your project root (create the file if it doesn't exist):

const { getPostHogExpoConfig } = require('posthog-react-native/metro');

const config = getPostHogExpoConfig(__dirname);

module.exports = config;

如果你已经自定义了你的 Metro 配置（例如，使用 NativeWind 或在 monorepo 中），请将你的更改应用到 getPostHogExpoConfig 返回的 config 对象上，而不是自己调用 getDefaultConfig。

🌐 If you already customize your Metro config (for example, with NativeWind or in a monorepo), apply your changes to the config object that getPostHogExpoConfig returns instead of calling getDefaultConfig yourself.

PostHog 的 CLI 使用 connect 设置的 POSTHOG_CLI_* 环境变量进行身份验证。要从你自己的机器上传，请改为运行 posthog-cli login。

🌐 PostHog's CLI authenticates with the POSTHOG_CLI_* environment variables that connect set. To upload from your own machine, run posthog-cli login instead.

在 EAS Build 上，posthog-react-native/expo 配置插件会在 Android（Gradle）和 iOS（Xcode）构建阶段自动上传源映射，因此不需要运行额外的命令。

关于 EAS 更新，空中更新只发送 JavaScript，所以每次更新后只需上传它们的源映射（本地符号在构建时固定）。安装 PostHog 的 CLI，然后一次导出一个平台并上传它的映射：

dist 是 EAS Update 的默认输出目录。每次上传只导出一个平台：PostHog 会上传原生（Hermes）源码映射，所以 dist 中的 web bundle 不会被处理。

本地崩溃符号化

🌐 Native crash symbolication

可选。本地崩溃（与 JavaScript 异常相对）需要在构建时上传本地调试符号。posthog-react-native/expo 插件在你选择加入后可以在 EAS Build 期间完成此操作：

🌐 Optional. Native crashes (as opposed to JavaScript exceptions) need native debug symbols uploaded at build time. The posthog-react-native/expo plugin can do this during EAS Build once you opt in:

{
  "expo": {
    "plugins": [["posthog-react-native/expo", { "uploadNativeSymbols": true }]]
  }
}

这是三个必需环节之一：构建时符号上传（如上所述）、在你的提供商中进行原生崩溃自动捕获，以及在你的 PostHog 项目中设置异常自动捕获。有关完整设置，请参阅 PostHog 的原生崩溃自动捕获。

🌐 This is one of three pieces required end to end: build-time symbol upload (above), native crash autocapture in your provider, and the exception-autocapture setting in your PostHog project. See PostHog's native crash autocapture for the full setup.

发布标签

🌐 Release tagging

通过从expo-updates和expo-constants注册超级属性，将每个捕获的事件映射回产生它的更新、项目和账户：

🌐 Map each captured event back to the update, project, and account that produced it by registering super properties from expo-updates and expo-constants:

import { useEffect } from 'react';
import Constants from 'expo-constants';
import * as Updates from 'expo-updates';
import { usePostHog } from 'posthog-react-native';

function ReleaseTagger() {
  const posthog = usePostHog();

  useEffect(() => {
    posthog?.register({
      'eas/update_id': Updates.updateId,
      'eas/channel': Updates.channel,
      'eas/runtime_version': Updates.runtimeVersion,
      'eas/project_id': Constants.expoConfig?.extra?.eas?.projectId,
      'eas/account': Constants.expoConfig?.owner,
    });
  }, [posthog]);

  return null;
}

在 <PostHogProvider> 内渲染 <ReleaseTagger />。每个后续的 capture() 都会携带这些属性，所以你可以在 PostHog 中按 eas/update_id 过滤或分组事件。只有当你的 应用配置 设置了 owner 时，eas/account 才有值。eas/update_id 和 eas/channel 仅在发布版和预览版中设置。在 Expo Go 和开发版本中，它们是 null，所以这些版本的事件不会携带它们。

🌐 Render <ReleaseTagger /> inside <PostHogProvider>. Every subsequent capture() carries these properties, so you can filter or group events by eas/update_id in PostHog. eas/account has a value only when your app config sets owner. eas/update_id and eas/channel are set only in release and preview builds. In Expo Go and development builds they are null, so events from those builds do not carry them.

标准 EAS 属性

🌐 Standard EAS properties

PostHog 能识别这些 eas/ 名称。它会在每个名称旁边显示 Expo 标志，并将带有标识符的名称链接到它们在 expo.dev 上的页面。每个值的来源取决于事件是在你的应用中触发还是在工作流中触发：

🌐 PostHog recognizes these eas/ names. It shows the Expo logo next to each and links the ones that carry an identifier to their page on expo.dev. Where each value comes from depends on whether the event fires in your app or in a workflow:

ReleaseTagger 代码片段会从 expo-updates 和 expo-constants 设置应用内的值。在工作流里，在 eas/posthog_capture_event 上设置同样的名字：eas/account、eas/project_id 和 eas/workflow_id 来源于 account、app 和 workflow 的上下文，每个任务都可以读取。构建和更新字段来自构建或更新任务的输出。 recipes 展示了这个上下文。eas/update_id 是应用中的单个更新 ID，在工作流里是更新组 ID，一个发布会生成一组特定平台的更新。两者都会在 expo.dev 上打开更新。

🌐 The ReleaseTagger snippet sets the in-app values from expo-updates and expo-constants. In a workflow, set the same names on eas/posthog_capture_event: eas/account, eas/project_id, and eas/workflow_id come from the account, app, and workflow contexts, which every job can read. The build and update fields come from a build or update job's outputs. The recipes show this in context. eas/update_id is the individual update ID in the app and the update group ID in a workflow, where one publish produces a group of platform-specific updates. Both open the update on expo.dev.

功能标记

🌐 Feature flags

一旦提供者设置完成，功能开关无需额外配置即可工作。请参阅 PostHog 的 React Native 功能开关 和 引导 以避免应用启动时的网络往返。

🌐 Once the provider is set up, feature flags work with no extra configuration. See PostHog's feature flags for React Native and bootstrapping to avoid a network round-trip on app start.

在 EAS 工作流程中的使用

🌐 Usage with EAS Workflows

EAS 工作流 可以让你的 CI 管道与 PostHog 互动。你可以在工作流步骤中发送事件、创建注释、发布功能标志、根据实时指标控制发布，并上传源映射。这些步骤会自动读取 connect 设置的 EXPO_PUBLIC_POSTHOG_* 和 POSTHOG_CLI_* 环境变量。有关每个步骤的完整输入参考，请参见 EAS 工作流语法参考中的 PostHog 函数。

管理整合

🌐 Manage the integration

稍后使用这些命令来管理集成：

🌐 Use these commands to manage the integration later:

dashboard 打开你已关联的 PostHog 项目。disconnect 仅移除 Expo 端的链接。你的 PostHog 组织、项目和数据保持不变。

手动设置

🌐 Manual setup

connect 是标准 PostHog React Native 设置的快捷方式。要手动操作，请按照 PostHog 的 React Native 安装指南 进行，然后设置 EXPO_PUBLIC_POSTHOG_API_KEY 和 EXPO_PUBLIC_POSTHOG_HOST（以及用于源映射的 POSTHOG_CLI_* 变量）。按照 步骤 2 所示，将你的应用封装在 <PostHogProvider> 中。有关源映射，请参阅 Source maps。

故障排除

🌐 Troubleshooting

了解更多

🌐 Learn more

• PostHog React Native 库
• 适用于 React Native 的产品分析
• React Native 的错误追踪
• 适用于 React Native 的会话回放
• 为 React Native 上传源地图
• React Native 的功能标记