跳轉至

驗證登入與查詢使用者資訊

登入驗證和用戶信息檢索 是一個通過從登入頁面重定向的臨時身份驗證碼(state)來驗證登入信息的API，並返回用戶信息。在返回用戶信息時，它包括訪問令牌和刷新令牌。

登入驗證與用戶信息檢索 API 請求返回的值大致如下。

  • IdP 資訊
  • 使用者資訊
  • 存取/更新令牌
Note

成功登入驗證後，需要用戶信息或令牌信息的情況如下。

  • 對於已成功驗證網頁登錄並生成 PlayerID 的用戶，響應包括用戶信息 (user_info)。然而，如果用戶信息已更改或需要單獨驗證，您可以通過調用 用戶信息檢索 API 來檢查它。
  • 如果需要訪問/刷新令牌，您必須再次執行網頁登錄或通過 令牌刷新 API 在令牌過期之前進行更新。

請求 URL

環境 URL
生產環境 https://weblogin.withhive.com/token
沙盒環境 https://sandbox-weblogin.withhive.com/token
HTTP 方法 POST
內容類型 application/json

請求主體

欄位名稱 類型 描述 必填
grant_type 字串 OAuth 2.0 授權碼流程 default: authorization_code Y
state 字串 登入後收到的臨時授權碼 (authorization_code) Y
client_id 字串 在安全金鑰設定中生成的 OAuth 2.0 客戶端 ID。您可以在 Hive 控制台 應用中心 > 安全金鑰設定 中查看它。 Y
client_secret 字串 在安全金鑰設定中生成的 OAuth 2.0 客戶端密鑰。您可以在 Hive 控制台 應用中心 > 安全金鑰設定 中查看它。 Y
redirect_uri 字串 這是重定向 URI 地址。它必須與 Hive 控制台 身份驗證 > 身份驗證環境設定 > 登入設定 中設置的 重定向 URI 匹配。 Y

請求主體範例

{
  "grant_type": "authorization_code",
  "state": "1627881984263-jkx1B3GOY3EsJ",
  "client_id": "58b48cd3-df47-5b52-2627-3f9c8d01",
  "client_secret": "bec7760b237244c4c818d6174587d8e1",
  "redirect_uri": "https://community.withhive.com/hivesdk/login/redirect"
}

回應主體

欄位名稱 類型 描述 備註
code 整數 網頁登入回應代碼
appid 字串 應用程式 ID
idp_index 整數 用於登入的 IdP 索引
  • 1: Hive
  • 2: Facebook
  • 3: Google
  • 9: Apple
idp_user_id 字串 用於 IdP 登入的唯一識別碼
enc_idp 字串 IdP 資訊的加密金鑰 外部 PC 自動登入令牌發放 金鑰
user_info JSON 用戶資訊
user_info.auth_ver 字串 認證伺服器版本
  • v4: Auth v4
user_info.user_id 大整數 Auth v4 玩家 ID
user_info.user_idp_list 陣列 連結的 IdP 列表 包含用戶連結的 IdP 資訊的列表
user_info.user_idp_list.player_id 大整數 連結的 IdP 列表 - Auth v4 玩家 ID
user_info.user_idp_list.idp_user_id 字串 連結的 IdP 列表 - IdP 的唯一識別碼
user_info.user_idp_list.idp_index 整數 連結的 IdP 列表 - IdP 索引
  • 1: Hive
  • 2: Facebook
  • 3: Google
  • 9: Apple
user_info.user_idp_list.idp_id 字串 連結的 IdP 列表 - IdP ID 即使使用其他 IdP 也會預設創建 GUEST
user_info.is_blocked 布林值 使用暫停狀態
  • true: 暫停的用戶
  • false: 正常用戶
user_info.is_refund 布林值 用戶是否有資格進行退款重付款
  • true: 用戶有資格進行退款重付款
  • false: 用戶不符合退款重付款資格
user_info.access_token 字串 存取權杖 (JWT) - 非對稱演算法
  • 如果沒有帳戶 (PlayerID) 則不會發出。
  • 有效期：1 小時
user_info.refresh_token 字串 刷新權杖 (JWT) - 非對稱演算法
  • 如果沒有帳戶 (PlayerID) 則不會發出。
  • 有效期：30 天

網頁登入回應代碼

代碼 描述 備註
100 成功
1050 無效的參數
1075 認證伺服器通信錯誤
2011 沒有項目信息
2013 項目處於終止狀態
2021 用戶尚未完成 IdP 認證或用戶的令牌會話已過期
2023 用戶的令牌信息異常
7000 OAuth2.0 安全金鑰未生成 在 Hive 控制台檢查 應用中心 > 安全金鑰設置
7001 OAuth2.0 客戶端 ID 值缺失 〃
7002 OAuth2.0 客戶端信息不匹配 〃
7003 OAuth2.0 客戶端信息未找到 〃
7004 OAuth2.0 不支持的令牌發行類型 檢查請求正文中的 grant_type
7005 OAuth2.0 重定向 URI 不匹配 檢查請求正文中的 redirect_uri
8001 OAuth2.0 JWT 令牌創建失敗

回應主體範例 (成功 - 用戶資訊存在)

當滿足以下條件時，這裡是返回的響應數據示例。

  • 當網頁登入成功完成時
  • 當 PlayerID 在認證伺服器上創建時
{
  "code": 100,
  "appid": "com.com2us.hivesdk.ios.community.global.normal",
  "idp_index": 3,
  "idp_user_id": "105213591741718897220",
  "enc_idp": "K+A4xduO7kf5OrJ/iDPqL2wrbMQTkNQ+jDz3OCCdGiezVsfW74kV0c/Qn2ipdP/ChFBUXoZkEUP03X26MVHnvgqHo9JG2BUCsRVcrsx+03IPRvpzjXAiY5c0tihk45jMWuPYo7q+j5Rsz8eSTKQo1vE9N85huOJWc8IAJKMqBRlpmiNfj+CgZQ5I7uV2u1nHhiLfwRqpt0vG/dT9mpdQisiKUS2mFIpgPnVSZaVMY7qnTvP+mTU11Yv2DhOq2VEycAic9Ko8UkBnllXEApqarqF5s4jg6bu9DxcnRNtZeaGbh4fZKEptjGuE6qqo3CsC1PN5TnU0Wf5uav07CaazsTpEBvA9SNZefWEeTDP2ePK8qd573vpXy4OQHpTOJkVm1AsN/Ir8Fssj9SKGdYyVuZ282VDAiFLAIlVyK4pAfjJRAve+G9tIm/i4mgQmuAqW",
  "user_info": {
    "auth_ver": "v4",
    "user_id": 20000018552,
    "user_idp_list": [
      {
        "player_id": 20000018552,
        "idp_user_id": "105213591741718897220",
        "idp_index": 3,
        "idp_id": "GOOGLE"
      },
      {
        "player_id": 20000018552,
        "idp_user_id": "0",
        "idp_index": 0,
        "idp_id": "GUEST"
      }
    ],
    "is_blocked": false,
    "is_refund": false,
    "access_token": "eyJraWQiOiIwYThlMThkOS1hNmZiLTM3ZDMtNjkwYy02Zjg1ZTllNCIsInR5cCI6IkpXVCIsImFsZyI6IlJTMjU2In0.eyJpc193aGl0ZWxpc3QiOmZhbHNlLCJwcm9qZWN0X2lkIjoiY29tLmNvbTJ1cy5oaXZlc2RrIiwiZ3JhbnRfdHlwZSI6InVzZXIiLCJ1c2VyX2lkIjoyMDAwMDAxODU1MiwidG9rZW5fdHlwZSI6ImFjY2Vzc190b2tlbiIsImV4cCI6MTc0NTU2MTk4MywiaWF0IjoxNzQ1NTU4MzgzLCJhdXRoX3ZlciI6InY0In0.e4mCIirRpAni4A1ZEF3FDOFng3Da8hq6IqZmyyRQZsc7W3LfFi_id5TIQSDbvmagmT4GcwHztovpoYZxf8blwqES1lJmEVXsBBJ3qpEOAem0K9aVwY0zmOO3A0Eeh6Y0APABewNCpHiKPCMZwxSsMaUE56FfuYgnbhpsipR638VgyPniRVU-Bzcu0Pi2zo-5yUKbg2FCXex510fvZRxqGZPg8Rfhm-jXqAYuwALLIFf2ZykOWqVRFtczfPXwB6fLQrQvQeBnOYcHHnR1q8Fi-Rk_bQPsAffIemGvaC4vUeyx6Szzt_Gok1BsuF76lYZ5ogCn4lAlZ0SJLrgMM2-DNQ",
    "refresh_token": "eyJraWQiOiIwYThlMThkOS1hNmZiLTM3ZDMtNjkwYy02Zjg1ZTllNCIsInR5cCI6IkpXVCIsImFsZyI6IlJTMjU2In0.eyJpc193aGl0ZWxpc3QiOmZhbHNlLCJwcm9qZWN0X2lkIjoiY29tLmNvbTJ1cy5oaXZlc2RrIiwiZ3JhbnRfdHlwZSI6InVzZXIiLCJ1c2VyX2lkIjoyMDAwMDAxODU1MiwidG9rZW5fdHlwZSI6InJlZnJlc2hfdG9rZW4iLCJleHAiOjE3NDgxNTAzODMsImlhdCI6MTc0NTU1ODM4MywiYXV0aF92ZXIiOiJ2NCJ9.fvXTfRDYhlk21EY-ngAXbQMgYM9f-rFYPBa_GMV3JDz3cy9wwGfPTnF-VO0WkpxzpPdbG1ZX0HAdIkT4kF873ee2d-g6-JeuIEy0SFcTMpdYWXnlOfsuZlFIkzCm0OB_mlnNo_wxXHvjHM_dFDF-SfK2r9_ga8yLOXDfLJeA4XUYGwwsG3XT9x5Vy8RlUcF2aeuf-2bXdLSD2NGssZh18RTayV2CNtGuX0kj-nABVVTzLWUqbwKSrIVXjlS76zxl3SisUW_pz97iM98yLLRdpe_56_VDPzKEqVmn4bCyhhlAT1LEdu_uudlBY7hSUX0cJzcLAtj_4GReuLU9SnvQpw"
  }
}

回應主體範例（成功 - 無用戶信息）

當滿足以下條件時，這裡是返回的響應數據示例。

  • 如果網頁登入成功完成
  • 即使在認證伺服器上未創建 PlayerID，開發者仍然可以使用 IdP 識別碼（idp_index、idp_user_id）作為用戶的帳戶識別碼來處理登入。然而，如果在沒有用戶信息的情況下進行登入，將不會有 PlayerID，因此無法使用 保持登入（SSO）。
{
  "code": 100,
  "appid": "com.com2us.hivesdk.ios.community.global.normal",
  "idp_index": 3,
  "idp_user_id": "105213591741718897220",
  "enc_idp": "K+A4xduO7kf5OrJ/iDPqL2wrbMQTkNQ+jDz3OCCdGiezVsfW74kV0c/Qn2ipdP/ChFBUXoZkEUP03X26MVHnvgqHo9JG2BUCsRVcrsx+03IPRvpzjXAiY5c0tihk45jMWuPYo7q+j5Rsz8eSTKQo1vE9N85huOJWc8IAJKMqBRlpmiNfj+CgZQ5I7uV2u1nHhiLfwRqpt0vG/dT9mpdQisiKUS2mFIpgPnVSZaVMY7qnTvP+mTU11Yv2DhOq2VEycAic9Ko8UkBnllXEApqarqF5s4jg6bu9DxcnRNtZeaGbh4fZKEptjGuE6qqo3CsC1PN5TnU0Wf5uav07CaazsTpEBvA9SNZefWEeTDP2ePK8qd573vpXy4OQHpTOJkVm1AsN/Ir8Fssj9SKGdYyVuZ282VDAiFLAIlVyK4pAfjJRAve+G9tIm/i4mgQmuAqW"
}

回應主體範例 (失敗)

這是當滿足以下條件時返回的響應數據的示例。

  • 如果網頁登錄失敗
{
  "code": 1050
}

外部 PC 自動登入令牌發放

  • 當運行 Hive 跨平台啟動器時，相應的令牌值 (web_idp_token) 會被傳遞以進行自動登錄。
  • web_idp_token 是一個一次性令牌，每次啟動遊戲時都需要重新獲取。
Note
  • 請小心不要暴露為安全原因而傳遞請求的 enc_idp 值。
  • 在進行 API 調用時，必須應用伺服器到伺服器。

請求 URL

環境 URL
生產環境 https://authcp.qpyou.cn/auth/get-web-idp-token
沙盒環境 https://sandbox-authcp.qpyou.cn/auth/get-web-idp-token
HTTP 方法 POST
內容類型 application/json

請求正文

欄位名稱 類型 描述 必填
appid 字串 應用程式 ID Y
enc_idp 字串 IdP 資訊的加密金鑰 Y

請求主體範例

{
  "appid": "com.com2us.hivesdk.ios.community.global.normal",
  "enc_idp": "K+A4xduO7kf5OrJ/iDPqL2wrbMQTkNQ+jDz3OCCdGiezVsfW74kV0c/Qn2ipdP/ChFBUXoZkEUP03X26MVHnvgqHo9JG2BUCsRVcrsx+03IPRvpzjXAiY5c0tihk45jMWuPYo7q+j5Rsz8eSTKQo1vE9N85huOJWc8IAJKMqBRlpmiNfj+CgZQ5I7uV2u1nHhiLfwRqpt0vG/dT9mpdQisiKUS2mFIpgPnVSZaVMY7qnTvP+mTU11Yv2DhOq2VEycAic9Ko8UkBnllXEApqarqF5s4jg6bu9DxcnRNtZeaGbh4fZKEptjGuE6qqo3CsC1PN5TnU0Wf5uav07CaazsTpEBvA9SNZefWEeTDP2ePK8qd573vpXy4OQHpTOJkVm1AsN/Ir8Fssj9SKGdYyVuZ282VDAiFLAIlVyK4pAfjJRAve+G9tIm/i4mgQmuAqW"
}

回應主體

欄位名稱 類型 描述 備註
result_code 整數 結果代碼
result_msg 字串 結果訊息
data JSON 結果數據
data.web_idp_token 字串 外部PC自動登錄令牌

回應主體範例

{
  "result_code": 0,
  "result_msg": "SUCCESS",
  "data": {
    "web_idp_token": "c47e61856f04f0a6194ddcbabca70a7f10552d044181386e625676fd07a63aee5d2b162a78a55bad350ed58fb07b79be8fea1c786108307f32b602019f31ac8d"
  }
}

結果代碼

result_code 描述
0 成功
4000 無效的請求參數
4012 enc_idp 解密錯誤