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

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

版本：0\.3\.2
npm 元数据更新时间：2026-11-02T17:05:43.171Z
中文译文更新时间：2026-11-14T04:10:44.805Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：2.3 MB，216 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：react \*，react-native \*
- 首次发布：2025-06-23T18:35:50.925Z
- 最新版本发布：2026-11-02T17:05:42.860Z
- 近 30 天下载量：207710（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：65（近 12 个月 55 个）

## 中文简介

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

## 安装

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

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

## README

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

## 特征

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

## 开始

使用 `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). 库使用UAPP APIs(`PaymentCredentialsGenerator`, (中文(简体) ), `PushTokenizeResult`),所以没有这些版本的更古老的SDK版本将无法编译. 以 18.10.1 试验.
    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 应享权利 。 企业队身份证明不支持. 在我们的面板中默认无法提供此项权利;您需要请求.

通过 [请求提供材料](https://developer.apple.com/contact/request/apple-pay-in-app-provisioning/)。只有账户持有者才能访问此表格——如果无法访问,请与团队账户持有者协调。 或者,您可以发电子邮件 `iap_entitlements@apple.com` 格式如下:

**主题 :** `Apple Pay Entitlements and Allow List Request - [Issuer Name] - [Country Code]`

**车身 :**

-   发行者名称
-   国家\[国家代码\]
-   团队标识
-   亚当身份证
-   应用程序名称

> \[注\] 只有制作团队的身份证和亚当的身份证才能获得该资格. 测试组的ID不合格.

一旦苹果验证你的身份, 你应该得到文件命名 `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
```

### 博览插件

用于 `@expensify/react-native-wallet` 与博览会,你需要使用博览会插座.

在你身边 `app.json` 文件,添加以下配置:

```json
{
  "expo": {
    "plugins": [
      [
            "@expensify/react-native-wallet",
            {
                enableApplePayProvisioning: true,
                googleTapAndPaySdkPath: "./libs/tapandpay-v18.10.1.zip", // path to the Google Tap & Pay SDK zip file
            },
      ],
    ]
  }
}
```

之后您需要重建您的应用程序, 因为 lib有本地文件 .

```bash
npx expo prebuild --clean
npx expo run:ios
npx expo run:android
```

## 所需数据

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

### 机器人

-   **不透明支付卡** (OPC) - 一个二进制的Google Pay从发行方的app收到信息,可以提交TSP接收一个指使.
-   **谷歌不透明支付卡** (Google OPC) - UAPP(统一Android Push Productioning)流所需要OPC的加密版本. 这是您在供给过程中使用谷歌加密密钥的后端生成的. [了解更多关于UAPP的信息](https://npmcn.com/package/%40expensify/react-native-wallet/docs/UAPP.md)
-   **托肯服务提供人** (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编码)所使用的密钥.
-   **主账户标识符** - PassKit使用不透明的发卡人ID(也叫FPANID)在再发和装置上识别同一张卡. 传过来 `IOSCardData` 转至 `canAddCardToAppleWallet`。 。 。 . `getCardStatusByIdentifier` 与该值完全匹配,并且不回落. `addCardToAppleWallet`,推断 `deviceType`,以及 `canAddCardToAppleWallet` 当你也经过时 `lastDigits` 共享一个查询:一个精确的 id 匹配胜出, 否则库会使用唯一没有的密码的 id `deactivated` 和最后一个数字相同。 仍然在运行并用同位数结尾的不同牌可以被取出. 传出存储在通行证上的id PassKit( `primaryAccountIdentifier` 从 `listAppleWalletPasses`) 跳过这个检查.
-   **设备类型** - 所提供卡片的装置: `phone` 或者说 `watch`。PassKit不报告用户选择的设备,所以库推断它来自已经提供卡片的地方。 当它无法分辨时,值是 `unknown`。 。 。 .

# API 参考

库为苹果钱包和Google钱包API的无缝集成和使用提供功能. 此外,它还包括管理供应活动的听众和管理人员。 下文介绍这些功能以及所涉及的数据类型.

## 职能

| 函数 | 说明 | 参数 | 返回/类型 | iOS系统 | 机器人 |
| :-: | :-: | --- | --- | --- | :-: |
| **获取安全钱包信息** | 返回安全交易所需的平台专用钱包信息. | 无 | `WalletData` | ❌ | ✅ |
| **检查Wallet的可用性** | 检查钱包是否准备好, 并尽可能初始化 . | 无 | `boolean` | ✅ | ✅ |
| **获取CardStatusBy后缀** | 获取钱包中卡片的当前状态. | `lastDigits: string`  
(牌号的最后几个数字) | `CardStatus` | ✅ | ✅ |
| **获取卡片状态识别符** | 返回基于特定平台标识符的卡片状态。 在Android上,这是 `Token Reference ID` 在iOS上,这是 `Primary Account Identifier`。 。 。 . | `identifier: string`, (中文(简体) ),  
`tsp: string` | `CardStatus` | ✅ | ✅ |
| **已获得资格 目标** | 检查该卡是否仍能被添加到Google钱包目标(手机或一对可穿戴). Google在支持可穿戴时推荐它用于"添加到Google钱包"按钮,因为已经挂入手机的卡片仍然可以添加到手表上. | `last4Digits: string`, (中文(简体) ),  
`network: string`, (中文(简体) ),  
`issuerName: string` | `boolean` | ❌ | ✅ |
| **添加标记到 GoogleWallet** | 启动本地 Push 程序, 用于在 Google 钱包中添加卡片 。 需要返回 UAPP 流量的支付凭证的处理器 . [学习更多](https://npmcn.com/package/%40expensify/react-native-wallet/docs/UAPP.md) | `data`数字 : `AndroidCardData`, (中文(简体) ),  
`handlePaymentCredentials`数字 : `(data: onPaymentCredentialsRequestPayload) => Promise<AndroidPaymentCredentialsResponse>` | `TokenizationStatus` | ❌ | ✅ |
| **恢复AddCardTo GoogleWallet 服务器** | 恢复使用已存在的代号引用ID在Google钱包上添加一卡片的Push提供流. | `data`数字 : `AndroidResumeCardData` | `TokenizationStatus` | ❌ | ✅ |
| **列表脚本** | 列出目前存储在Google钱包中的所有令牌. | 无 | `TokenInfo[]` | ❌ | ✅ |
| **列表 AppleWalletPasses 地图集** | 列出Apple钱包安全元素(Apple Wallet Secret Elements)可供应用,包括激活状态和通过是否远程(例如苹果观察). 过滤结果为 `activationState === 'requireActivation'` 或者说 `activationState === 'pending'` 用于构建待发卡 UI. | 无 | `IOSWalletPass[]` | ✅ | ❌ |
| **ưμ㼯A** | 为这些最后的位数打开已安装的 iPhone 传出, 偏好需要验证的 。 回返 `false` 何时 `lastDigits` 空的,当没有通过匹配, 当不止一张牌结束在这些数字, 和Android. | `lastDigits: string` | `boolean` | ✅ | ✅ |
| **添加卡通AppleWallet** | 启动本地 Push 提供流程, 用于在 Apple 钱包中添加一卡 。 何时 `IOSCardData.primaryAccountIdentifier` 设置,设备拾取器只列出还没有卡片的设备。 如果PassKit无法显示流量,因为卡片已经出现在每个设备上,那么调用会以明显的出错而失败. 如果发售人回调时投出,则"添加支付通行证"即被关闭,承诺以该错误拒绝. 否则就解决了 `IOSAddCardResult`。成功的添加包括: `activationState` 当PassKit报告已知状态时。 减少额包括 `errorDomain` 财务报告和审定财务报表 `errorCode` 并且不会拒绝,因为钱包已经显示自己的信息。 见"断取"之变. | `data`数字 : `IOSCardData`, (中文(简体) ),  
`issuerEncrypt-`  
`PayloadCallback: IOSIssuerCallback` | `IOSAddCardResult` | ✅ | ❌ |
| **canAddCardTopleWallet 存档副本 页面存档备份,存于互联网档案馆** | 检查该卡是否仍能被添加到iPhone或一对相配的苹果观察. 过 `lastDigits` 来使用与 `addCardToAppleWallet`. 回归 `false` 安卓号. | `primaryAccountIdentifier: string`, (中文(简体) ),  
`lastDigits?: string` | `boolean` | ✅ | ✅ |
| **激活AppleWalletPass 程序** | 使用您发行商后端的激活数据激活 Apple 钱包中已有的安全元素通过 。 决定: `true` 当通过已经激活时。 对于 `requireActivation`,返回 Apple 的结果,这可能是 `false`。拒绝任何其他国家(`pending`, (中文(简体) ), `suspended`或无效或非基数64激活数据. | `data`数字 : `IOSPassActivationData` | `boolean` | ✅ | ❌ |

### 打破变革

`addCardToAppleWallet` 决定 `IOSAddCardResult` 改为 `TokenizationStatus`读取 `result.status`。 。 。 .

钱包的下降解决了 `{ status: 'error', errorDomain, errorCode }` 而不是拒绝。 发行者步骤解决后取消 `{ status: 'canceled' }` 而不是拒绝。 发行者回调时所抛出的错误仍然拒绝,添加支付通行证表关闭 .

## 数据类型

| 类型 | 说明 | 字段 |
| :-: | :-: | --- |
| **Android Wallet 数据** | 钱包交易所需的Android设备的具体信息. | `deviceID: string`, (中文(简体) ),  
`walletAccountID: string` |
| **Android 卡尔达塔** | 数据与Android平台钱包上要添加的卡片有关. | `network: string`, (中文(简体) ),  
`opaquePaymentCard: string`, (中文(简体) ),  
`cardHolderName: string`, (中文(简体) ),  
`lastDigits: string`, (中文(简体) ),  
`userAddress: UserAddress`, (中文(简体) ),  
`isVirtualCard?: boolean`, (中文(简体) ),  
`isBounceProvisioned?: boolean` |
| **Android ResumeCardData (英语)** | 使用已存在的代号参考ID恢复给Google钱包加卡的简化数据结构. | `network: string`, (中文(简体) ),  
`tokenReferenceID: string`, (中文(简体) ),  
`cardHolderName?: string`, (中文(简体) ),  
`lastDigits?: string` |
| **Android Payment 证书回复** | 包含UAPP流加密支付凭证的响应对象. [学习更多](https://npmcn.com/package/%40expensify/react-native-wallet/docs/UAPP.md) | `opaquePaymentCard: string`, (中文(简体) ),  
`googleOpaquePaymentCard: string` |
| **支付凭证请求加载** | 当Google钱包在UAPP提供期间请求支付资格时收到的有效载荷. [学习更多](https://npmcn.com/package/%40expensify/react-native-wallet/docs/UAPP.md) | `requestId: string`, (中文(简体) ),  
`serverSessionId: string`, (中文(简体) ),  
`walletId: string`, (中文(简体) ),  
`tokenRequestorId: string | null`, (中文(简体) ),  
`opaquePaymentCard: string` |
| **用户地址** | 用于验证持卡人的结构地址. | `name: string`, (中文(简体) ),  
`addressOne: string`, (中文(简体) ),  
`addressTwo: string`, (中文(简体) ),  
`city: string`, (中文(简体) ),  
`administrativeArea: string`, (中文(简体) ),  
`countryCode: string`, (中文(简体) ),  
`postalCode: string`, (中文(简体) ),  
`phoneNumber: string` |
| **IOSCardData 数据** | 数据涉及将在iOS上添加的卡. 设定 `primaryAccountIdentifier` 在第一次提供之后,接下来的尝试 瞄准还没有卡片的设备. | `network: string`, (中文(简体) ),  
`activationData: string`, (中文(简体) ),  
`encryptedPassData: string`, (中文(简体) ),  
`ephemeralPublicKey: string`, (中文(简体) ),  
`cardHolderTitle: string`, (中文(简体) ),  
`cardHolderName: string`, (中文(简体) ),  
`lastDigits: string`, (中文(简体) ),  
`cardDescription: string`, (中文(简体) ),  
`cardDescriptionComment: string`, (中文(简体) ),  
`primaryAccountIdentifier?: string` |
| **已经激活 有效载荷** | 数据被收听者用来在卡片状态变化时通知. | `tokenId?: string | null`, (中文(简体) ),  
`status: 'activated' | 'canceled'`  
 |
| **IOS Issuer 调回** | 这种回调被以非ce来被引用,它的签名,从苹果公司获得的证书阵列,卡被添加到设备上. 将这些细节转发给您的服务器或发卡人的API,以安全加密在苹果钱包上加卡所需的有效载荷. `deviceType` 是最佳值;见 `IOSDeviceType`。 。 。 . | `(nonce: string, nonceSignature: string, certificate: string[], deviceType: IOSDeviceType) => IOSEncryptPayload` |
| **IOS 服务器** | 该卡正在提供最佳设备。 PassKit 不报告所选设备, 因此从已有的路由中推断 `primaryAccountIdentifier` 设置,使用与 `addCardToAppleWallet`。当苹果公司询问加密的有效载荷时,包括当用户再次尝试时,则计算出该值。 配对的苹果卫视的出站口从不计为iPhone出站口. `phone` 指该卡已经只在配对的"苹果观察"上. `watch` 表示它已经只在iPhone上. `unknown` 表示卡片在两个设备上都没有,或者没有提供标识符,所以用户仍然可以选择任何一个设备. 传入 `deactivated` 状态计为不存在. | `'phone' | 'watch' | 'unknown'` |
| **IOSAddPayment PassData (英语)** | 数据在用户继续提供流程时返回 。 苹果提供非ce,它的签名,和证书. 图书馆又说 `deviceType`; 苹果不还. 见 `IOSDeviceType`。 。 。 . | `status: number`, (中文(简体) ),  
`nonce: string`, (中文(简体) ),  
`nonceSignature: string`, (中文(简体) ),  
`certificates: string[]`, (中文(简体) ),  
`deviceType?: string` |
| **IOS Encrypt Payload (英语)** | 包含完成Apple Walet所添加卡片的必要元素的对象. | `encryptedPassData: string`, (中文(简体) ),  
`activationData: string`, (中文(简体) ),  
`ephemeralPublicKey: string` |
| **IOSPass 活动数据** | 确定一个现有的苹果钱包安全元素通过,并提供由您的发行商后端返回的激活有效载荷. `activationData` 一定是64号基地编码的 设定 `isRemote` 改为 `true` 用于对齐的 Apple Watch 传球或 `false` iPhone在两张牌上同一张牌时通过。 先看一看iPhone的通过,然后再看"守望". | `passTypeIdentifier: string`, (中文(简体) ),  
`serialNumber: string`, (中文(简体) ),  
`activationData: string`, (中文(简体) ),  
`isRemote?: boolean` |
| **IOS WalletPass (英语)** | 设备上目前可获得的关于苹果钱包安全元素传递的信息或对称远程设备的信息. | `passTypeIdentifier: string`, (中文(简体) ),  
`serialNumber: string`, (中文(简体) ),  
`primaryAccountIdentifier?: string`, (中文(简体) ),  
`lastDigits?: string`, (中文(简体) ),  
`activationState: CardStatus`, (中文(简体) ),  
`isRemote: boolean` |
| **IOSAddCard 结果** | 成果 `addCardToAppleWallet`。 。 。 . `activationState` 当 PassKit 报告已知的卡片状态时,它将被设定为成功. `errorDomain` 财务报告和审定财务报表 `errorCode` 当钱包显示自己的信息后,卡片会下降. | `status: TokenizationStatus`, (中文(简体) ),  
`activationState?: CardStatus`, (中文(简体) ),  
`errorDomain?: string`, (中文(简体) ),  
`errorCode?: number` |
| **托肯信息** | 谷歌钱包中存储的一款代币信息. | `identifier: string`, (中文(简体) ),  
`lastDigits: string`, (中文(简体) ),  
`tokenState: number` |

### AndroidCardData 可选字段

这个 `AndroidCardData` 类型包括两个可选的布尔字段,这些字段提供了关于所提供卡片的额外信息:

#### `isVirtualCard?: boolean`

表示所提供的卡片是否是虚拟卡片. 虚拟卡是数字生成的与物理卡账户相连接的卡号. 它们通过以下方式加强安全:

-   允许用户在线购买而不暴露其实体卡号
-   方便注销和再生而不影响物理卡
-   提供交易专用或商家专用卡号

设定为 `true`,此旗帜告知谷歌钱包,所提供卡片是虚拟卡片,这可能会影响卡片在钱包界面中如何显示和管理.

#### `isBounceProvisioned?: boolean`

说明卡片是否通过"弹出提供"提供. 弹出提供是两步提供流程,其中:

1.  用户最初直接通过 Google 钱包( 在您的应用程序之外) 提供一张卡片
2.  您的应用程序稍后“ 弹出” 或引导用户返回以完成额外的校验或设置步骤

此旗能帮助Google Walet轨道卡最初通过Google Waletapp添加,但需要额外的应用特定配置或验证. 设定为 `true`,它表示此卡以前通过Google钱包接口提供,现在正在通过您的应用程序完成或更新.

## 卡片状态

| 类型 | 可能值 |
| :-: | :-: |
| **卡片状态** | `not found`, (中文(简体) ), `active`, (中文(简体) ), `requireActivation`, (中文(简体) ), `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/%40expensify/react-native-wallet/assets/buttons/android_button.svg) | ![](https://npmcn.com/package/%40expensify/react-native-wallet/assets/buttons/ios_button.svg) |

# 十六进制编码

这个库使用基础64编码来编码数据. 你可能用Hex编码.

如果情况如此,您需要以适当的格式转换数据.

这是一个如何将数据转换成六进制格式的例子 :

```ts
import { Buffer } from "buffer"
const base64ToHex = (base64: string): string => Buffer.from(base64, "base64").toString("hex")

[...]

    const issuerEncryptPayloadCallback = async (
        nonce: string,
        nonceSignature: string,
        certificate: string[],
        deviceType: IOSDeviceType,
    ): Promise<IOSEncryptPayload> => {
        try {
            const payload = {
                encryptionDetails: {
                    nonce: base64ToHex(nonce),
                    nonceSignature: base64ToHex(nonceSignature),
                    wspCertificates: certificate,
                },
                deviceType,
                serialNumber,
                wspId: "APPLE" as const,
            }
[...]
```

这将取决于您的后端/ 签发器的操作情况, 以确保检查它们, 否则监督办可能无法提供卡片 .

# UAPP( 统一的Android Push 提供)

对于需要增强卡片提供安全性的Android应用程序,这个库支持UAPP(统一Android Push Productioning)与Google钱包相通.

📖 **[读取UAPP完整的文档 ~](https://npmcn.com/package/%40expensify/react-native-wallet/docs/UAPP.md)**

UAPP指南涵盖:

-   UAPP是什么,如何运作
-   分步设置指令
-   后端执行要求
-   处理和排除出错
-   完整代码示例

# 发布您的应用程序

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

### 机器人

> \[尖叫声\] **在生产释放前必须进行测试.** 未按规定提供发射审批测试证据的,可以撤销您对谷歌钱包生产环境的访问. 在应用前完成所有测试要求.

在将您的应用程序部署到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)。它们验证您的应用程序如何在不同情况下处理卡状态跟踪.

**主要测试标准包括:**

-   适当处理卡状态(活动、待发、暂停等)
-   已提供卡片时纠正用户界面行为
-   敏感付款数据的安全处理
-   遵守Google品牌准则
-   适当的错误处理和用户反馈

请参看 [完整的测试标准文件](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/%40expensify/react-native-wallet/#readme-components) 相反! 将添加到苹果钱包按钮时显示 `canAddCardToAppleWallet(primaryAccountIdentifier, lastDigits)` 返回时 `true`,包括卡被添加到iPhone后但尚未被配对的苹果观察. 显示文本类似 `Added to Apple Wallet` 只有回电一次 `false`。通过 `primaryAccountIdentifier` 内 `IOSCardData` 因此,接下来的尝试 瞄准剩下的设备, 通过相同的 `lastDigits` 双方同意 这个匹配 [苹果公司的应用中提供指南](https://applepaydemo.apple.com/in-app-provisioning#3.3)。 。 。 .

在品牌准则旁边,请遵循来自 [提供内部文件](https://npmcn.com/package/%40expensify/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/%40expensify/react-native-wallet/assets/signature-light.png)

## 常见问题

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

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

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

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

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

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

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

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

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

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

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

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

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

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