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
• 错误跟踪 使用源映射和本地崩溃符号化
• 版本标记、功能开关 和 故障排除

安装并配置 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 更新输出目录。

name: Publish update
on:
  push:
    branches: ['main']
jobs:
  publish_update:
    name: Publish update
    type: update
    params:
      channel: production
  upload_update_sourcemaps:
    name: Upload OTA source maps to PostHog
    needs: [publish_update]
    environment: production
    steps:
      - uses: eas/checkout
      - uses: eas/install_node_modules
      - name: Export JS bundle and source maps
        run: npx expo export --dump-sourcemap --output-dir dist
      - name: Upload source maps to PostHog
        run: npx --yes @posthog/cli@latest hermes upload --directory dist

本地崩溃符号化

🌐 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 注册 超级属性，将每个捕获的事件映射回特定的空中更新：

🌐 Map each captured event back to a specific over-the-air update by registering super properties from expo-updates:

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

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

  useEffect(() => {
    posthog?.register({
      expo_update_id: Updates.updateId,
      expo_channel: Updates.channel,
      expo_runtime_version: Updates.runtimeVersion,
    });
  }, [posthog]);

  return null;
}

在 <PostHogProvider> 内渲染 <ReleaseTagger />。每个后续的 capture() 都具有这些属性，因此你可以在 PostHog 中按 expo_update_id 过滤或分组事件。

🌐 Render <ReleaseTagger /> inside <PostHogProvider>. Every subsequent capture() carries these properties, so you can filter or group events by expo_update_id in PostHog.

功能标记

🌐 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.

管理整合

🌐 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 的功能标记