# @exodus/react-native-wallet 中文文档

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

版本：0\.1\.19
npm 元数据更新时间：2026-10-06T21:03:07.065Z
中文译文更新时间：2026-11-14T04:05:20.212Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：2.2 MB，211 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：react \*，react-native \*
- 首次发布：2026-02-03T07:55:33.160Z
- 最新版本发布：2026-05-07T14:15:22.804Z
- 近 30 天下载量：12167（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：4（近 12 个月 4 个）

## 中文简介

一个反应原生模块,旨在将卡推提供无缝地集成到苹果钱包和Google钱包中,从而能够从您的应用程序直接方便和安全地添加支付卡.

## 安装

```sh
npm install @exodus/react-native-wallet
```

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

## README

![@expensify/react-native-wallet](https://npmcn.com/package/%40exodus/react-native-wallet/assets/hero-image.png)

## 特征

-   提供无缝集成
-   QQ通用解决方案( Apple 钱包和 Google 钱包)
-   QQ 直接从您的应用程序中轻松安全地添加支付卡
-   \* 支持签证、万事达卡、Amex和发现支付卡

## 开始

使用 `react-native-wallet` Push提供功能需要Google和Apple进行适当的配置和访问. 在安装库前请遵循以下指示 :

### 机器人

要与Google钱包在Android上互动,请确保完成以下所有步骤: [google Push 提供文档](https://developers.google.com/pay/issuers/apis/push-provisioning/android/setup)数字 :

#### 第1步:进入Google TapAndPay SDK

1.  访问 [google Pay Android Push 提供 API 文件](https://developers.google.com/pay/issuers/apis/push-provisioning/android/) 并请求访问它.
    
2.  一旦得到谷歌团队的批准
    
    1.  下载 [磁带Pay SDK](https://developers.google.com/pay/issuers/apis/push-provisioning/android/releases)。 。 。 .
    2.  解开并取出SDK `/android/libs` 在您的 React 原生项目中的文件夹( 如果没有) `libs` 文件夹,创建一个).
    3.  添加 `/android/libs` 改为 `.gitignore`。 。 。 .
3.  然后连接 SDK 到您的工程 `build.gradle`,例如,在 [实例/机器人/建造.gradle](https://github.com/Expensify/react-native-wallet/blob/main/example/android/build.gradle)数字 :
    

```groovy
allprojects {
    repositories {
        google()
        maven { url "file://${rootDir}/libs" }
    }
}
```

#### 第二步:将您的应用程序白列一等,供SDK使用.

要在您的应用中使用Google SDK, 您需要将您的应用细节白名单 。 没有它,调用一些功能将导致 `Not verified` 错误. 为了解决问题,请遵照我的指示 [官方 Google 文档](https://developers.google.com/pay/issuers/apis/push-provisioning/android/allowlist)。 。 。 .

为了你的建筑,你需要准备你的应用软件 `package name` 财务报告和审定财务报表 `fingerprint` 如下 [这些步骤](https://developers.google.com/pay/issuers/apis/push-provisioning/android/allowlist#how_to_get_your_apps_fingerprint)例如,这些价值应该是这样的:

```
Package name: com.app.package.name

Fingerprint: SHA256: 36:38:63:59:6E:...:00:82:16:4E:FF
```

> \[TIP\] 您可以使用 SHA-256 证书校验和 `apksigner` 或者说 `keytool`。 。 。 .

以所有需要的数据提交表格并等待Google的回应. 成功将您的应用程序白化后, 您将可以在我们的库中使用 Google SDK .

* * *

### iOS系统

### 步骤1:申请适当的应享权利

为了在您的应用程序中启用 In-App Proference, 您必须请求激活您的开发者团队ID 的 Apple Pay 应享权利 。 企业队身份证明不支持. 在我们的面板中默认无法提供此项权利;您需要请求。 发送电子邮件到 [苹果支付提供@apple.com](mailto:apple-pay-provisioning@apple.com) 还有你的应用名称 团队身份和亚当身份.

一旦苹果验证你的身份, 你应该得到文件命名 `Getting Started with Apple Pay In-App Provisioning, Verification & Security`在此机密文件中,您将找到与下列事项有关的所有相关信息:

-   您的项目的前提条件
-   应遵循的最佳做法
-   内部辅助提供如何运作
-   UX 要求
-   测试过程
-   还有...

在应用您的应用程序前, 请先熟悉该文件 .

### 步骤2:启动权利

在得到苹果公司的积极回应后,打开开发者门户网站面板并搜索 `Certificates, Identifiers & Profiles` - > (中文) `Profiles` - > (中文) `Our distribution profile` - > (中文) `Edit` 并添加 `ApplePay In-App Provisioning Distribution` 权利. 您必须使用物理设备和卡片.

### 步骤3:在项目中添加应享权利

添加 `com.apple.developer.payment-pass-provisioning` 有权享受您的项目。 查找或创建 `.entitlements` 在您的工程中, 并添加下面的应享权利( 类似于 [钱包实例](https://github.com/Expensify/react-native-wallet/blob/main/example/ios/WalletExample/WalletExample.entitlements):

```xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    ...
     <!-- In-App Provisioning special entitlement-->
    <key>com.apple.developer.payment-pass-provisioning</key>
    <true/>
</dict>
</plist>
```

## 安装

在完成上面一节的设置后,安装 `react-native-wallet` npm 软件包 :

```sh
npm install @expensify/react-native-wallet
```

或者说

```sh
yarn add @expensify/react-native-wallet
```

## 所需数据

您可以在这里找到库中使用的数据元素, 这是与 Google 钱包和 Apple 钱包 API 合作的关键 .

### 机器人

-   **不透明支付卡** (OPC) - 一个二进制的Google Pay从发行方的app收到信息,可以提交TSP接收一个指使.
-   **托肯服务提供人** (TSP)-一种服务,通过在交易中将信用卡号码替换为独特的数字标识-符号来增强支付安全. TSP指定了用于创建给定代号的代号服务,例如Visa, MasterCard, American Express.
-   **托肯引用编号** - 一个独特的识别号码,用于指代一个DPAN(动态个人账户号码)。 Token提供商将在发证时为每个DPAN指定一个发证人代号ID.

### iOS系统

-   **诺斯** - 苹果公司服务器产生的一次性非ce值。 此非ce必须包含在附加付款请求的加密数据中.
-   **非签名** - 非ce设备专用签名。 此签名必须包含在附加付款请求的加密数据中 .
-   **证书** - 一系列NSData对象。 每个对象包含一个编码为X.509的DER证书,其中叶子为先,根为后. 您必须下载根 CA 以验证整个链条 .
-   **加密的通过数据**\- 一个加密的JSON文件,其中包含在Apple Pay中添加一卡所需的敏感信息(Base 64被编码). [更多细节在这里.](https://developer.apple.com/documentation/passkit/pkaddpaymentpassrequest/encryptedpassdata)
-   **电子公钥** - 椭圆曲线密码学(ECC)(Base 64编码)所使用的密钥.

# API 参考

库提供7个功能,用于Apple钱包和Google钱包API的无缝集成和使用. 此外,它还包括一名听众,负责告知加卡何时启用。 下文介绍这些功能以及所涉及的数据类型.

## 职能

| 函数 | 说明 | 参数 | 返回/类型 | iOS系统 | 机器人 |
| :-: | :-: | --- | --- | --- | :-: |
| **获取安全钱包信息** | 返回安全交易所需的平台专用钱包信息. | 无 | `WalletData` | ❌ | ✅ |
| **检查Wallet的可用性** | 检查钱包是否准备好, 并尽可能初始化 . | 无 | `boolean` | ✅ | ✅ |
| **获取CardStatusBy后缀** | 获取钱包中卡片的当前状态. | `lastDigits: string`  
(牌号的最后几个数字) | `CardStatus` | ✅ | ✅ |
| **获取卡片状态识别符** | 返回基于特定平台标识符的卡片状态。 在Android上,这是 `Token Reference ID` 在iOS上,这是 `Primary Account Identifier`。 。 。 . | `identifier: string`, (中文(简体) ),  
`tsp: string` | `CardStatus` | ✅ | ✅ |
| **添加标记到 GoogleWallet** | 启动本地 Push 程序, 用于在 Google 钱包中添加卡片 . | `data`数字 : `AndroidCardData` | `TokenizationStatus` | ❌ | ✅ |
| **恢复AddCardTo GoogleWallet 服务器** | 恢复使用已存在的代号引用ID在Google钱包上添加一卡片的Push提供流. | `data`数字 : `AndroidResumeCardData` | `TokenizationStatus` | ❌ | ✅ |
| **列表脚本** | 列出目前存储在Google钱包中的所有令牌. | 无 | `TokenInfo[]` | ❌ | ✅ |
| **添加卡通AppleWallet** | 启动本地 Push 提供流程, 用于在 Apple 钱包中添加一卡 . | `data`数字 : `IOSCardData`, (中文(简体) ),  
`issuerEncrypt-`  
`PayloadCallback: IOSIssuerCallback` | `void` | ✅ | ❌ |

## 数据类型

| 类型 | 说明 | 字段 |
| :-: | :-: | --- |
| **Android Wallet 数据** | 钱包交易所需的Android设备的具体信息. | `deviceID: string`, (中文(简体) ),  
`walletAccountID: string` |
| **Android 卡尔达塔** | 数据与Android平台钱包上要添加的卡片有关. | `network: string`, (中文(简体) ),  
`opaquePaymentCard: string`, (中文(简体) ),  
`cardHolderName: string`, (中文(简体) ),  
`lastDigits: string`, (中文(简体) ),  
`userAddress: UserAddress` |
| **Android ResumeCardData (英语)** | 使用已存在的代号参考ID恢复给Google钱包加卡的简化数据结构. | `network: string`, (中文(简体) ),  
`tokenReferenceID: string`, (中文(简体) ),  
`cardHolderName?: string`, (中文(简体) ),  
`lastDigits?: string` |
| **用户地址** | 用于验证持卡人的结构地址. | `name: string`, (中文(简体) ),  
`addressOne: string`, (中文(简体) ),  
`addressTwo: string`, (中文(简体) ),  
`city: string`, (中文(简体) ),  
`administrativeArea: string`, (中文(简体) ),  
`countryCode: string`, (中文(简体) ),  
`postalCode: string`, (中文(简体) ),  
`phoneNumber: string` |
| **IOSCardData 数据** | 数据涉及一张将在iOS平台上添加的卡片. | `network: string`, (中文(简体) ),  
`activationData: string`, (中文(简体) ),  
`encryptedPassData: string`, (中文(简体) ),  
`ephemeralPublicKey: string`, (中文(简体) ),  
`cardHolderTitle: string`, (中文(简体) ),  
`cardHolderName: string`, (中文(简体) ),  
`lastDigits: string`, (中文(简体) ),  
`cardDescription: string`, (中文(简体) ),  
`cardDescriptionComment: string` |
| **已经激活 有效载荷** | 当卡片状态发生变化时,收听者会使用数据通知. | `tokenId: string`, (中文(简体) ),  
`actionStatus: 'activated' | 'canceled'`  
 |
| **IOS Issuer 调回** | 这种回调被用一个非ce,它的签名,以及从苹果公司获得的证书阵列来引用. 预计将将这些细节转发到您的服务器或发卡人的API,以安全加密在苹果钱包上加卡所需的有效载荷. | `(nonce: string, nonceSignature: string, certificate: string[]) => IOSEncryptPayload` |
| **IOS Encrypt Payload (英语)** | 包含完成Apple Walet所添加卡片的必要元素的对象. | `encryptedPassData: string`, (中文(简体) ),  
`activationData: string`, (中文(简体) ),  
`ephemeralPublicKey: string` |
| **托肯信息** | 谷歌钱包中存储的一款代币信息. | `identifier: string`, (中文(简体) ),  
`lastDigits: string`, (中文(简体) ),  
`tokenState: number` |

## 卡片状态

| 类型 | 可能值 |
| :-: | :-: |
| **卡片状态** | `not found`, (中文(简体) ), `active`, (中文(简体) ), `requireAuthorization`, (中文(简体) ), `pending`, (中文(简体) ), `suspended`, (中文(简体) ), `deactivated` |

## 听众

| 听众 | 事件描述 | 注册函数 | 未注册函数 |
| :-: | :-: | --- | --- |
| **_卡片活动_** | 当卡片状态改变为激活时通知. | `addListener(event: string, callback: (data: onCardActivatedPayload) => void): EmitterSubscription` | `removeListener(subscription: EmitterSubscription): void` |

## 构成部分

### `AddToWalletButton`

即用组件简化了Google钱包和Apple钱包增加的支付卡. 按钮会根据指定的平台和语言自动调整其外观. 它使用由下列机构提供的官方资产: [谷歌](https://developers.google.com/wallet/generic/resources/brand-guidelines) 财务报告和审定财务报表 [苹果公司](https://developer.apple.com/wallet/add-to-apple-wallet-guidelines/) 在他们的钱包相关品牌指南.

> \[大 请记住: [谷歌](https://developers.google.com/wallet/generic/resources/brand-guidelines) 财务报告和审定财务报表 [苹果公司](https://developer.apple.com/wallet/add-to-apple-wallet-guidelines/) 在应用程序中添加此组件时.

遵守这些准则不仅对遵守法律要求至关重要,而且对使用户确信您的应用程序的真实性和安全也至关重要.

> \[注\] 本地化由系统设置自动处理,确保按钮语言与设备首选语言相匹配.

| 财产 | 类型 | 需求 | 说明 | 特定平台 |
| :-: | :-: | --- | --- | --- |
| **新闻** | `(e: GestureResponderEvent) => void` | 对 | 按钮按下时触发的回调 . | 没有 |
| **样式** | `ViewStyle` | 没有 | 自定义组件的总体样式. | 没有 |
| **按钮样式** | `'black' | 'blackOutline'` | 没有 | 自定义按钮样式. | 仅iOS |
| **按钮类型** | `'basic' | 'badge'` | 没有 | 定义按钮的类型(例如主键和次要键). | 没有 |
| **边框拉迪乌斯** | `number` | 没有 | 按钮的边框半径,仅适用于iOS按钮. | 仅iOS |

#### 用法示例:

```js
<AddToWalletButton
    onPress={() => console.log('Button pressed!')}
    style={styles.longButton}
    buttonStyle="blackOutline"
    buttonType="badge"
    borderRadius={4}
/>
```

| 机器人 | iOS系统 |
| :-: | :-: |
| ![](https://npmcn.com/package/%40exodus/react-native-wallet/assets/buttons/android_button.svg) | ![](https://npmcn.com/package/%40exodus/react-native-wallet/assets/buttons/ios_button.svg) |

# 发布您的应用程序

要成功发布您的应用程序,您需要浏览两个平台的一系列强制测试案例.

### 机器人

在将您的应用程序部署到Google Play Store之前,确保您在实施 Push Production 时注意安全,并正确测试您的代码. 为了完成这个任务 请熟悉一下 [提供最佳做法](https://developers.google.com/pay/issuers/apis/push-provisioning/android/best-practices)。 。 。 .

关于应用Google TapAndPay SDK的应用程序部署的最新信息可见于 [发射前进程](https://developers.google.com/pay/issuers/apis/push-provisioning/android/launch-process#step_3_issuer_app_product_review) 财务报告和审定财务报表 [β测试](https://developers.google.com/pay/issuers/apis/push-provisioning/android/beta-testing) 页面存档备份,存于互联网档案馆 Google 文档中。 确保完成Google在连接到 **谷歌的品牌制作**, (中文(简体) ), **API 安全性**,以及 **应用程序稳定性**。 。 。 .

该应用程序需要由Google审查. 在这一过程中,它将需要通过4个规定的强制性测试案例 [这里](https://developers.google.com/pay/issuers/apis/push-provisioning/android/test-cases)。它们验证您的应用程序如何在不同情况下处理卡状态跟踪.

> \[注\] 请务必藏起来 `Add to Google Wallet` 当卡片已经添加到钱包中时按钮.

### iOS系统

在您的 App 中执行 In- App Push 提供功能时, 必须确保您的应用程序遵循 Apple 的功能 [与苹果钱包连接的品牌指南](https://developer.apple.com/wallet/add-to-apple-wallet-guidelines/)。记住,您不能创建自己的按钮,或者您的应用程序在修订时会被拒绝 。 你可以用这个 [添加Wallet按钮组件](https://npmcn.com/package/%40exodus/react-native-wallet/#readme-components) 相反! 当通行证已经提供时, 确保隐藏此按钮, 并替换为文本如 `Added to Apple Wallet`。卡片一旦添加到您的主要设备(用户的iPhone)和所有被链接的设备(例如Apple Watch)中,就会被充分提供.

在品牌准则旁边,请遵循来自 [提供内部文件](https://npmcn.com/package/%40exodus/react-native-wallet/\(#ios\)) 由苹果公司提供.

In-App提供功能在向App Store提交你的应用程序之前,必须经过苹果认证团队的审查和核实. 以下是在审查过程中可能测试的一些关键设想:

-   将一张牌输入苹果钱包
-   将一卡片输入苹果观察
-   尝试注册已经通过钱包程序添加的卡片
-   使用它的 IBAN 手动加卡
-   从同一发行方添加多张牌
-   添加和去除同一张牌
-   在提供过程中处理收到的电话
-   .

苹果公司可能要求演示某些测试方案,例如验证一个单一用户加起来最多20个不同的卡的能力. 准备为此类案件提供鉴定.

此外,在向App Store提交应用程序时,必须包括:

-   测试的演示账户 .
-   演示视频展示In-App提供体验.

# 兼容性

`@expensify/react-native-wallet` 与React Introduct(0.76.0)的5个最新小版本兼容,并专门与新架构相配合.

# 捐款

对该图书馆的捐款按下列方式提供: [https://github.com/Expensify/App (英语)](https://github.com/Expensify/App)请参考该回扣及其所有捐助准则.

## 许可证

麻省理工学院

* * *

此库由 [**加速**](https://www.expensify.com/)和公司卡合作 [**软件大楼**](https://swmansion.com/),反应土著核心贡献者和专家来建立高性能的移动解决方案.

![Brought to you by Software Mansion + Expensify](https://npmcn.com/package/%40exodus/react-native-wallet/assets/signature-light.png)

## 常见问题

### @exodus/react-native-wallet 是什么？

一个反应原生模块,旨在将卡推提供无缝地集成到苹果钱包和Google钱包中,从而能够从您的应用程序直接方便和安全地添加支付卡\.

### 如何安装 @exodus/react-native-wallet？

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

### @exodus/react-native-wallet 支持 TypeScript 吗？

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

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

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

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

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

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

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

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

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