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

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

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

Note

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

ภาพรวม

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

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

รายการ 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 นั้นลงทะเบียนไว้แล้ว เมื่อเข้าสู่ระบบสำเร็จ คุณสามารถตรวจสอบ PlayerID ได้จาก data.player_id

Warning

API เว็บล็อกอินแบบกำหนดเองไม่รองรับการสร้างบัญชี guest (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 ID ผู้ใช้ IdP

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 ใหม่กับบัญชีผู้เล่นเดิม ต้องเรียกใช้หลังจากเข้าสู่ระบบผ่าน API การเข้าสู่ระบบด้วย IdP เท่านั้น

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 ID ผู้ใช้ IdP

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 ที่เชื่อมโยงกับบัญชีผู้เล่น ต้องเรียกใช้หลังจากเข้าสู่ระบบผ่าน API การเข้าสู่ระบบด้วย IdP เท่านั้น

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 โทเค็นไม่ถูกต้อง

ลบบัญชี

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

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

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

Request Body

ชื่อฟิลด์ ประเภท คำอธิบาย จำเป็น
appid String App ID ของเกม (AppID) Y
player_id Integer PlayerID ที่จะลบ Y
did Integer Device 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 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 ที่บริษัทเกมให้บริการเอง