5.1 KiB
5.1 KiB
用户登录流程
本文档基于 docs/petsHeroAI_client_guide.md 中的登录态接口，整理客户端登录顺序与数据处理要求。
1. 整体顺序
- 设备快速登录：
POST /v1/user/fast_login，拿到userToken和用户信息。 - 保存登录态与用户信息：保存 token、积分、userId、头像、昵称、国家码等；首次登录记录为注册日期。
- 归因上报：
POST /v1/user/referrer，将归因数据（如从 Adjust 获取的 digest）上报。 - 获取用户通用信息：
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 为准。