125 lines
5.1 KiB
Markdown
125 lines
5.1 KiB
Markdown
# 用户登录流程
|
||
|
||
本文档基于 `docs/petsHeroAI_client_guide.md` 中的登录态接口，整理客户端登录顺序与数据处理要求。
|
||
|
||
---
|
||
|
||
## 1. 整体顺序
|
||
|
||
1. **设备快速登录**：`POST /v1/user/fast_login`，拿到 `userToken` 和用户信息。
|
||
2. **保存登录态与用户信息**：保存 token、积分、userId、头像、昵称、国家码等；**首次登录**记录为注册日期。
|
||
3. **归因上报**：`POST /v1/user/referrer`，将归因数据（如从 Adjust 获取的 digest）上报。
|
||
4. **获取用户通用信息**：`GET /v1/user/common_info`，拉取通用配置并保存（含 `surge` 中 `lucky` 等）。
|
||
|
||
登录成功后，后续所有请求需在 Header 中携带 `knight`（即 `User_token` / userToken）。
|
||
|
||
---
|
||
|
||
## 2. 设备快速登录 `POST /v1/user/fast_login`
|
||
|
||
- **鉴权**：需要（Header 需带 `portal`，首次无 `knight` 可空或按文档处理）。
|
||
- **说明**：用设备 ID + 签名做设备登录，返回用户 token 及基础信息。
|
||
|
||
### 请求
|
||
|
||
| 位置 | 字段（映射后） | 说明 |
|
||
|--------|----------------|------|
|
||
| Query | portal | 应用包名（必填） |
|
||
| Query | crest | 渠道号（可选） |
|
||
| Query | accolade | 类型（可选） |
|
||
| Body | digest | 归因信息，如 utm_source=googleplay（可与 Adjust 一致） |
|
||
| Body | resolution | 签名：**MD5(deviceId) 大写 32 位** |
|
||
| Body | origin | 设备 ID（deviceId） |
|
||
|
||
### 响应（解密后 data / sidekick）
|
||
|
||
| 字段（映射后） | 说明 |
|
||
|----------------|------|
|
||
| reevaluate | **userToken**，后续请求 Header 的 `knight` |
|
||
| asset | **userId**，用户 ID |
|
||
| reveal | **credit**，积分余额 |
|
||
| realm | 头像 URL |
|
||
| terminal | 用户名 |
|
||
| navigate | 国家代码 |
|
||
| surge | 客户端界面配置（extConfig），JSON 字符串，需按需解析 |
|
||
| equip | 是否首次注册（firstRegister） |
|
||
| 其他 | 见接口文档 sidekick 结构 |
|
||
|
||
### 客户端必做
|
||
|
||
- 保存并设置 **userToken**（如写入请求头 `knight`）。
|
||
- 保存并更新 **积分**（reveal）、**用户信息**（userId、头像、昵称、国家码等）。
|
||
- **首次登录**：将该次登录日期记为**注册日期**（用于归因/统计）；可本地标记“已注册”避免重复上报。
|
||
|
||
---
|
||
|
||
## 3. 归因上报 `POST /v1/user/referrer`
|
||
|
||
- **鉴权**：需要（Header 带 `portal`、`knight`）。
|
||
- **说明**：登录成功后调用，上报归因数据；**digest 从 Adjust 取**。
|
||
|
||
### 请求
|
||
|
||
| 位置 | 字段（映射后） | 说明 |
|
||
|--------|----------------|------|
|
||
| Query | sentinel | 应用标识（必填） |
|
||
| Query | asset | 用户 ID（userId） |
|
||
| Query | accolade | 类型（可选），传 `android_adjust` |
|
||
| Query | portal | 应用包名（必填） |
|
||
| Body | digest | **归因信息，从 Adjust 获取** |
|
||
| Body | origin | 设备 ID（deviceId） |
|
||
|
||
### 响应
|
||
|
||
- code=0 表示成功；可解析 msg / data 做提示或日志。
|
||
- **调用成功后建议增加日志输出**，便于排查归因是否上报成功。
|
||
|
||
---
|
||
|
||
## 4. 获取用户通用信息 `GET /v1/user/common_info`
|
||
|
||
- **鉴权**：需要（Header 带 `portal`、`knight`）。
|
||
- **说明**：登录成功后调用，拉取通用配置并**保存到全局/本地**。
|
||
|
||
### 请求
|
||
|
||
| 位置 | 字段（映射后） | 说明 |
|
||
|--------|----------------|------|
|
||
| Query | sentinel | 应用标识（必填） |
|
||
| Query | asset | 用户 ID（userId） |
|
||
| Query | shield / crest / item / origin / gauntlet / portal | 按需传，见接口文档 |
|
||
|
||
### 响应（解密后 data / sidekick）
|
||
|
||
- 与 fast_login 的 data 结构类似，含 **surge**（extConfig）、积分、用户信息等。
|
||
- **surge**：字符串，为 JSON；需 **先 JSON 解析再使用**。
|
||
- 解析后的对象中，包含 **lucky** 等字段，用于控制第三方支付等能力。
|
||
- 其他字段（reveal、realm、terminal、navigate 等）按需保存到全局变量或状态。
|
||
|
||
### 客户端必做
|
||
|
||
- 调用 common_info 并将结果**保存到全局/状态**。
|
||
- 对 **surge** 做 **JSON decode**，得到对象后读取并保存 **lucky** 等配置。
|
||
|
||
---
|
||
|
||
## 5. 流程小结
|
||
|
||
```
|
||
APP 启动
|
||
→ 获取 deviceId，计算 sign = MD5(deviceId) 大写 32 位
|
||
→ 可选：从 Adjust 获取归因 digest
|
||
→ POST /v1/user/fast_login（body: digest, resolution, origin；query: portal, crest, accolade）
|
||
→ 若成功：
|
||
1. 保存 userToken（knight）、userId（asset）、积分（reveal）、头像/昵称/国家码等
|
||
2. 若首次登录：记录注册日期并标记已注册
|
||
3. POST /v1/user/referrer（body: digest 从 Adjust 取, origin；query: sentinel, asset, portal）
|
||
→ 成功后打日志
|
||
4. GET /v1/user/common_info（query: sentinel, asset）
|
||
→ 将结果保存到全局
|
||
→ 对 data.surge 做 JSON decode，保存 lucky 等
|
||
→ 之后所有请求 Header 带 knight = userToken
|
||
```
|
||
|
||
接口的 V2 请求体/响应体、加解密与字段映射以 **petsHeroAI_client_guide.md** 为准。
|