# 顽皮狮支付SDK示例

**Repository Path**: abbasspace/wps_payment_sample_project

## Basic Information

- **Project Name**: 顽皮狮支付SDK示例
- **Description**: 顽皮狮支付SDK示例
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-13
- **Last Updated**: 2026-05-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# WPS 支付 SDK 多厂商接入说明（Android 示例）

本文说明如何在主工程中接入 **WPS 支付桥接 AAR**（`wps-paymentsdk-<厂商>-release.aar`）。各厂商的 **桥接包、三方 SDK、Maven 依赖** 不同，**同一 APK 内只能编入一种桥接包**（类名均为 `com.wps.paymentsdk.*`，不可并存）。

更完整的 **Unity 宿主 / JNI 调用 / 各渠道 meta-data 键名** 见仓库根目录 **[UnityIntegration.md](UnityIntegration.md)**。

---

## 文档结构

| 章节 | 内容 |
|------|------|
| [示例工程说明](#示例工程说明) | 编译方式、界面能力、`Application` 与主题 |
| [通用约定](#通用约定) | `libs` 目录、Flavor、Manifest 注意点 |
| [沙发（Shafa）](#沙发shafa) | 桥接包与沙发、ZXing |
| [阿里（Ali）](#阿里ali) | 桥接包、AppPay、Gson / OkHttp / Okio、MultiDex |
| [乐视（Leshi）](#乐视leshi) | 桥接包（已内嵌联运 SDK，勿重复引 jar） |
| [华为（Huawei）](#华为huawei) | 占位说明 |
| [参考与维护](#参考与维护) | 版本、扩展渠道时的维护建议 |

---

## 示例工程说明

### 构建与运行

1. 将对应渠道的 **桥接 AAR**（及下方各节列出的三方包）放入 **`app/libs/`**。
2. Android Studio 打开 **Build Variants**，选择 **`shafaDebug` / `aliDebug` / `leshiDebug` / `huaweiDebug`**（或对应 `Release`）。
3. **Sync Project with Gradle Files**，再 Run。

依赖与 Flavor 的对应关系已写在 **`app/build.gradle.kts`**：若缺少某渠道的桥接 AAR，Gradle 会 **告警**；该变体可能无法编译或无法联调。

### 工程与版本（摘要）

| 项 | 说明 |
|----|------|
| **AGP / Gradle** | 见 `gradle/libs.versions.toml` 与 `gradle/wrapper/gradle-wrapper.properties`（当前示例使用 **AGP 8.10.x**、**Gradle 8.11.x**） |
| **compileSdk / targetSdk** | **36**（与沙法桥接 AAR 元数据要求一致） |
| **minSdk** | **19**（AndroidX 使用 **AppCompat 1.6.x**、**Material 1.12.x** 等与低 minSdk 兼容的版本，见 Version Catalog） |
| **Kotlin** | 见 `libs.versions.toml` |
| **MultiDex** | 全局开启；**`SampleApplication`** 继承 **`MultiDexApplication`**（阿里等渠道方法数易超 64K） |

### 示例 App 行为

| 能力 | 说明 |
|------|------|
| **`SampleApplication`** | 在 `onCreate` 中调用 **`PaymentSdk.bootstrap(...)`**；亦可改为无参 **`bootstrap(this)`** 并从 Manifest / `BuildConfig` 读密钥（见 `SampleApplication` 内注释与 **UnityIntegration.md §3**） |
| **`MainActivity`** | **ViewBinding**；**Material `TextInputLayout`** 编辑 **`PayRequest`** 各字段；**「恢复示例」** 加载当前 Flavor 的 **`PayRequestFactory.demo()`**；**「发起支付」** 用表单内容调用 **`PaymentSdk.pay`** |
| **回调日志** | **`PaymentCallback`** 输出到界面与 Logcat；**`onEvent`** 使用整型 **`code`**（配合 **`PaymentEventCode`**） |
| **二维码** | 全工程依赖 **ZXing `core`**；在 **`CREATE_ORDER_SUCCESS`** 且订单 JSON 含 **`qrCodeUrl`** 时，用 ZXing 生成二维码展示（便于阿里等渠道联调） |

### 主题（Material）

界面使用 **`TextInputLayout`**，应用主题须为 **`Theme.MaterialComponents.*`**（或 Material3 子类）。示例中 **`values/themes.xml`** 已设为 **`Theme.MaterialComponents.DayNight.NoActionBar`**。若改回纯 `Theme.AppCompat.*`，会导致 **inflate `TextInputLayout` 崩溃**。

---

## 通用约定

### 桥接包与类冲突

- 每个 **`wps-paymentsdk-*-release.aar`** 内均含 **`com.wps.paymentsdk.PaymentSdk`** 等同名类，**不能**把多个渠道的桥接包打进同一个 APK。
- 本仓库通过 **Product Flavor**（`payment` 维度）为各变体单独配置 **`xxxImplementation`**，实现「一次工程、多渠道出包」。

### 放置位置

- 桥接包与本地 AAR/JAR 默认放在 **`app/libs/`**。
- 沙发三方包若命名为 **`shafaPay*.aar`** 并放入 `libs`，**`app/build.gradle.kts`** 会自动 **`fileTree` 匹配** 并加入 **`shafa`** 变体（无需手改文件名，以你方交付为准）。

### 初始化与安全

- **App Key / Secret、环境（沙箱/正式）** 以 WPS 与渠道文档为准；**勿将生产密钥提交公开仓库**。
- 调用顺序：**`bootstrap(Application)`**（进程级）→ 进入支付页 **`init(Activity, PaymentCallback)`** → **`pay(PayRequest)`** → 离开页 **`release()`**（详见 **UnityIntegration.md §2**）。

### 同步、编译与清单

- 修改依赖后 **Gradle Sync**；关注 **Manifest 合并**、`minSdk` 与传递依赖是否与渠道要求冲突。
- 渠道自带的 **Activity / Provider / meta-data** 勿随意删除；冲突时用 **`tools:replace`** / **`tools:node`** 按文档处理。

---

## 沙发（Shafa）

**桥接包：** `app/libs/wps-paymentsdk-shafa-release.aar`  
**变体：** `shafaDebug` / `shafaRelease`

### 依赖一览

| 类型 | 说明 |
|------|------|
| 桥接 AAR | `wps-paymentsdk-shafa-release.aar` |
| 沙发支付 SDK | `shafaPay*.aar`（放入 `libs` 后由构建脚本自动匹配；若缺失，运行时可能出现 **`TVPayment`** 等 **`ClassNotFoundException`**） |
| ZXing | **`com.google.zxing:core`**（Version Catalog：`libs.zxing.core`，**全变体 implementation**，用于示例里二维码展示；沙发厂商侧是否强制以文档为准） |

---

## 阿里（Ali）

**桥接包：** `app/libs/wps-paymentsdk-ali-release.aar`  
**变体：** `aliDebug` / `aliRelease`

### 依赖一览

| 类型 | 说明 |
|------|------|
| 桥接 AAR | `wps-paymentsdk-ali-release.aar` |
| AppPay | `apppaysdk-0.1.3.aar`（文件名以交付为准，需在 `build.gradle.kts` 中与路径一致） |
| Gson | `com.google.code.gson:gson` |
| OkHttp / Okio | **`okhttp:3.14.9`**、**`okio:1.17.6`**（**勿**升到 OkHttp 4.x，见 **UnityIntegration.md §6.1**） |

**`PayRequest`：** 阿里渠道 **`price`、`callbackUrl`** 必填（见 **UnityIntegration.md §6.1**）。

---

## 乐视（Leshi）

**桥接包：** `app/libs/wps-paymentsdk-leshi-release.aar`（需自行放入，未放入时 **`leshi`** 变体仅告警）  
**变体：** `leshiDebug` / `leshiRelease`

### 依赖一览

| 类型 | 说明 |
|------|------|
| 桥接 AAR | `wps-paymentsdk-leshi-release.aar`（**已内嵌** `leishi_intermodal_sdk`，**不要**再 `implementation` 同名 jar，否则会 **Duplicate class**） |

若你方交付的桥接包 **未** 内嵌联运 SDK，再单独加入 `leishi_intermodal_sdk.jar`，且 **二选一**，勿与已内嵌的 AAR 同时引用。

Manifest 中 **`meta-data` / `queries` / `receiver`** 等以 AAR 合并结果与 **UnityIntegration.md §3.0.1（乐视）** 为准。

---

## 华为（Huawei）

**桥接包：** `app/libs/wps-paymentsdk-huawei-release.aar`（占位；未放入时 **`huawei`** 变体仅告警）  
**变体：** `huaweiDebug` / `huaweiRelease`

接入 **HMS / IAP** 后，请按官方文档补充依赖、Manifest 与本节说明。

---

## 参考与维护

| 资源 | 用途 |
|------|------|
| **[UnityIntegration.md](UnityIntegration.md)** | Unity 导出、`bootstrap`/`init`/`pay`/`release`、各渠道 **meta-data / BuildConfig** 键名、Ali 依赖版本、排障清单 |
| **`gradle/libs.versions.toml`** | AndroidX、Material、ZXing、Gson、OkHttp、Okio、Kotlin、AGP 等版本集中管理 |
| **`app/src/<flavor>/java/.../PayRequestFactory.kt`** | 各渠道 **示例默认 `PayRequest`**（与 MainActivity「恢复示例」对应） |

**新增厂商时：** 在 **`app/build.gradle.kts`** 增加 Flavor 与 **`xxxImplementation`**，在 **`app/src/<flavor>/`** 增加 **`PayRequestFactory`** 与 **`res/values/strings.xml`**（渠道提示文案），并更新本文档 **文档结构** 表与对应章节。