# @warplink/react-native 中文文档

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

版本：1\.3\.0
npm 元数据更新时间：2026-11-02T20:59:08.988Z
中文译文更新时间：2026-11-02T21:10:54.408Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：434 kB，221 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=18
- 运行依赖：0 个
- peer 依赖：react \>=18\.0\.0，react-native \>=0\.75\.0
- 首次发布：2026-05-16T21:29:33.507Z
- 最新版本发布：2026-11-02T20:59:08.652Z
- 已发布版本数：9（近 12 个月 9 个）

## 中文简介

WarpLink深度链接，为React Native安装归因和实时分析SDK

## 安装

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

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

## README

# @warplink / react-native

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![npm version](https://img.shields.io/npm/v/@warplink/react-native.svg)](https://www.npmjs.com/package/@warplink/react-native) [![CI](https://github.com/WarpLinkApp/warplink-react-native-sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/WarpLinkApp/warplink-react-native-sdk/actions/workflows/ci.yml)

深度链接，安装归因，实时分析React Native。处理通用链接和应用链接，解析延迟的深层链接，以及属性安装 [WarpLink](https://warplink.app/).

## 要求

| 要求 | 最低版本 |
| --- | --- |
| React Native | \> = 0.75.0 |
| 反应 | \> = 18.0.0 |
| iOS | 15 + |
| 安卓 | API 26+ （Android 8.0） |
| node . js | 18 + |

支持两种React Native架构。新建筑是唯一的 从React Native 0.82开始，这就是今天的新应用。这个 Android bridge在每次检查时都针对该范围的两端进行编译 当前的React Native在每个版本中都会在一个设备上运行。

## 安装

### Bare React Native

```bash
npm install @warplink/react-native
```

iOS SDK通过Swift包管理器发布，并由React Native podspec自动拉入。SPM集成需要动态框架，因此将其添加到您的 `ios/Podfile` 在你的应用程序 `target` 布洛克:

```ruby
use_frameworks! :linkage => :dynamic
```

然后安装iOS pods：

```bash
cd ios && pod install
```

Android自动链接通过React Native CLI。不需要额外的设置。

### 世博管理工作流

```bash
npx expo install @warplink/react-native
```

然后生成本地项目：

```bash
npx expo prebuild
```

> **注意：** 这个SDK需要本地模块，并且做了 **不** 与世博合作。您必须使用开发构建(`npx expo prebuild` 或EAS Build)。

## 快速入门

SDK是 **选择退出**裸露的 `configure({ apiKey, onLink })` 电线本身, 热启动，并自动延迟深层链接。所有这三件事都能融入你的生活 `onLink` 回调。否 `useEffect`，无需手动订阅。

延迟的检查将在下一次启动时重试。

```tsx
import { WarpLink } from '@warplink/react-native';

// Call once at app startup, outside any component.
WarpLink.configure({
  apiKey: 'wl_live_yoursdkkeyhere000000000000000000',
  onLink: ({ deepLink, error }) => {
    if (deepLink) {
      // Fires for cold start, warm start, AND deferred (first launch).
      // Disambiguate deferred installs with deepLink.isDeferred.
      navigate(deepLink.deepLinkUrl ?? deepLink.destination);
    } else if (error) {
      console.error('WarpLink error:', error.code, error.message);
    }
  },
}).catch((e) => console.error('WarpLink configure failed:', e));
```

这就是整个快乐之路。 `onLink` 接收应用程序看到的每个深度链接。

### 获取SDK密钥

`apiKey` 以一个 **SDK关键**，创建于 **键** > **SDK键** 在 仪表板。它预先限定了链接解析和安装属性的作用域。API密钥 是后端脚本、CI和AI代理的单独凭证，而它们不能 安装记录。两者共享 `wl_live_` 前缀，所以在这里粘贴API密钥是 一个容易犯的错误：深度链接一直在解析，但没有安装出现在您的 仪表板。看到 [集成指南](https://npmcn.com/package/%40warplink/react-native/docs/integration-guide.md) 完整的 预排。

### 所需的本机主机设置

两个原生钩子是 **要求** 获取深层链接以获取SDK。它们不是 可选的。

-   **iOS:** 你的 `AppDelegate` 必须将传入的url转发到 `WarpLinkModule.handleIncomingURL(url)`，为SDK提供iOS Universal Links。看到 [iOS主机钩子](https://npmcn.com/package/%40warplink/react-native/docs/integration-guide.md#ios-host-hook)。如果 你的应用程序声明 `UIApplicationSceneManifest` 并且有一个 `SceneDelegate` (这是普通Xcode模板的默认值，也是苹果应用程序的要求 使用更新的sdk（没有sdk就无法启动），也是一样的 Forward也需要在 `SceneDelegate`： iOS停止调用 `AppDelegate` 一旦一个场景存在，就完全挂钩。看到 [iOS SceneDelegate钩子](https://npmcn.com/package/%40warplink/react-native/docs/integration-guide.md#ios-scenedelegate-hook).
-   **Android:** 你的启动活动必须声明 `android:launchMode="singleTask"` 所以预热启动意图到达SDK。看到 [安卓系统设置](https://npmcn.com/package/%40warplink/react-native/docs/integration-guide.md#android-launchmode).

### 使用自定义链接域

`aplnk.to` 开箱即用。如果您的链接在您自己的域上，请声明它 SDK会在第一次启动时识别它，在它获取你的 域名列表，甚至没有网络：

```tsx
WarpLink.configure({
  apiKey: 'wl_live_yoursdkkeyhere000000000000000000',
  linkDomains: ['links.yourapp.com'],
  onLink: handleLink,
});
```

相同的声明可以存在 `Info.plist` （`WarpLinkDomains`)或Android 清单(`app.warplink.DOMAINS`)。所有的源都被合并，所以声明 在不止一个地方是安全的。看到 [自定义链路域](https://npmcn.com/package/%40warplink/react-native/docs/api-reference.md#custom-link-domains).

### 测试第一次安装

一、 `wl_test_` 键将其属性状态与 `wl_live_` 状态在同一设备上。在调试构建中使用Test键。要在不删除应用程序的情况下再次测试首次安装，请调用 `WarpLink.clearAttribution()` 使用测试键。它清除存储在设备上的属性并开始新的检查。它对活键不起任何作用。

### 使任何部件失效

每个源都是独立禁用的。关掉一个，自己接好线。

```tsx
WarpLink.configure({
  apiKey: 'wl_live_yoursdkkeyhere000000000000000000',
  onLink: handleLink,
  automaticDeepLinks: false,          // you call onDeepLink()/getInitialDeepLink()
  automaticDeferredDeepLinks: false,  // you call checkDeferredDeepLink()
});
```

省略 `onLink` 完全保留手动模式的深度链接。两件事 从1.0.x更改： `configure()` 不再抛出一个错误的键（它报告） 通过 `onLink` 而不是控制台警告)，以及 `AttributionResult.installId` 被删除。pre-1.1 API中的其他所有内容都没有改变，仍然受到支持。 延期的支票仍然会触发， 因为这个请求是什么属性的安装；呼叫 `checkDeferredDeepLink()` 读比赛，还是通过 `automaticDeferredDeepLinks: false` 关闭复选框：

```tsx
WarpLink.configure({ apiKey: 'wl_live_yoursdkkeyhere000000000000000000' });

function App() {
  useEffect(() => {
    const unsubscribe = WarpLink.onDeepLink(({ deepLink }) => {
      if (deepLink) navigate(deepLink.destination);
    });
    WarpLink.getInitialDeepLink().then((l) => l && navigate(l.destination));
    WarpLink.checkDeferredDeepLink().then((l) => l?.isDeferred && navigate(l.destination));
    return unsubscribe;
  }, []);
  return <>{/* Your app */}</>;
}
```

## 功能

-   **默认选择退出：** 一个 `configure({ apiKey, onLink })` 调用开启冷启动、热启动和延迟深度链接。每个都是独立的残疾。
-   **通用链接和应用程序链接处理：** 解析到目的地和自定义参数的传入深层链接。看到 [集成指南](https://npmcn.com/package/%40warplink/react-native/docs/integration-guide.md).
-   **延迟深度链接：** 即使在App Store或Play Store安装之后，也要引导用户访问特定内容。看到 [延迟深度链接](https://npmcn.com/package/%40warplink/react-native/docs/deferred-deep-links.md).
-   **安装归因:** 确定性和概率匹配与置信度得分。看到 [归因](https://npmcn.com/package/%40warplink/react-native/docs/attribution.md).
-   **跨平台的:** iOS和Android的单一TypeScript API，带有特定平台的原生桥。
-   **不需要ATT：** 在iOS上使用IDFV（不受应用跟踪透明度的限制）。没有IDFA，没有用户提示。
-   **调试日志:** 使与 `{ debugLogging: true }` 在配置选项中跟踪SDK行为。
-   **原生SDK版本：** `await WarpLink.sdkVersion()` 返回本机SDK报告的版本。
-   **归因完成:** `await WarpLink.isAttributionComplete()` 告诉您此安装的延迟检查是否已确定完成。
-   **零依赖关系:** 没有第三方运行时依赖项。只依赖于 `react` 和 `react-native`.

## 文档

| 指南 | 描述 |
| --- | --- |
| [集成指南](https://npmcn.com/package/%40warplink/react-native/docs/integration-guide.md) | 从零到工作深度链接的逐步设置 |
| [API参考](https://npmcn.com/package/%40warplink/react-native/docs/api-reference.md) | 所有公共类型和方法的完整参考 |
| [延迟深度链接](https://npmcn.com/package/%40warplink/react-native/docs/deferred-deep-links.md) | 延迟深度链接是如何工作的以及如何使用它 |
| [归因](https://npmcn.com/package/%40warplink/react-native/docs/attribution.md) | 安装归因层和信心评分 |
| [错误处理](https://npmcn.com/package/%40warplink/react-native/docs/error-handling.md) | 每个错误案例以及推荐的恢复操作 |
| [故障排除](https://npmcn.com/package/%40warplink/react-native/docs/troubleshooting.md) | 常见问题和解决方案 |
| [重火力点迁移](https://npmcn.com/package/%40warplink/react-native/docs/firebase-migration.md) | 从Firebase动态链接迁移到WarpLink |
| [体系结构](https://npmcn.com/package/%40warplink/react-native/docs/architecture.md) | SDK如何与本地iOS和Android SDK连接 |

## 链接

-   [WarpLink仪表板](https://warplink.app/)
-   [更新日志](https://npmcn.com/package/%40warplink/react-native/CHANGELOG.md)

## 许可证

麻省理工学院的许可。看到 [许可证](https://npmcn.com/package/%40warplink/react-native/LICENSE) 获取详细信息。

## 常见问题

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

WarpLink深度链接，为React Native安装归因和实时分析SDK

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

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

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

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

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

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @warplink/react-native 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=18。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

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

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

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

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