自訂網頁登入實作¶

This guide explains how to implement web login directly using the Hive server API instead of the web login page provided by Hive Platform. Refer to this document when the app needs its own login UI and direct IdP authentication handling.

Note

To use the custom web login API, app registration and OAuth 2.0 Access Token issuance must be completed in Hive Console.

Overview¶

Use custom web login in the following cases.

When you want to apply an app-specific login UI/UX
When you want to implement a login screen consistent with the existing website design
When you want to process login within your own page without redirecting to the web login page

API Endpoint	說明
`POST /v2/game/auth/signinidp`	IdP sign-in
`POST /v2/game/auth/connect`	IdP linking
`POST /v2/game/auth/disconnect`	IdP unlinking
`POST /v2/game/player/delete-project`	Delete account

IdP sign-in¶

Creates a new player with IdP information or returns existing player information if the IdP is already registered. When sign-in succeeds, check the PlayerID in data.player_id.

Warning

自訂網頁登入 API 不支援建立訪客（GUEST，idp_index: 0）帳號。

Note

To use the Delete account API, set require_token to true to receive the Authorization value in the response header. If you do not use account deletion, set it to false.

請求 URL¶

正式 URL	https://auth.qpyou.cn/v2/game/auth/signinidp
沙盒 URL	https://sandbox-auth.qpyou.cn/v2/game/auth/signinidp
HTTP 方法	POST
Content-Type	application/json
資料格式	JSON

請求標頭¶

欄位名稱	說明	類型	必填
X-Access-Token	用於應用程式伺服器認證的 OAuth 2.0 Access Token （請參閱發行 OAuth Token）	String	Y
ISCRYPT	資料是否加密（0 = 不加密）（必須傳遞 0）	Integer	Y

請求本文¶

欄位名稱	說明	類型	必填
appid	App ID	String	Y
idp_index	IdP index code (IdP list)	Integer	Y
idp_user_id	Unique IdP user identifier	String	Y
require_token	Whether to request a player token. `true` when using Delete account, otherwise `false`	Boolean	Y

請求範例¶

{"appid":"com.com2us.hivesdk.normal.freefull.apple.global.ios.universal","idp_index":3,"idp_user_id":"google_67890","require_token":true}

Response header¶

欄位名稱	說明	類型
Authorization	Session token. Used when calling Delete account API	String

回應本文¶

欄位名稱	說明	類型
result_code	回應代碼 Details	Integer
result_msg	結果訊息	String
token_validation	JWT 驗證結果（JWT 驗證錯誤）	Object
token_validation.result_code	JWT 驗證結果代碼	Integer
token_validation.result_msg	JWT 驗證結果訊息	String
data	結果資料	Object
data.player_id	Player ID	Integer
data.idp_index	IdP index	Integer
data.idp_id	IdP name	String
data.idp_user_id	IdP user ID	String

回應代碼¶

Code value	說明
0	成功
2499	JWT 驗證失敗（請參閱 token_validation）
4200	IdP does not exist
5000	Internal server error

IdP linking¶

Links a new IdP to an existing player account. You must call this API after signing in with the IdP sign-in API.

請求 URL¶

正式 URL	https://auth.qpyou.cn/v2/game/auth/connect
沙盒 URL	https://sandbox-auth.qpyou.cn/v2/game/auth/connect
HTTP 方法	POST
Content-Type	application/json
資料格式	JSON

請求標頭¶

欄位名稱	說明	類型	必填
X-Access-Token	用於應用程式伺服器認證的 OAuth 2.0 Access Token （請參閱發行 OAuth Token）	String	Y
ISCRYPT	資料是否加密（0 = 不加密）（必須傳遞 0）	Integer	Y

請求本文¶

欄位名稱	說明	類型	必填
appid	App ID	String	Y
idp_index	IdP index code (IdP list)	Integer	Y
idp_user_id	Unique IdP user identifier	String	Y
player_id	Player ID to link	Integer	Y

請求範例¶

{"appid":"com.com2us.hivesdk.normal.freefull.apple.global.ios.universal","idp_index":2,"idp_user_id":"fb_12345678","player_id":100000001}

回應本文¶

欄位名稱	說明	類型
result_code	回應代碼 Details	Integer
result_msg	結果訊息	String
token_validation	JWT 驗證結果（JWT 驗證錯誤）	Object
token_validation.result_code	JWT 驗證結果代碼	Integer
token_validation.result_msg	JWT 驗證結果訊息	String
data	結果資料	Object
data.player_id	Player ID	Integer
data.idp_index	Linked IdP index	Integer
data.idp_id	Linked IdP name	String
data.idp_user_id	IdP user ID	String

回應代碼¶

Code value	說明
0	成功
1002	The IdP is already linked to another player
1003	The same IdP type is already linked
2002	Player does not exist
2499	JWT 驗證失敗（請參閱 token_validation）
4200	IdP does not exist
5000	Internal server error

IdP unlinking¶

Unlinks an IdP from a player account. You must call this API after signing in with the IdP sign-in API.

請求 URL¶

正式 URL	https://auth.qpyou.cn/v2/game/auth/disconnect
沙盒 URL	https://sandbox-auth.qpyou.cn/v2/game/auth/disconnect
HTTP 方法	POST
Content-Type	application/json
資料格式	JSON

請求標頭¶

欄位名稱	說明	類型	必填
X-Access-Token	用於應用程式伺服器認證的 OAuth 2.0 Access Token （請參閱發行 OAuth Token）	String	Y
ISCRYPT	資料是否加密（0 = 不加密）（必須傳遞 0）	Integer	Y

請求本文¶

欄位名稱	說明	類型	必填
appid	App ID	String	Y
idp_index	IdP index code (IdP list)	Integer	Y
idp_user_id	Unique IdP user identifier	String	Y
player_id	Player ID	Integer	Y

回應本文¶

欄位名稱	說明	類型
result_code	回應代碼 Details	Integer
result_msg	結果訊息	String
token_validation	JWT 驗證結果（JWT 驗證錯誤）	Object
token_validation.result_code	JWT 驗證結果代碼	Integer
token_validation.result_msg	JWT 驗證結果訊息	String

回應代碼¶

Code value	說明
0	成功
2499	JWT 驗證失敗（請參閱 token_validation）
4006	Linked IdP information does not exist
4200	IdP does not exist
5000	Internal server error
7000	Invalid token

Delete account¶

Deletes a player account. You must call this API after signing in with the IdP sign-in API.

Set require_token to true when calling the IdP sign-in API.
Store the Authorization value returned in the response header.
Include the stored Authorization value in the request header when calling this API.

Warning

Account deletion cannot be undone. Provide sufficient notice to the user before deletion.

請求 URL¶

正式 URL	https://auth.qpyou.cn/v2/game/player/delete-project
沙盒 URL	https://sandbox-auth.qpyou.cn/v2/game/player/delete-project
HTTP 方法	POST
Content-Type	application/json
資料格式	JSON

請求標頭¶

欄位名稱	說明	類型	必填
X-Access-Token	用於應用程式伺服器認證的 OAuth 2.0 Access Token （請參閱發行 OAuth Token）	String	Y
ISCRYPT	資料是否加密（0 = 不加密）（必須傳遞 0）	Integer	Y
Authorization	Session token received in the response header after calling IdP sign-in with `require_token: true`	String	Y

請求本文¶

欄位名稱	說明	類型	必填
appid	App ID	String	Y
player_id	Player ID to delete	Integer	Y
did	Device ID. Fixed to `0`	Integer	Y

回應代碼¶

Code value	說明
0	成功
2499	JWT 驗證失敗（請參閱 token_validation）
5000	Internal server error
7000	Invalid token
7001	No token in header

Note

JWT 驗證失敗時，可在 token_validation 欄位中查看詳細錯誤資訊。詳情請參閱 JWT 驗證錯誤代碼。