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

เอกสารนี้อธิบายวิธีนำเว็บล็อกอินไปใช้งานด้วย 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 นี้ต้องตรวจสอบโทเค็น จึงต้องดำเนินการต่อไปนี้ล่วงหน้า

เมื่อเรียก API การเข้าสู่ระบบด้วย IdP ให้ตั้งค่า require_token เป็น true
จัดเก็บค่า Authorization ที่ได้รับจากส่วนหัวการตอบกลับของ API การเข้าสู่ระบบด้วย IdP
เมื่อเรียก 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 สำหรับรายละเอียด