126 lines
3.4 KiB
Markdown
126 lines
3.4 KiB
Markdown
# Flutter App 配置与内购对接
|
||
|
||
本文只描述当前 App 端需要直接调用的 gateway HTTP 接口。所有业务接口都返回统一外壳：
|
||
|
||
```json
|
||
{
|
||
"code": "OK",
|
||
"message": "ok",
|
||
"request_id": "server-generated-request-id",
|
||
"data": {}
|
||
}
|
||
```
|
||
|
||
## 1. 检查 App 更新
|
||
|
||
`GET /api/v1/app/version`
|
||
|
||
公开接口，不需要登录。客户端必须传平台，建议同时传当前编译版本号。
|
||
|
||
请求头：
|
||
|
||
| Header | 必填 | 说明 |
|
||
| --- | --- | --- |
|
||
| `X-App-Code` | 否 | App 编码，默认 `lalu`。 |
|
||
| `X-App-Platform` | 是 | `android` 或 `ios`。也可以用 query `platform` 覆盖。 |
|
||
| `X-App-Build-Number` | 建议 | 当前客户端编译版本号。也可以用 query `build_number` 覆盖。 |
|
||
| `X-App-Version` | 否 | 当前客户端展示版本号，只用于客户端侧日志排查。 |
|
||
|
||
示例：
|
||
|
||
```http
|
||
GET /api/v1/app/version?platform=android&build_number=100
|
||
X-App-Code: lalu
|
||
X-App-Platform: android
|
||
X-App-Build-Number: 100
|
||
```
|
||
|
||
响应：
|
||
|
||
```json
|
||
{
|
||
"code": "OK",
|
||
"message": "ok",
|
||
"request_id": "req_abc",
|
||
"data": {
|
||
"app_code": "lalu",
|
||
"platform": "android",
|
||
"version": "1.2.0",
|
||
"build_number": 120,
|
||
"force_update": true,
|
||
"download_url": "https://example.com/lalu.apk",
|
||
"description": "修复已知问题",
|
||
"has_update": true,
|
||
"current_build_number": 100,
|
||
"updated_at_ms": 1710000000000,
|
||
"server_time_ms": 1710000001234
|
||
}
|
||
}
|
||
```
|
||
|
||
Flutter 处理规则：
|
||
|
||
- `has_update=false`：不展示升级弹窗。
|
||
- `has_update=true && force_update=false`：展示普通升级弹窗，允许关闭。
|
||
- `has_update=true && force_update=true`：展示强更弹窗，不允许进入主流程。
|
||
- `download_url` 由后台配置。Android 通常打开 APK 下载页；iOS 通常打开 App Store 链接。
|
||
- 服务端只用 `build_number` 判断新旧，不解析 `version` 语义版本。
|
||
|
||
## 2. 获取内购商品列表
|
||
|
||
`GET /api/v1/wallet/recharge/products`
|
||
|
||
登录接口，需要 `Authorization: Bearer <access_token>`。gateway 会用当前登录用户资料里的 `region_id` 筛选商品，客户端不要自己传区域。
|
||
|
||
请求头：
|
||
|
||
| Header | 必填 | 说明 |
|
||
| --- | --- | --- |
|
||
| `Authorization` | 是 | App 登录 access token。 |
|
||
| `X-App-Platform` | 是 | `android` 或 `ios`。也可以用 query `platform` 覆盖。 |
|
||
|
||
示例：
|
||
|
||
```http
|
||
GET /api/v1/wallet/recharge/products
|
||
Authorization: Bearer <access_token>
|
||
X-App-Platform: ios
|
||
```
|
||
|
||
响应：
|
||
|
||
```json
|
||
{
|
||
"code": "OK",
|
||
"message": "ok",
|
||
"request_id": "req_abc",
|
||
"data": {
|
||
"channels": ["apple"],
|
||
"products": [
|
||
{
|
||
"product_id": 11,
|
||
"product_code": "iap_ios_1500",
|
||
"product_name": "1500 Coins",
|
||
"description": "coin pack",
|
||
"platform": "ios",
|
||
"channel": "apple",
|
||
"currency_code": "USDT",
|
||
"coin_amount": 1500,
|
||
"amount_micro": 1500000,
|
||
"region_ids": [2002],
|
||
"resource_asset_type": "COIN",
|
||
"status": "active",
|
||
"enabled": true
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
Flutter 处理规则：
|
||
|
||
- 只展示 `products` 里的商品；后台已经按平台、用户区域、上架状态过滤。
|
||
- `amount_micro` 是 USDT 微单位，`1 USDT = 1000000`。
|
||
- 当前资源类型固定是 `COIN`，后续如果后台新增资源类型，客户端应按 `resource_asset_type` 分支处理。
|
||
- Android 使用 `channel=google` 的商品对接 Google Play Billing；iOS 使用 `channel=apple` 的商品对接 StoreKit。
|