自定义网页登录实现
本文介绍如何不使用 Hive Platform 提供的 网页登录页面，而是利用 Hive server API 直接实现网页登录。如果游戏公司希望构建自有登录 UI 并直接处理 IdP 认证，请参考本文档。
Note
要使用自定义网页登录 API，必须先在 Hive Console 中完成应用注册及 hive_certification_key 签发。
概述
自定义网页登录适用于以下情况。
- 希望应用游戏公司自有的登录 UI/UX
- 希望实现与现有网站设计统一的登录界面
- 希望不重定向到网页登录页面，而是在自有页面内处理登录
API 列表
| API Endpoint | 说明 |
POST /game/auth/signinidp | IdP 登录 |
POST /game/auth/connect | IdP 绑定 |
POST /game/auth/disconnect | IdP 解绑 |
POST /game/player/delete | 账号删除 |
| Header 名称 | 类型 | 是否必填 | 说明 |
| Content-Type | String | Y | 固定为 application/json |
| Authorization | String | Y or N | 会话令牌。在需要令牌验证的 API 中必填，否则可省略 |
| ISCRYPT | Integer | Y | 是否加密。固定为 0 |
| Header 名称 | 类型 | 说明 |
| Authorization | String | 新签发的会话令牌。仅在 IdP 登录 请求中 require_token: true 时签发 |
| ISCRYPT | Integer | 响应是否加密 |
通用响应格式
成功响应
{
"result_code": 0,
"result_msg": "SUCCESS",
"data": { }
}
失败响应
{
"result_code": 4000,
"result_msg": "Request has invalid format.",
"data": null
}
IdP 登录
使用 IdP 信息创建新玩家；如果该 IdP 已注册，则返回现有玩家信息。登录成功时，可通过 data.player_id 确认 PlayerID。
Warning
自定义网页登录 API 不支持创建访客（GUEST, idp_index: 0）账号。
Note
若要使用 账号删除 API，需要将 require_token 设置为 true，以便在响应 Header 中签发 Authorization 值。如果不使用账号删除功能，则可设置为 false。
Request URL
| 环境 | URL |
| 生产环境 (Production) | https://auth.qpyou.cn/game/auth/signinidp |
| 沙盒环境 (Sandbox) | https://sandbox-auth.qpyou.cn/game/auth/signinidp |
| HTTP Method | POST |
| Content-Type | application/json |
Request Body
| 字段名 | 类型 | 说明 | 是否必填 |
| appid | String | 游戏 App ID (AppID) | Y |
| idp_index | Integer | IdP 索引代码。参考 IdP 代码定义 | Y |
| idp_user_id | String | IdP 用户唯一标识符 | Y |
| hive_certification_key | String | Hive 认证密钥 | Y |
| require_token | Boolean | 是否请求玩家令牌。使用 账号删除 API 时为 true，不使用时为 false | Y |
Request Body 示例
{
"appid": "com.com2us.example",
"idp_index": 3,
"idp_user_id": "google_67890",
"hive_certification_key": "your_certification_key",
"require_token": true
}
| 字段名 | 类型 | 说明 |
| Content-Type | String | 响应数据格式（JSON）及字符编码（UTF-8）信息 |
| Authorization | String | 会话令牌 |
HTTP/1.1 200
Content-Type: application/json; charset=UTF-8
Authorization: abcdf7ebce779429ea878f91d5f1c8
Iscrypt: 0
Response Body
| 字段名 | 类型 | 说明 |
| result_code | Integer | 结果代码。为 0 时成功 |
| result_msg | String | 结果消息 |
| data.player_id | Integer | PlayerID |
| data.idp_index | Integer | IdP 索引 |
| data.idp_id | String | IdP 名称 |
| data.idp_user_id | String | IdP 用户 ID |
Response Body 示例（成功）
{
"result_code": 0,
"result_msg": "SUCCESS",
"data": {
"player_id": 100000002,
"idp_index": 3,
"idp_id": "GOOGLE",
"idp_user_id": "google_67890"
}
}
Response Body 示例（失败）
{
"result_code": 4002,
"result_msg": "Invalid certfication key"
}
错误代码
| 代码 | 说明 | 备注 |
| 4002 | 认证密钥错误 | |
| 4200 | 不存在的 IdP | |
| 5000 | 数据库错误 | |
IdP 绑定
将新的 IdP 绑定到现有玩家账号。必须先调用 IdP 登录 API 完成登录后再调用。
Request URL
| 环境 | URL |
| 生产环境 (Production) | https://auth.qpyou.cn/game/auth/connect |
| 沙盒环境 (Sandbox) | https://sandbox-auth.qpyou.cn/game/auth/connect |
| HTTP Method | POST |
| Content-Type | application/json |
Request Body
| 字段名 | 类型 | 说明 | 是否必填 |
| appid | String | 游戏 App ID (AppID) | Y |
| idp_index | Integer | IdP 索引代码。参考 IdP 代码定义 | Y |
| idp_user_id | String | IdP 用户唯一标识符 | Y |
| player_id | Integer | 要绑定的 PlayerID | Y |
| hive_certification_key | String | Hive 认证密钥 | Y |
Request Body 示例
{
"appid": "com.com2us.example",
"idp_index": 2,
"idp_user_id": "fb_12345678",
"player_id": 100000001,
"hive_certification_key": "your_certification_key"
}
Response Body
| 字段名 | 类型 | 说明 |
| result_code | Integer | 结果代码。为 0 时成功 |
| result_msg | String | 结果消息 |
| data.player_id | Integer | PlayerID |
| data.idp_index | Integer | 已绑定的 IdP 索引 |
| data.idp_id | String | 已绑定的 IdP 名称 |
| data.idp_user_id | String | IdP 用户 ID |
Response Body 示例（成功）
{
"result_code": 0,
"result_msg": "SUCCESS",
"data": {
"player_id": 100000001,
"idp_index": 2,
"idp_id": "FACEBOOK",
"idp_user_id": "fb_12345678"
}
}
Response Body 示例（已绑定到其他玩家时）
{
"result_code": 1002,
"result_msg": "Already connected other player",
"data": {
"player_id": 100000002,
"idp_index": 2,
"idp_id": "FACEBOOK",
"idp_user_id": "fb_12345678"
}
}
错误代码
| 代码 | 说明 | 备注 |
| 1002 | 该 IdP 已绑定到其他玩家 | |
| 1003 | 相同的 IdP 类型已绑定 | |
| 2002 | 不存在的玩家 | |
| 4002 | 认证密钥错误 | |
| 4200 | 不存在的 IdP | |
| 5000 | 数据库错误 | |
IdP 解绑
将玩家账号中已绑定的 IdP 解绑。必须先调用 IdP 登录 API 完成登录后再调用。
Request URL
| 环境 | URL |
| 生产环境 (Production) | https://auth.qpyou.cn/game/auth/disconnect |
| 沙盒环境 (Sandbox) | https://sandbox-auth.qpyou.cn/game/auth/disconnect |
| HTTP Method | POST |
| Content-Type | application/json |
Request Body
| 字段名 | 类型 | 说明 | 是否必填 |
| appid | String | 游戏 App ID (AppID) | Y |
| idp_index | Integer | IdP 索引代码。参考 IdP 代码定义 | Y |
| idp_user_id | String | IdP 用户唯一标识符 | Y |
| player_id | Integer | PlayerID | Y |
| hive_certification_key | String | Hive 认证密钥 | Y |
Request Body 示例
{
"appid": "com.com2us.example",
"idp_index": 2,
"idp_user_id": "fb_12345678",
"player_id": 100000001,
"hive_certification_key": "your_certification_key"
}
Response Body
| 字段名 | 类型 | 说明 |
| result_code | Integer | 结果代码。为 0 时成功 |
| result_msg | String | 结果消息 |
Response Body 示例（成功）
{
"result_code": 0,
"result_msg": "SUCCESS"
}
Response Body 示例（失败）
{
"result_code": 4002,
"result_msg": "Invalid certfication key"
}
错误代码
| 代码 | 说明 | 备注 |
| 4002 | 认证密钥错误 | |
| 4006 | 无已绑定的 IdP 信息 | |
| 4200 | 不存在的 IdP | |
| 7000 | 无效的令牌 | |
账号删除
删除玩家账号。必须先调用 IdP 登录 API 完成登录后再调用。
此 API 必须进行令牌验证，因此必须先执行以下操作。
- 调用 IdP 登录 API 时，将
require_token 设置为 true - 保存 IdP 登录 API 响应 Header 中传递的
Authorization 值 - 调用此 API 时，在请求 Header 中包含上述保存的
Authorization 值
Warning
账号删除无法恢复。删除前请向用户提供充分说明。
Request URL
| 环境 | URL |
| 生产环境 (Production) | https://auth.qpyou.cn/game/player/delete |
| 沙盒环境 (Sandbox) | https://sandbox-auth.qpyou.cn/game/player/delete |
| HTTP Method | POST |
| Content-Type | application/json |
| Header 名称 | 类型 | 说明 | 是否必填 |
| Authorization | String | 调用 IdP 登录 时设置 require_token: true 后，通过响应 Header 传递的会话令牌 | Y |
Request Body
| 字段名 | 类型 | 说明 | 是否必填 |
| appid | String | 游戏 App ID (AppID) | Y |
| player_id | Integer | 要删除的 PlayerID | Y |
| did | Integer | 设备 ID。固定为 0 | Y |
| hive_certification_key | String | Hive 认证密钥 | Y |
Request Body 示例
{
"appid": "com.com2us.example",
"player_id": 100000001,
"did": 0,
"hive_certification_key": "your_certification_key"
}
Response Body
| 字段名 | 类型 | 说明 |
| result_code | Integer | 结果代码。为 0 时成功 |
| result_msg | String | 结果消息 |
Response Body 示例（成功）
{
"result_code": 0,
"result_msg": "SUCCESS"
}
Response Body 示例（失败）
{
"result_code": 7000,
"result_msg": "Invalid token."
}
错误代码
| 代码 | 说明 | 备注 |
| 4002 | 认证密钥错误 | |
| 7000 | 无效的令牌 | |
| 7001 | Header 中没有令牌 | |
IdP 代码定义
基本 IdP
| 代码 | IDP_ID | 说明 |
| 0 | GUEST | 访客 |
| 1 | HIVE | 会员账号 |
| 2 | FACEBOOK | Facebook |
| 3 | GOOGLE | Google |
| 4 | QQ | QQ |
| 5 | WEIBO | Weibo |
| 6 | VK | VK |
| 7 | WECHAT | WeChat |
| 8 | APPLE | Apple Game Center |
| 9 | SIGNIN_APPLE | Sign in with Apple |
| 10 | LINE | LINE |
| 11 | TWITTER | Twitter |
| 12 | WEVERSE | Weverse |
| 13 | NAVER | Naver |
| 14 | GOOGLE_PLAY_GAMES | Google Play Games |
| 15 | HUAWEI | Huawei |
| 16 | FUNTAP | Funtap |
| 18 | STEAM | Steam |
| 19 | X | X（原 Twitter） |
| 20 | TELEGRAM | Telegram |
| 21 | XIAOMI | Xiaomi |
| 22 | OPPO | OPPO |
| 23 | VIVO | VIVO |
自定义 IdP
| 代码 | IDP_ID | 说明 |
| 1100 | CUSTOM_GAME | 游戏公司自行提供的 IdP |