自訂 Web 登入實作¶

本文說明如何不使用 Hive 平台提供的 Web 登入頁面，而是利用 Hive 伺服器 API 直接實作 Web 登入。如果開發商想自行建置登入 UI，並直接處理 IdP 驗證，請參閱本文。

Note

若要使用自訂 Web 登入 API，必須先在 Hive Console 中完成 App 註冊及 hive_certification_key 核發。

概要¶

自訂 Web 登入適用於下列情況。

想套用開發商專屬的登入 UI/UX 時
想實作與既有網站設計一致的登入畫面時
想在自有頁面內處理登入，而不重新導向至 Web 登入頁面時

API 清單¶

API Endpoint	說明
`POST /game/auth/signinidp`	IdP 登入
`POST /game/auth/connect`	IdP 連結
`POST /game/auth/disconnect`	IdP 解除連結
`POST /game/player/delete`	帳號刪除

通用請求標頭¶

標頭名稱	類型	必填	說明
Content-Type	String	Y	固定為 `application/json`
Authorization	String	Y or N	工作階段權杖。需要驗證權杖的 API 必填，否則可省略
ISCRYPT	Integer	Y	是否加密。固定為 `0`

通用回應標頭¶

標頭名稱	類型	說明
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，以取得回應標頭中的 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 Example¶

{
    "appid": "com.com2us.example",
    "idp_index": 3,
    "idp_user_id": "google_67890",
    "hive_certification_key": "your_certification_key",
    "require_token": true
}

Response Header¶

欄位名稱	類型	說明
Content-Type	String	回應資料格式 (JSON) 與字元編碼 (UTF-8) 資訊
Authorization	String	工作階段權杖

Response Header Example¶

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 Sample (成功)¶

{
    "result_code": 0,
    "result_msg": "SUCCESS",
    "data": {
        "player_id": 100000002,
        "idp_index": 3,
        "idp_id": "GOOGLE",
        "idp_user_id": "google_67890"
    }
}

Response Body Sample (失敗)¶

{
    "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 Example¶

{
    "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 Sample (成功)¶

{
    "result_code": 0,
    "result_msg": "SUCCESS",
    "data": {
        "player_id": 100000001,
        "idp_index": 2,
        "idp_id": "FACEBOOK",
        "idp_user_id": "fb_12345678"
    }
}

Response Body Sample (已連結到其他玩家時)¶

{
    "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 Example¶

{
    "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 Sample (成功)¶

{
    "result_code": 0,
    "result_msg": "SUCCESS"
}

Response Body Sample (失敗)¶

{
    "result_code": 4002,
    "result_msg": "Invalid certfication key"
}

錯誤碼¶

代碼	說明	備註
4002	認證金鑰錯誤
4006	沒有已連結的 IdP 資訊
4200	不存在的 IdP
7000	無效的權杖

帳號刪除¶

刪除玩家帳號。必須先透過 IdP 登入 API 登入後再呼叫。

此 API 必須驗證權杖，因此務必先完成下列作業。

呼叫 IdP 登入 API 時，將 require_token 設為 true
儲存由 IdP 登入 API 回應標頭傳回的 Authorization 值
呼叫此 API 時，在請求標頭中包含上方儲存的 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`

Request Header¶

標頭名稱	類型	說明	必填
Authorization	String	呼叫 IdP 登入時設為 `require_token: true` 後，透過回應標頭傳回的工作階段權杖	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 Example¶

{
    "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 Sample (成功)¶

{
    "result_code": 0,
    "result_msg": "SUCCESS"
}

Response Body Sample (失敗)¶

{
    "result_code": 7000,
    "result_msg": "Invalid token."
}

錯誤碼¶

代碼	說明	備註
4002	認證金鑰錯誤
7000	無效的權杖
7001	標頭中沒有權杖

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