# @basis-theory/react-native-threeds 中文文档

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

版本：1\.3\.0
npm 元数据更新时间：2026-11-02T18:33:38.615Z
中文译文更新时间：2026-11-07T18:03:18.249Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：242 kB，154 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：react \*，react-native \>=0\.74\.0，react-native-webview \*
- 首次发布：2025-01-24T19:30:18.575Z
- 最新版本发布：2026-10-02T21:02:56.700Z
- 近 30 天下载量：16313（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：6（近 12 个月 3 个）

## 中文简介

基础理论 3DS 反应原生 SDK

## 安装

```sh
npm install @basis-theory/react-native-threeds
```

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

## README

# 3DS 反应原生 SDK

[![Version](https://img.shields.io/npm/v/@basis-theory/react-native-threeds.svg)](https://www.npmjs.org/package/@basis-theory/react-native-threeds)

这个 [基础理论](https://basistheory.com/) 3DS 反应原生 SDK.

## 安装

使用 [节点软件包管理器](https://docs.npmjs.com/)

```sh
npm install @basis-theory/react-native-threeds
```

使用 [雅伦](https://classic.yarnpkg.com/en/docs/)

```sh
yarn add @basis-theory/react-native-threeds
```

## 使用量

SDK提供三种策略. 他们共享相同的流:对卡进行标记,创建3DS会话,并让后端用您私人的 API 密钥认证.

| 战略 | iOS系统 | 机器人 | 博览去 |
| --- | --- | --- | --- |
| 网络视频 | ✅ | ✅ | ✅ |
| 桥 | ✅ | ✅ | ❌ |
| 涡轮模块 | ✅ | ❌ | ❌ |

本土战略(Bridge和TurboModule)需要发展(`expo prebuild` 或赤裸裸的回放原生应用程序。 博览会 Go 只能使用 WebView.

以下例子如下: `tokenId` 用于您已经创建的纸牌符号, 例如 [反应原生元素](https://developers.basistheory.com/docs/sdks/mobile/react-native/)。 。 。 .

### 网络视频

包装您的应用程序 `BasisTheory3dsProvider` 和使用情况 `useBasisTheory3ds` 在其下方的任何组件中。 提供商将挑战 作为其孩子的顶部, 所以挂在您的应用程序的根部.

```tsx
import { Button } from 'react-native';
import {
  BasisTheory3dsProvider,
  useBasisTheory3ds,
} from '@basis-theory/react-native-threeds';

const App = () => (
  <BasisTheory3dsProvider apiKey="<PUBLIC_API_KEY>">
    <Checkout tokenId="<TOKEN_ID>" />
  </BasisTheory3dsProvider>
);

const Checkout = ({ tokenId }: { tokenId: string }) => {
  const { createSession, startChallenge } = useBasisTheory3ds();

  const pay = async () => {
    const session = await createSession({ tokenId });

    // Your backend authenticates the session with your private API key.
    const authentication = await yourBackend.authenticate(session.id);

    if (authentication.authentication_status_code === 'C') {
      await startChallenge({
        sessionId: session.id,
        acsChallengeUrl: authentication.acs_challenge_url,
        acsTransactionId: authentication.acs_transaction_id,
        threeDSVersion: authentication.threeds_version,
      });
    }
  };

  return <Button title="Pay" onPress={pay} />;
};
```

### 启用本地 3DS

原生地3DS默认关闭,因此WebView-Only apps的构建完全如前:没有原生地代码,没有额外的SDK,没有额外的设置. 要启用它,请将此添加到您的应用程序中 `package.json`数字 :

```json
{
  "@basis-theory/react-native-threeds": {
    "native": true
  }
}
```

然后重建应用程序.

-   **iOS: (英语)** 运行 `pod install`. 它下载了Ravelin的3DS SDK,本地融合使用. 需要iOS 15 或 后期.
    
-   **机器人:** Ravelin的 3DS SDK 需要在您的应用模块中进行两个更改,一个库无法为您做: [核心图书馆](https://developer.android.com/studio/write/java8-support#library-desugaring),并排除 `META-INF` 报告拉维林的OKhttp依赖和AndroidX两艘船.
    
    -   **博览会( E)`expo prebuild`:** 将配置插件添加到 `app.json` 它在每一个建设前都增加了:
        
        ```json
        { "expo": { "plugins": ["@basis-theory/react-native-threeds"] } }
        ```
        
    -   **浅显反射原生,或有承诺的博览会 `android/`数字 :** 将这些行添加到 `android/app/build.gradle`数字 :
        
        ```groovy
        android {
            compileOptions {
                coreLibraryDesugaringEnabled true
            }
            packagingOptions {
                resources {
                    excludes += "META-INF/versions/9/OSGI-INF/MANIFEST.MF"
                }
            }
        }
        
        dependencies {
            coreLibraryDesugaring 'com.android.tools:desugar_jdk_libs:2.1.5'
        }
        ```
        
    
    图书馆自动将拉弗林的马文寄存器添加到您的构建中. 狦 `settings.gradle` 套装 `repositoriesMode` 改为 `PREFER_SETTINGS` 或者说 `FAIL_ON_PROJECT_REPOS`,Gradle忽略或拒绝存储器,所以添加 `https://maven.ravelin.com/public/repositories/threeds2service/` 改为 `dependencyResolutionManagement.repositories` 内 `settings.gradle` 换句话说.
    

只允许 `native` 如果使用的话 `BasisTheoryThreeDS` 或者说 `BasisTheoryThreeDSStrategies`。 仅用WebView的应用程序 `desugar_jdk_libs` 与构造连接,而不连接任何本地 3DS 代码.

### 土著

`BasisTheoryThreeDS` 使用iOS上的涡轮Module 当你的建筑编译它, 和桥 其他任何地方。 不需要供应商。 本地SDK打电话给你 `authenticationEndpoint` 与会话ID,如果银行需要挑战,在您的应用程序上展示.

```tsx
import { useEffect, useState } from 'react';
import { Button } from 'react-native';
import { BasisTheoryThreeDS } from '@basis-theory/react-native-threeds';

const Checkout = ({ tokenId }: { tokenId: string }) => {
  const [ready, setReady] = useState(false);

  useEffect(() => {
    BasisTheoryThreeDS.configure({
      apiKey: '<PUBLIC_API_KEY>',
      // Your backend: receives the session ID and authenticates it with your private API key.
      authenticationEndpoint: 'https://your-backend.example.com/3ds/authenticate',
    }).then(() => setReady(true));
  }, []);

  const pay = async () => {
    const session = await BasisTheoryThreeDS.createSession({ tokenId });
    const result = await BasisTheoryThreeDS.startAuthentication(session.id);
    // result.status: 'successful' | 'attempted' | 'failed' | 'unavailable' | 'rejected'
    //   | 'decoupled_challenge' | 'informational'
  };

  return <Button title="Pay" disabled={!ready} onPress={pay} />;
};
```

失败或取消的挑战解决方式 `status: 'failed'` 和原因在内 `result.details`。 。 。 . `decoupled_challenge` 表示您的应用程序外的发行人认证: 订阅 `3ds.session.decoupled-challenge-notification` 网络浏览以学习完成后, 然后从您的后端获取结果 [获取挑战结果](https://developers.basistheory.com/docs/api/3ds/sessions#get-challenge-result)· ; `informational` 表示没有请求认证. 承诺只在配置,运输,或SDK出错时拒绝.

要强制一个策略,使用 `BasisTheoryThreeDSStrategies.ios.bridge`, (中文(简体) ), `BasisTheoryThreeDSStrategies.ios.turboModule`,或 `BasisTheoryThreeDSStrategies.android.bridge`他们暴露了同样的方法. `ios.turboModule` 需要新建新架构; 请检查 `isThreeDSTurboModuleAvailable()`。 。 。 .

### 选择本土战略

大桥总被编译. TurboModule在iOS上加上了新架构:

-   **iOS: (英语)** 在React Industrial 0.82和后期,涡轮摩多仪总是被编译. 在0.81时, `newArchEnabled` 选择: 在 `app.json` 用于博览会,或 `ios/Podfile.properties.json` (或 `RCT_NEW_ARCH_ENABLED=1 pod install`) (中文(简体) ). `true` 将涡轮摩多尔与大桥并列 `false` 只编译"桥". 运行 `pod install` 改变它之后,它再次.
-   **机器人:** 没有配置。 只有"桥"被编译;Android TurboModule在此包中没有支持.

已测试使用反应原生0.81.5(见 [`example/`](https://npmcn.com/package/%40basis-theory/react-native-threeds/example)) (中文(简体) ).

## 文档

关于终点和例子的完整清单,请参见我们 [正式文件](https://developers.basistheory.com/docs/sdks/mobile/3ds-react-native/)。 。 。 .

## 捐款

见 [贡献指南](https://npmcn.com/package/%40basis-theory/react-native-threeds/CONTRIBUTING.md) 学习如何为储存库和发展工作流程作出贡献.

## 常见问题

### @basis-theory/react-native-threeds 是什么？

基础理论 3DS 反应原生 SDK

### 如何安装 @basis-theory/react-native-threeds？

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

### @basis-theory/react-native-threeds 支持 TypeScript 吗？

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

### @basis-theory/react-native-threeds 支持 ESM 还是 CommonJS？

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

### @basis-theory/react-native-threeds 可以商用吗？

@basis-theory/react-native-threeds 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @basis-theory/react-native-threeds 的下载量有多少？

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

### @basis-theory/react-native-threeds 还在维护吗？

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