# @aptabase/react-native 中文文档

规范地址：https://npmcn.com/package/%40aptabase/react-native/

版本：0\.6\.0
npm 元数据更新时间：2026-08-17T06:01:56.425Z
中文译文更新时间：2026-11-06T12:55:55.955Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40aptabase/react-native
原文对照：https://npmcn.com/package/%40aptabase/react-native/?lang=original
项目主页：https://github.com/aptabase/aptabase-react-native
源码仓库：https://github.com/aptabase/aptabase-react-native

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：75.5 kB，16 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：react \>=19\.1\.0，react-native \>=0\.81\.4
- 首次发布：2023-05-26T20:58:00.947Z
- 最新版本发布：2026-08-17T06:01:55.466Z
- 近 30 天下载量：17832（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：21（近 12 个月 3 个）

## 中文简介

Aptabase 的回放原生 SDK : 开放源代码、 隐私第一和简单分析 移动、桌面和网络应用程序

## 安装

```sh
npm install @aptabase/react-native
```

也可以使用：`pnpm add @aptabase/react-native`、`yarn add @aptabase/react-native`、`bun add @aptabase/react-native`

## README

![Aptabase](https://aptabase.com/og.png)

# Aptabase 反应原生 SDK

使用 Aptabase 、 开源、 隐私第一和简单分析的移动、 桌面和 Web Apps 设备.

## 安装

使用 SDK 安装 `npm` 或您的首选 JavaScript 软件包管理器

```bash
npm add @aptabase/react-native
```

## 机器人要求

如果你的目标是Android,你需要增加以下权限: `AndroidManifest.xml`数字 :

```xml
<uses-permission android:name="android.permission.INTERNET" />
```

## 网络支持

此 SDK 也支持 React Environment Web !

> \[注\] 此特性默认已禁用 。 要让它生效,你需要通过 `enableWeb` 选项.

```js
Aptabase.init("<YOUR_APP_KEY>", {
  enableWeb: true,
  appVersion: "1.0.0", // required on web — no native module provides it
});
```

启用后,SDK将使用与Web SDK相同的行为来追踪网络环境中的事件. 也就是说事件会立即送到 `/event` 结尾而不是组合到 `/events` 终点.

## 使用量

首先,你必须得到你的 `App Key` 从Aptabase可以找到它 `Instructions` 菜单.

通过调用 SDK 初始化 `init` 函数在声明您的 `App` 组件 :

```js
import Aptabase from "@aptabase/react-native";

Aptabase.init("<YOUR_APP_KEY>"); // 👈 this is where you enter your App Key

export default function App() {
  return <Counter />;
}
```

之后,你可以开始跟踪事件 `trackEvent`数字 :

```js
import { trackEvent } from "@aptabase/react-native";
import { useState } from "react";

export function Counter() {
  const [count, setCount] = useState(0);

  const increment = () => {
    setCount(count + 1);
    trackEvent("increment", { count });
  };

  const decrement = () => {
    setCount(count - 1);
    trackEvent("decrement", { count });
  };

  return (
    <View>
      <Button onPress={increment} title="Increment" />
      <Button onPress={decrement} title="Decrement" />
      <Text>Count is {count}</Text>
    </View>
  );
}
```

要禁用跟踪事件, 您可以调用 `dispose` 函数。 这将停止并解除SDK的初始化.

```js
import Aptabase from "@aptabase/react-native";

Aptabase.dispose();
```

**博览会应用说明 :** 在 Expo Go 上运行时在开发过程中发送的事件不会有 `App Version` 属性,因为在 Expo Go 中没有本地模块。 然而,当你建立你的应用 运行在一个真正的设备 `App Version` 属性将可用。 或者,您也可以设置 `appVersion` 期间 `init` 在开发期间也可以使用.

几个重要说明:

1.  SDK会用一些有用的信息自动增强事件,如OS,app版本等.
2.  你控制着被送到阿普塔基地的东西 此 SDK 不自动跟踪任何事件, 您需要呼叫 `trackEvent` 手动.
    -   因此,一般建议在启动时至少跟踪一个事件
3.  你不需要等待着 `trackEvent` 函数,会在后台运行.
4.  只允许自定义属性上的字符串和数字值

## 报告错误

> 错误报告在β中. 报告出现在 `Errors` 你的Aptabase仪表板的一页.

使用 `trackError` 报告你发现和处理的错误:

```js
import { trackError } from "@aptabase/react-native";

try {
  await doSomething();
} catch (error) {
  trackError(error); // severity: error
}
```

对于您的应用程序无法恢复的错误, 请将报告标为致命 :

```js
trackError(error, { fatal: true }); // severity: fatal
```

同时自动报告未发现的错误和相撞, 并允许在 `init`数字 :

```js
Aptabase.init("<YOUR_APP_KEY>", {
  enableCrashReporting: true,
});
```

关于错误报告的几个重要说明:

1.  每份报告包括错误类型、消息、堆栈跟踪、严重性(`error` 或者说 `fatal`及其如何被俘获(`handled`, (中文(简体) ), `unhandled` 或者说 `crash`) (中文(简体) ).
2.  在原生时,立即发送报告,并保存在记忆中,以便在网络无法使用时进行重试。 在网络上,立即发送报告,不重复(网络要求 `enableWeb` 选项).
3.  错误以单独的每月错误配额计算 。 当配额用完后,服务器拒绝新的报告,直到它重新发送.
4.  被 React Error 捕获出错误 边界永远不会到达全局错误处理器 – call `trackError` 如果需要报告,请从边界上报到.
5.  原生(非JS)相撞没有被捕获. 在开发过程中,致命的JS错误显示RedBox而不是崩溃了应用程序.

## 准备提交 App Store

在向苹果App Store提交应用程序时,需要填写 `App Privacy` 形式。 你可以找到我们所有的答案 [使用 Aptabase 时如何填写 App 隐私](https://aptabase.com/docs/apple-app-privacy) 向导.

AI/LLM整合说明见 [页:1](https://npmcn.com/package/%40aptabase/react-native/llms.txt)

## 常见问题

### @aptabase/react-native 是什么？

Aptabase 的回放原生 SDK : 开放源代码、 隐私第一和简单分析 移动、桌面和网络应用程序

### 如何安装 @aptabase/react-native？

在项目目录运行 npm install @aptabase/react-native，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（\>=19\.1\.0）、react-native（\>=0\.81\.4）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @aptabase/react-native 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @aptabase/react-native 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @aptabase/react-native 可以商用吗？

@aptabase/react-native 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @aptabase/react-native 的下载量有多少？

根据 npm 官方下载统计，@aptabase/react-native 在 2026/10/07 – 2026/11/05 这 30 天内被下载 17,832 次，日均约 594 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @aptabase/react-native 还在维护吗？

最新版本 0\.6\.0 发布于 2026/08/17（2 个月前）；至今共发布 21 个版本，其中过去 12 个月发布了 3 个；首次发布于 2023/05/27。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。