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

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

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

การเตรียมพร้อม

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

วิธีการทำงาน

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

Note

API การสอบถามประกาศของแอปทำงานด้วยการยืนยันตัวตนแบบ JWT

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

สามารถดูประกาศได้เฉพาะเมื่อค่าตอบกลับตรงตามเงื่อนไขด้านล่าง

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

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

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

อธิบายตัวอย่างข้อมูลผลตอบกลับเมื่อสำเร็จและล้มเหลว รวมถึงรหัสสถานะที่ส่งกลับเมื่อเรียก API การสอบถามประกาศของแอป

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

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

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

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

ตัวอย่างการตรวจสอบ JWT ล้มเหลว

{
  "result_code": 1203,
  "result_msg": "Unauthorized",
  "token_validation": {
    "result_code": 2408,
    "result_msg": "JWT token expired"
  }
}

รหัสสถานะ

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

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


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

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

ข้อมูลคำขอ

รายการ ข้อมูล
Production URL https://social-api.qpyou.cn/v2/games/{game_index}/notices
Sandbox URL https://sandbox-social-api.qpyou.cn/v2/games/{game_index}/notices
HTTP Method GET
Response Format JSON

ข้อมูลคำขอ

อธิบายข้อมูลที่ส่งเมื่อเรียก 'ดูประกาศทั้งหมด'

ส่วนหัวคำขอ

ฟิลด์ ประเภท จำเป็น คำอธิบาย หมายเหตุ
X-Access-Token string Y JWT Access Token สำหรับวิธีการออก โปรดดูที่ การออกโทเค็น OAuth

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

X-Access-Token: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6InByb2plY3RfYWJjMTIzIn0...

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

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

เนื้อหาคำขอ

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

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

ตัวอย่างการเรียก 'ดูประกาศทั้งหมด' มีดังนี้

curl -X GET "https://sandbox-social-api.qpyou.cn/v2/games/539/notices" \
  -H "X-Access-Token: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6InByb2plY3RfYWJjMTIzIn0..."

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

อธิบายข้อมูลที่ได้รับเมื่อเรียก 'ดูประกาศทั้งหมด'

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

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

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

ตัวอย่างการตอบสนองเมื่อเรียก 'ดูประกาศทั้งหมด' มีดังนี้

{
  "result_code": 0,
  "result_msg": "Success",
  "token_validation": { 
    "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": 4,
        "game_index": 539,
        "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/v2/games/{game_index}/notices?page={page}&per_page={per_page}
Sandbox URL https://sandbox-social-api.qpyou.cn/v2/games/{game_index}/notices?page={page}&per_page={per_page}
HTTP Method GET
Response Format JSON

ข้อมูลคำขอ

อธิบายข้อมูลที่ส่งเมื่อเรียก 'ดูประกาศแบบแบ่งหน้า'

ส่วนหัวคำขอ

ฟิลด์ ประเภท จำเป็น คำอธิบาย หมายเหตุ
X-Access-Token string Y JWT Access Token สำหรับวิธีการออก โปรดดูที่ การออกโทเค็น OAuth

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

X-Access-Token: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6InByb2plY3RfYWJjMTIzIn0...

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

ฟิลด์ ประเภท จำเป็น คำอธิบาย
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/v2/games/539/notices?page=1&per_page=20" \
  -H "X-Access-Token: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6InByb2plY3RfYWJjMTIzIn0..."

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

อธิบายข้อมูลที่ได้รับเมื่อเรียก 'ดูประกาศแบบแบ่งหน้า'

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

ฟิลด์ ประเภท คำอธิบาย
result_code int รหัสผลลัพธ์ของผลตอบกลับ
result_msg string ข้อความผลลัพธ์
token_validation object ผลการตรวจสอบ JWT
ㄴ result_code int รหัสผลการตรวจสอบ JWT (0 = สำเร็จ โปรดดู รหัสข้อผิดพลาดการตรวจสอบ JWT สำหรับรายละเอียด)
ㄴ result_msg string ข้อความผลการตรวจสอบ JWT
data object ข้อมูลผลตอบกลับ (ไม่รวมหากการตรวจสอบ JWT ล้มเหลว)
ㄴ 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",
  "token_validation": {
    "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": 4,
        "game_index": 539,
        "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"]
      }
    ]
  }
}

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

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

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

ฟิลด์ ประเภท คำอธิบาย
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