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

การแจ้งเตือนเกม

คู่มือนี้อธิบายวิธีการใช้งาน API การสอบถามประกาศในเกม

ก่อนเรียก API คุณต้องลงทะเบียนประกาศที่จะแสดงในเกมจาก Hive Console ก่อน ลงทะเบียนประกาศ

ภาพรวม

API การสอบถามประกาศในเกมจะถูกเรียกโดยตรงจากเกมผ่านการสื่อสารแบบเซิร์ฟเวอร์ต่อเซิร์ฟเวอร์ และรองรับอินเทอร์เฟซสองประเภทขึ้นอยู่กับวิธีการสอบถาม

ส่วนหัวคำขอ Authorization ต้องมีโทเคนการยืนยันตัวตน (Hive authentication key) ผลตอบกลับประกอบด้วย ข้อมูลพื้นฐานของประกาศ, รายละเอียดตามภาษา, รายการ ID เซิร์ฟเวอร์เกม และ รายการรหัสประเทศ

ประกาศจะถูกส่งกลับในผลตอบกลับเฉพาะเมื่อตรงตามเงื่อนไขทั้งหมดต่อไปนี้:

  • status = 1: สถานะเปิดใช้งาน
  • start_time <= เวลาปัจจุบัน: เวลาปัจจุบันอยู่หลังเวลาเริ่มแสดงผล
  • end_time >= เวลาปัจจุบัน: เวลาปัจจุบันอยู่ก่อนเวลาสิ้นสุดการแสดงผล
Note

เวลาทั้งหมดอ้างอิงตาม KST (UTC+9)

ข้อกำหนดผลตอบกลับร่วม

อธิบายตัวอย่างผลตอบกลับและรหัสผลตอบกลับที่ใช้กับการเรียก API การสอบถามประกาศในเกมทั้งหมด

ตัวอย่างผลตอบกลับเมื่อสำเร็จ

{
  "result_code": 0,
  "result_msg": "Success",
  "data": { ... }
}

ตัวอย่างผลตอบกลับเมื่อเกิดข้อผิดพลาด

{
  "result_code": 1100,
  "result_msg": "Unknown error"
}

รหัสผลตอบกลับ

HTTP status code Code Message Description
200 0 Success ประมวลผลสำเร็จ
500 1100 Unknown error ข้อผิดพลาดที่ไม่ทราบสาเหตุ
500 1101 Internal server error ข้อผิดพลาดภายในเซิร์ฟเวอร์
400 1201 Detail message
(e.g., Missing required parameter: game_index)		 ข้อผิดพลาดรูปแบบคำขอ
400 1202 Detail message
(e.g., `game_index` must be a positive integer)		 ข้อผิดพลาดค่าพารามิเตอร์
401 1203 Unauthorized ข้อผิดพลาดการอนุญาต
405 1204 Method not allowed ข้อผิดพลาดเมธอดคำขอ HTTP


ดูประกาศทั้งหมด

ส่งกลับรายการประกาศทั้งหมดสำหรับเกมที่ระบุ (game_index)

ข้อมูลคำขอ

รายการ รายละเอียด
Production URL https://social-api.qpyou.cn/games/{game_index}/notices
Sandbox URL https://sandbox-social-api.qpyou.cn/games/{game_index}/notices
HTTP Method GET
Response Format JSON

ข้อมูลคำขอ

ส่วนหัวคำขอ

ฟิลด์ ประเภท จำเป็น คำอธิบาย หมายเหตุ
Authorization string Y Bearer token
(Hive authentication key)		 AppCenter > Project Management > Game Details > Basic Information > Hive authentication key

ตัวอย่างส่วนหัวคำขอ

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWUsImlhdCI6MTUxNjIzOTAyMn0.KMUFsIDTnFmyG3nMiGM6H9FNFUROf3wh7SmqJp-QV30

พารามิเตอร์เส้นทาง

ฟิลด์ ประเภท จำเป็น คำอธิบาย
game_index int Y ดัชนีเกม (จำนวนเต็มบวก)

เนื้อหาคำขอ

ไม่มี (คำขอ GET)

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

curl -X GET "https://sandbox-social-api.qpyou.cn/games/313/notices" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWUsImlhdCI6MTUxNjIzOTAyMn0.KMUFsIDTnFmyG3nMiGM6H9FNFUROf3wh7SmqJp-QV30"

ข้อมูลผลตอบกลับ

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

ฟิลด์ ประเภท คำอธิบาย
result_code int รหัสผลลัพธ์ของผลตอบกลับ
result_msg string ข้อความผลลัพธ์
data object ข้อมูลผลตอบกลับ
ㄴ list array รายการประกาศ (อาร์เรย์ของออบเจกต์ ข้อมูลพื้นฐานของประกาศ; ส่งกลับ [] หากไม่มีผลลัพธ์)

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

{
  "result_code": 0,
  "result_msg": "Success",
  "data": {
    "list": [
      {
        "notice_id": 123,
        "status": 1,
        "type": "N",
        "view_count": 500,
        "registrant": "admin",
        "top_placed": 1,
        "start_time": "2026-03-01 00:00:00",
        "end_time": "2026-03-31 23:59:59",
        "company_index": 1,
        "game_index": 313,
        "country_expose_type": "W",
        "details": {
          "ko": {
            "game_name": "테스트게임",
            "title": "공지사항 제목",
            "content": "공지사항 내용",
            "crop_image": "https://example.com/img/123_kor.png"
          },
          "en": {
            "game_name": "TestGame",
            "title": "Notice Title",
            "content": "Notice Content",
            "crop_image": "https://example.com/img/123_eng.png"
          }
        },
        "game_servers": ["server1", "server2"],
        "country_codes": ["KR", "US"]
      }
    ]
  }
}

ดูประกาศแบบแบ่งหน้า

ส่งกลับรายการประกาศสำหรับเกมที่ระบุ (game_index) แบบแบ่งหน้า

ดูประกาศทั้งหมด จะเปลี่ยนเป็นโหมดแบ่งหน้าเมื่อมีพารามิเตอร์คิวรี page หรือ per_page อยู่ในคำขอ

ข้อมูลคำขอ

รายการ รายละเอียด
Production URL https://social-api.qpyou.cn/games/{game_index}/notices?page={page}&per_page={per_page}
Sandbox URL https://sandbox-social-api.qpyou.cn/games/{game_index}/notices?page={page}&per_page={per_page}
HTTP Method GET
Response Format JSON

ข้อมูลคำขอ

ส่วนหัวคำขอ

ฟิลด์ ประเภท จำเป็น คำอธิบาย หมายเหตุ
Authorization string Y Bearer token
(Hive authentication key)		 AppCenter > Project Management > Game Details > Basic Information > Hive authentication key

ตัวอย่างส่วนหัวคำขอ

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWUsImlhdCI6MTUxNjIzOTAyMn0.KMUFsIDTnFmyG3nMiGM6H9FNFUROf3wh7SmqJp-QV30

พารามิเตอร์เส้นทาง

ฟิลด์ ประเภท จำเป็น คำอธิบาย
game_index int Y ดัชนีเกม (จำนวนเต็มบวก)

พารามิเตอร์คิวรี

Note

หาก page หรือ per_page ไม่ใช่จำนวนเต็มบวก ระบบจะใช้ค่าเริ่มต้นแทน

พารามิเตอร์ ประเภท จำเป็น ค่าเริ่มต้น คำอธิบาย
page int N 1 หมายเลขหน้า (เริ่มจาก 1)
per_page int N 20 จำนวนรายการต่อหน้า

เนื้อหาคำขอ

ไม่มี (คำขอ GET)

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

curl -X GET "https://sandbox-social-api.qpyou.cn/games/313/notices?page=1&per_page=20" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWUsImlhdCI6MTUxNjIzOTAyMn0.KMUFsIDTnFmyG3nMiGM6H9FNFUROf3wh7SmqJp-QV30"

ข้อมูลผลตอบกลับ

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

ฟิลด์ ประเภท คำอธิบาย
result_code int รหัสผลลัพธ์ของผลตอบกลับ
result_msg string ข้อความผลลัพธ์
data object ข้อมูลผลตอบกลับ
ㄴ pagination object ข้อมูล Pagination
  ㄴ page int หมายเลขหน้าปัจจุบัน
  ㄴ per_page int จำนวนรายการต่อหน้า
  ㄴ total_count int จำนวนข้อมูลทั้งหมด
  ㄴ total_pages int จำนวนหน้าทั้งหมด (ceil(total_count / per_page); 0 หาก total_count = 0)
ㄴ list array รายการประกาศ (อาร์เรย์ของออบเจกต์ ข้อมูลพื้นฐานของประกาศ; ส่งกลับ [] หากไม่มีผลลัพธ์)

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

{
  "result_code": 0,
  "result_msg": "Success",
  "data": {
    "pagination": {
      "page": 1,
      "per_page": 20,
      "total_count": 50,
      "total_pages": 3
    },
    "list": [
      {
        "notice_id": 123,
        "status": 1,
        "type": "N",
        "view_count": 500,
        "registrant": "admin",
        "top_placed": 1,
        "start_time": "2026-03-01 00:00:00",
        "end_time": "2026-03-31 23:59:59",
        "company_index": 1,
        "game_index": 313,
        "country_expose_type": "W",
        "details": {
          "ko": {
            "game_name": "테스트게임",
            "title": "공지사항 제목",
            "content": "공지사항 내용",
            "crop_image": "https://example.com/img/123_kor.png"
          },
          "en": {
            "game_name": "TestGame",
            "title": "Notice Title",
            "content": "Notice Content",
            "crop_image": "https://example.com/img/123_eng.png"
          }
        },
        "game_servers": ["server1", "server2"],
        "country_codes": ["KR", "US"]
      }
    ]
  }
}

รายละเอียดข้อมูลผลตอบกลับ

ข้อมูลพื้นฐานของประกาศ

ฟิลด์ ประเภท คำอธิบาย
notice_id int ID ประจำตัวของประกาศ
status int สถานะ (1: เปิดใช้งาน; ส่งกลับเฉพาะประกาศที่เปิดใช้งาน)
type string ประเภทประกาศ (ดู รหัส type)
view_count int จำนวนการเข้าชม
registrant string ผู้ลงทะเบียน
top_placed int|null ปักหมุดไว้บนสุด (1 หรือมากกว่า: ปักหมุด, null: ไม่ปักหมุด)
start_time string เวลาเริ่มแสดง (yyyy-MM-dd HH:mm:ss, KST)
end_time string เวลาสิ้นสุดการแสดง (yyyy-MM-dd HH:mm:ss, KST)
company_index int ดัชนีบริษัท
game_index int ดัชนีเกม
country_expose_type string|null ประเภทการแสดงตามประเทศ (ดู รหัส country_expose_type; ค่าเริ่มต้น: null)
details object รายละเอียดตามภาษา (ดู details)
game_servers array รายการ ID เซิร์ฟเวอร์เกม (ดู game_servers)
country_codes array รายการรหัสประเทศ (ดู country_codes)

รหัส type

รหัส คำอธิบาย
I ข้อมูล
C การบำรุงรักษา
U อัปเดต
N ประกาศ
A ประกาศทั่วไป
E อีเวนต์
D ข้อผิดพลาด

รหัส country_expose_type

รหัส คำอธิบาย
null ไม่มีข้อจำกัด (แสดงในทุกประเทศ)
W รายการที่อนุญาต (แสดงเฉพาะประเทศที่รวมอยู่ใน country_codes)
B รายการที่ถูกบล็อก (บล็อกสำหรับประเทศที่รวมอยู่ใน country_codes)

details

details คือออบเจกต์ที่มีรหัสภาษาเป็นคีย์ รวมเฉพาะภาษาที่ลงทะเบียนสำหรับประกาศเท่านั้น; ส่งกลับออบเจกต์ว่าง ({}) หากไม่มีข้อมูล

ฟิลด์ ประเภท คำอธิบาย
game_name string ชื่อเกม
title string หัวข้อประกาศ
content string เนื้อหาประกาศ
crop_image string URL รูปภาพที่ตัด

รหัสภาษาที่รองรับ

รหัส ภาษา
ko ภาษาเกาหลี
en ภาษาอังกฤษ
ja ภาษาญี่ปุ่น
zh-hans ภาษาจีนตัวย่อ
zh-hant ภาษาจีนตัวเต็ม
de ภาษาเยอรมัน
fr ภาษาฝรั่งเศส
ru ภาษารัสเซีย
es ภาษาสเปน
pt ภาษาโปรตุเกส
id ภาษาอินโดนีเซีย
th ภาษาไทย
vi ภาษาเวียดนาม
it ภาษาอิตาลี
tr ภาษาตุรกี
ar ภาษาอาหรับ

game_servers

  • รายการ ID เซิร์ฟเวอร์เกม ส่งกลับอาร์เรย์ว่าง ([]) หากไม่มีข้อมูล
  • ตัวอย่าง: ["server1", "server2", "server3"]

country_codes

  • รายการรหัสประเทศ ส่งกลับอาร์เรย์ว่าง ([]) หากไม่มีข้อมูล
  • ตัวอย่าง: ["KR", "US", "JP"]
  • อ้างอิง: มาตรฐาน ISO 3166