ข้ามไปที่เนื้อหา

การใช้งานเว็บล็อกอินแบบกำหนดเอง

เอกสารนี้อธิบายวิธีนำเว็บล็อกอินไปใช้งานด้วย Hive Server API โดยตรงโดยไม่ใช้ หน้าเว็บล็อกอิน ที่ Hive Platform มีให้ หากแอปต้องการสร้าง UI สำหรับเข้าสู่ระบบของตนเองและจัดการการยืนยันตัวตนของ IdP โดยตรง ให้ดูเอกสารนี้

Note

หากต้องการใช้ API เว็บล็อกอินแบบกำหนดเอง ต้องลงทะเบียนแอปและดำเนินการ การออก OAuth 2.0 Access Token ให้เสร็จสิ้นใน Hive Console

ภาพรวม

ใช้เว็บล็อกอินแบบกำหนดเองในกรณีต่อไปนี้

  • เมื่อต้องการใช้ UI/UX สำหรับเข้าสู่ระบบที่เป็นเอกลักษณ์ของแอป
  • เมื่อต้องการสร้างหน้าจอเข้าสู่ระบบให้สอดคล้องกับดีไซน์ของเว็บไซต์เดิม
  • เมื่อต้องการให้ผู้ใช้เข้าสู่ระบบภายในหน้าของตนเองโดยไม่ต้องรีไดเรกต์ไปยังหน้าเว็บล็อกอิน

API ที่มีให้ในฟีเจอร์ 'การใช้งานเว็บล็อกอินแบบกำหนดเอง' มีดังนี้

API Endpoint คำอธิบาย
POST /v2/game/auth/signinidp การเข้าสู่ระบบด้วย IdP
POST /v2/game/auth/connect การเชื่อมโยง IdP
POST /v2/game/auth/disconnect ยกเลิกการเชื่อมโยง IdP
POST /v2/game/player/delete-project ลบบัญชี


การเข้าสู่ระบบด้วย IdP

สร้างผู้เล่นใหม่ด้วยข้อมูล IdP หรือส่งคืนข้อมูลผู้เล่นเดิมหาก IdP นั้นลงทะเบียนไว้แล้ว เมื่อเข้าสู่ระบบสำเร็จ คุณสามารถตรวจสอบ PlayerID ได้จาก data.player_id

Warning

API เว็บล็อกอินแบบกำหนดเองไม่รองรับการสร้างบัญชี guest (GUEST, idp_index: 0)

Note

หากต้องการใช้ API ลบบัญชี ต้องตั้งค่า require_token เป็น true เพื่อรับค่า Authorization ในส่วนหัวการตอบกลับ หากไม่ใช้ฟังก์ชันลบบัญชี สามารถตั้งค่าเป็น false ได้

URL คำขอ

URL ใช้งานจริง https://auth.qpyou.cn/v2/game/auth/signinidp
URL Sandbox 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 (โปรดดู รายการ IdP) Integer Y
idp_user_id ตัวระบุผู้ใช้เฉพาะของ IdP String Y
require_token ต้องการโทเค็นผู้เล่นหรือไม่ เมื่อต้องใช้ API ลบบัญชี ให้ตั้งค่าเป็น true และหากไม่ใช้ให้ตั้งค่าเป็น false Boolean Y

ตัวอย่างคำขอ

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

ส่วนหัวการตอบกลับ

จะมีส่วนหัวต่อไปนี้รวมอยู่ด้วยเมื่อ require_token: true

ชื่อฟิลด์ คำอธิบาย ประเภท
Authorization เซสชันโทเค็น ใช้เมื่อเรียก API ลบบัญชี String

เนื้อหาการตอบกลับ

ชื่อฟิลด์ คำอธิบาย ประเภท
result_code รหัสตอบกลับ รายละเอียด 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 Integer
data.idp_id ชื่อ IdP String
data.idp_user_id ID ผู้ใช้ IdP String

ตัวอย่างการตอบกลับ

สำเร็จ

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

รหัสตอบกลับ

ค่ารหัส คำอธิบาย
0 สำเร็จ
2499 การตรวจสอบ JWT ล้มเหลว (ดู token_validation)
4200 ไม่มี IdP นี้
5000 ข้อผิดพลาดภายในเซิร์ฟเวอร์


การเชื่อมโยง IdP

เชื่อมโยง IdP ใหม่กับบัญชีผู้เล่นเดิม ต้องเรียกใช้หลังจากเข้าสู่ระบบผ่าน API การเข้าสู่ระบบด้วย IdP เท่านั้น

URL คำขอ

URL ใช้งานจริง https://auth.qpyou.cn/v2/game/auth/connect
URL Sandbox 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 (โปรดดู รายการ IdP) Integer Y
idp_user_id ตัวระบุผู้ใช้เฉพาะของ IdP String Y
player_id Player ID ที่จะเชื่อมโยง 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 รหัสตอบกลับ รายละเอียด 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 ที่เชื่อมโยงแล้ว Integer
data.idp_id ชื่อ IdP ที่เชื่อมโยงแล้ว String
data.idp_user_id ID ผู้ใช้ IdP String

ตัวอย่างการตอบกลับ

สำเร็จ

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

กรณีที่เชื่อมโยงกับผู้เล่นคนอื่นไว้แล้ว

{
    "result_code": 1002,
    "result_msg": "Already connected other player",
    "token_validation": {
        "result_code": 0,
        "result_msg": "success"
    },
    "data": {
        "player_id": 100000002,
        "idp_index": 2,
        "idp_id": "FACEBOOK",
        "idp_user_id": "fb_12345678"
    }
}

รหัสตอบกลับ

ค่ารหัส คำอธิบาย
0 สำเร็จ
1002 IdP นี้เชื่อมโยงกับผู้เล่นคนอื่นอยู่แล้ว
1003 เชื่อมโยง IdP ประเภทเดียวกันไว้แล้ว
2002 ไม่มีผู้เล่นนี้
2499 การตรวจสอบ JWT ล้มเหลว (ดู token_validation)
4200 ไม่มี IdP นี้
5000 ข้อผิดพลาดภายในเซิร์ฟเวอร์


ยกเลิกการเชื่อมโยง IdP

ยกเลิกการเชื่อมโยง IdP ที่เชื่อมโยงกับบัญชีผู้เล่น ต้องเรียกใช้หลังจากเข้าสู่ระบบผ่าน API การเข้าสู่ระบบด้วย IdP เท่านั้น

URL คำขอ

URL ใช้งานจริง https://auth.qpyou.cn/v2/game/auth/disconnect
URL Sandbox 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 (โปรดดู รายการ IdP) Integer Y
idp_user_id ตัวระบุผู้ใช้เฉพาะของ IdP String Y
player_id Player ID 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 รหัสตอบกลับ รายละเอียด Integer
result_msg ข้อความผลลัพธ์ String
token_validation ผลการตรวจสอบ JWT (ข้อผิดพลาดการตรวจสอบ JWT) Object
token_validation.result_code รหัสผลการตรวจสอบ JWT Integer
token_validation.result_msg ข้อความผลการตรวจสอบ JWT String

ตัวอย่างการตอบกลับ

สำเร็จ

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

รหัสตอบกลับ

ค่ารหัส คำอธิบาย
0 สำเร็จ
2499 การตรวจสอบ JWT ล้มเหลว (ดู token_validation)
4006 ไม่มีข้อมูล IdP ที่เชื่อมโยง
4200 ไม่มี IdP นี้
5000 ข้อผิดพลาดภายในเซิร์ฟเวอร์
7000 โทเค็นไม่ถูกต้อง


ลบบัญชี

ลบบัญชีผู้เล่น ต้องเรียกใช้หลังจากเข้าสู่ระบบผ่าน API การเข้าสู่ระบบด้วย IdP เท่านั้น

API นี้ต้องตรวจสอบโทเค็น จึงต้องดำเนินการต่อไปนี้ล่วงหน้า

  1. เมื่อเรียก API การเข้าสู่ระบบด้วย IdP ให้ตั้งค่า require_token เป็น true
  2. จัดเก็บค่า Authorization ที่ได้รับจากส่วนหัวการตอบกลับของ API การเข้าสู่ระบบด้วย IdP
  3. เมื่อเรียก API นี้ ให้ใส่ค่า Authorization ที่จัดเก็บไว้ข้างต้นในส่วนหัวคำขอ
Warning

การลบบัญชีไม่สามารถย้อนกลับได้ โปรดแจ้งให้ผู้ใช้ทราบอย่างเพียงพอก่อนลบ

URL คำขอ

URL ใช้งานจริง https://auth.qpyou.cn/v2/game/player/delete-project
URL Sandbox 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 เซสชันโทเค็นที่ได้รับผ่านส่วนหัวการตอบกลับหลังตั้งค่า require_token: true เมื่อเรียก การเข้าสู่ระบบด้วย IdP String Y

เนื้อหาคำขอ

ชื่อฟิลด์ คำอธิบาย ประเภท จำเป็น
appid App ID String Y
player_id Player ID ที่จะลบ Integer Y
did Device ID กำหนดเป็น 0 คงที่ Integer Y

ตัวอย่างคำขอ

{
    "appid": "com.com2us.hivesdk.normal.freefull.apple.global.ios.universal",
    "player_id": 100000001,
    "did": 0
}

เนื้อหาการตอบกลับ

ชื่อฟิลด์ คำอธิบาย ประเภท
result_code รหัสตอบกลับ รายละเอียด Integer
result_msg ข้อความผลลัพธ์ String
token_validation ผลการตรวจสอบ JWT (ข้อผิดพลาดการตรวจสอบ JWT) Object
token_validation.result_code รหัสผลการตรวจสอบ JWT Integer
token_validation.result_msg ข้อความผลการตรวจสอบ JWT String

ตัวอย่างการตอบกลับ

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

รหัสตอบกลับ

ค่ารหัส คำอธิบาย
0 สำเร็จ
2499 การตรวจสอบ JWT ล้มเหลว (ดู token_validation)
5000 ข้อผิดพลาดภายในเซิร์ฟเวอร์
7000 โทเค็นไม่ถูกต้อง
7001 ไม่มีโทเค็นในเฮดเดอร์
Note

เมื่อการตรวจสอบ JWT ล้มเหลว คุณสามารถดูข้อมูลข้อผิดพลาดโดยละเอียดได้ในฟิลด์ token_validation โปรดดู รหัสข้อผิดพลาดการตรวจสอบ JWT สำหรับรายละเอียด