ซิงค์กับรายการ
Item เป็นระบบที่ใช้ในการรวมและจัดการฟีเจอร์การส่งและการดึงเกมเงิน & ไอเท็มในเกม โดย Item คุณสามารถเชื่อมต่อกับระบบที่หลากหลาย เช่น ระบบคูปอง, อีเวนต์, offerwall และ CPI เพื่อส่งหรือดึงไอเท็ม และมีสำนักงานหลังสำหรับผู้ดูแลระบบที่สามารถค้นหาประวัติการส่งและดึงไอเท็มได้ด้วยตนเอง
Note
- การขอ API สำหรับการส่ง/ดึงรายการ เป็นแบบอะซิงโครนัส และตอบสนองต่อคำขอ API ตามความสำเร็จหรือความล้มเหลวของการลงทะเบียนข้อมูลคำขอ
- คุณสามารถยืนยันการตอบสนองต่อกระบวนการจริง เช่น การเรียก API ของเซิร์ฟเวอร์เกม จากหน้ารายละเอียดที่แสดงเมื่อคลิกที่ไอคอน สถานะ จากผลการค้นหาในหน้า การขอส่ง/ดึงรายการ หรือ บันทึกความสำเร็จในการส่ง/ดึงรายการ; ไปที่ คอนโซล > การเรียกเก็บเงิน > รายการ > การขอส่ง/ดึงรายการ หรือ บันทึกความสำเร็จในการส่ง/ดึงรายการ.
การเตรียมความพร้อมสำหรับการเชื่อมต่อ¶
โปรดตรวจสอบให้แน่ใจว่าคุณได้ลงทะเบียน URL ของเซิร์ฟเวอร์เกมและรายการในเมนู การจัดการรายการ เพื่อซิงค์กับมัน
ขอ API สำหรับการส่ง/ดึงรายการ¶
การตรวจสอบพื้นฐานของ API การร้องขอสำหรับการส่งมอบ/ดึงข้อมูลรายการ¶
วิธีการสื่อสาร API¶
- Request API สำหรับการส่ง/ดึงรายการมีการสื่อสารสองประเภท; HTTP และ JSON ที่ใช้ซ็อกเก็ต.
- รายการส่ง JSON ไปยังเซิร์ฟเวอร์เกมเพื่อขอส่งหรือดึงรายการ.
- เซิร์ฟเวอร์เกมส่งผลลัพธ์กลับมาพร้อมกับ JSON ไปยัง รายการ.
- ผลลัพธ์ของการตอบสนองรวมถึงรหัสกระบวนการและข้อความ.
- JSON ควรเข้ารหัสเป็น UTF8.
วิธีการสมัครเกม¶
- ก่อนเปิดให้บริการ ให้ทดสอบการเชื่อมต่อบนเซิร์ฟเวอร์ทดสอบ หลังจากเริ่มบริการแล้ว ให้ส่งไปยังเซิร์ฟเวอร์ทั่วไป
- เซิร์ฟเวอร์ทดสอบควรเชื่อมต่อขณะให้บริการ
- รายการจะถูกส่งผ่านกล่องของขวัญเป็นหลัก
- หากต้องการข้อความสำหรับคำอธิบายการส่งรายการให้ผู้ใช้เห็นบนกล่องของขวัญ ให้ดูที่ Request Body > reason เซิร์ฟเวอร์เกมควรประมวลผลข้อความคำอธิบายตามภาษา
- คำขอรายการจะถูกส่งโดยผู้ใช้ทีละรายการ สามารถส่งรายการที่ส่ง/รับมากกว่าหนึ่งรายการพร้อมกันได้ แต่ต้องแน่ใจว่าประมวลผลคำขอหนึ่งรายการภายในธุรกรรมเดียว หากรายการใดรายการหนึ่งที่ส่ง/รับล้มเหลว ให้ทำการย้อนกลับคำขอทั้งหมดและตอบสนองต่อความล้มเหลว
ปิดไฟร์วอลล์เซิร์ฟเวอร์เกม¶
- คุณควรปิดกฎไฟร์วอลล์ขาเข้าบน IP ด้านล่างจากเซิร์ฟเวอร์เกมเพื่อการสื่อสารระหว่างเซิร์ฟเวอร์。
-
- 52.79.76.25
- 3.37.22.75
- 43.202.181.123 (เซิร์ฟเวอร์ Sandbox)
การตรวจสอบสุขภาพเซิร์ฟเวอร์เกม¶
รายการส่งฟิลด์ด้านล่างไปยัง Request Body (จาก รายการไปยังเซิร์ฟเวอร์เกม) ใน Request API เพื่อส่งมอบ/ดึงรายการทุกห้านาทีเป็นเวลาสองครั้ง โดยการทำเช่นนี้ รายการสามารถติดตามสถานะของเซิร์ฟเวอร์เกมได้.
{"transactionId":"","idCategory":"","id":"","detail":[{"action":"","assetCode":"","amount":0}],"reason":""}
หลังจากที่ได้รับฟิลด์ Request Body อาจเกิดข้อผิดพลาดในการตรวจสอบที่เซิร์ฟเวอร์เกม ในกรณีนี้ ให้กรอกฟิลด์รหัสและข้อความในค่า Response ด้วยข้อมูลข้อผิดพลาด และตอบกลับไปยัง Item. Item จะรับรู้ว่าเซิร์ฟเวอร์เกมทำงานปกติหากมีฟิลด์รหัสและข้อความอยู่ หากไม่มีสองฟิลด์ในคำตอบ เซิร์ฟเวอร์เกมจะถือว่าผิดปกติ.
การตรวจสอบค่า apihash¶
เซิร์ฟเวอร์เกมของคุณสามารถตรวจสอบข้อมูลที่ เซิร์ฟเวอร์ไอเท็มส่งโดยใช้ค่า Apihash
ของ Header ก่อนที่จะตรวจสอบค่าแฮช คุณจำเป็นต้องแปลงข้อมูลในร่างคำขอเป็น JSON encode หรือยูนิโค้ด (ดูตัวอย่างโค้ดด้านล่าง) เพิ่มคำนำหน้าของข้อกำหนดคำขอไปยังค่า JSON ที่แปลงแล้วเพื่อสร้างค่าแฮชในรูปแบบ SHA1 จากนั้นคุณสามารถตรวจสอบค่า Apihash
โดยการเปรียบเทียบกับแฮช SHA1 ที่สร้างขึ้น
- Sample โค้ด
// ตัวอย่างของ JSON String ที่ถูกแปลง (เพิ่มบรรทัดและช่องว่างเพื่อความอ่านง่าย) { "transactionId": "123456789", "idCategory": "vid", "id": "1004", "detail": [ { "action": "p", "assetCode": "gem", "amount": 1, "method": "" } ], "reason": "td", "subReason": "", "userMessage": "", "templateMessage": { "ko": { "title": "Item \uc9c0\uae09 \uba54\uc138\uc9c0 QA \ud55c\uad6d", "body": "Item \uc9c0\uae09 \uba54\uc138\uc9c0 QA \ud55c\uad6d\uc5b4 \ub178\ucd9c" } }, "serverId": "kr", "additionalinfo": "", "gameIndex": 539 }
Request API สำหรับการจัดส่ง/ดึงข้อมูลรายการด้วยวิธีการ HTTP communication¶
API การขอรับ/เพิกถอนสิทธิ์จะสื่อสารกับเซิร์ฟเวอร์เกม (URL) ที่ตั้งไว้ในเมนู Hive Console > Billing > Item > Item Registration โดยใช้โปรโตคอล HTTP และวิธีการส่งข้อมูลการขอคือ POST.
Request specification (From Item to game server)¶
HTTP Header: Apihash
- สำหรับการตรวจสอบความถูกต้องของข้อมูล ให้ส่งค่าฮาชพร้อมกับค่าคีย์ Apihash。
- ใช้ sha1 สำหรับค่าฮาช (เพิ่มคำนำหน้า !@#COM2US!@# ไปยังเนื้อหาของ JSON String).
- เนื้อหาคำขอ
ชื่อฟิลด์ | คำอธิบาย | ประเภท | จำเป็น (บังคับ: M, ตัวเลือก: O) |
---|---|---|---|
transactionId | ตัวระบุเพื่อแยกแยะคำขอแต่ละรายการ (สำหรับตรวจสอบคำขอซ้ำ) ดูเพิ่มเติม | สตริง | M |
idCategory | ID * โมดูลเดียว: hiveuid * Auth v1: vid * Auth v4: playerid | สตริง | M |
id | ค่าของ ID ที่ตรงกับ idCategory | สตริง | M |
detail | อาร์เรย์ของสามรายการ (วัตถุ) ด้านล่าง | อาร์เรย์ | M |
ㄴ action | ว่าจะส่งหรือดึงข้อมูล * s หรือ p: ส่ง * w หรือ r: ดึงข้อมูล | สตริง | M |
ㄴ assetCode | รหัสรายการที่จะส่ง | สตริง | M |
ㄴ amount | จำนวนของรายการที่ส่ง | จำนวนเต็ม | M |
reason | เหตุผลสำหรับคำขอ ดูเพิ่มเติม | สตริง | M |
subReason | เหตุผลสำหรับคำขอ ดูเพิ่มเติม | สตริง | O |
serverId | เซิร์ฟเวอร์ที่ผู้ใช้เป้าหมายเข้าถึง (ID เซิร์ฟเวอร์) | สตริง | M |
additionalinfo | ข้อมูลเพิ่มเติมที่ส่งจากไคลเอนต์ไปยังเซิร์ฟเวอร์เกม (ทั้งหมดเป็นตัวพิมพ์เล็ก) | สตริง | O |
duration | ระยะเวลาของการเก็บรายการในกล่องของขวัญ (ตัวเลือก) ดูเพิ่มเติม 1-9999: ระยะเวลาของการเก็บรายการ -1: ค่าที่สามารถกำหนดได้สูงสุดบนเซิร์ฟเวอร์เกม | จำนวนเต็ม | O |
userMessage | ข้อมูลข้อความที่ส่งมอบรายการไม่สามารถเปลี่ยนแปลงได้และสามารถแลกเปลี่ยนกับเกมเก่าที่ไม่ได้ใช้ templateMessage | สตริง | O |
templateMessage | ข้อมูลข้อความที่ตั้งค่าสำหรับข้อความการส่งรายการ messagekey พร้อมรหัสภาษา, ค่าพร้อมชื่อเรื่องและเนื้อหาของข้อความ (หากมีข้อมูลอยู่ รูปแบบเริ่มต้นคือวัตถุ แต่หากว่างเปล่า ค่าจะถูกส่งกลับเป็นประเภทสตริง) | วัตถุ | O |
gameIndex | หมายเลขประจำเกมแต่ละเกมใน AppCenter | จำนวนเต็ม | M |
transactionId
- แยกแยะว่าคำขอได้ถูกประมวลผลแล้วโดยการระบุ transactionId ของแต่ละคำขอ (หลีกเลี่ยงการส่ง/ดึงซ้ำ)
- ในกรณีที่มีคำขอซ้ำ ให้ระบุในค่าการตอบกลับ (ดูที่ข้อกำหนดการตอบกลับ)
เหตุผล
Note
รายละเอียดของฟิลด์เหตุผลสามารถเพิ่มหรือเปลี่ยนแปลงได้ ดังนั้นให้ดูเหตุผลการเกิดเป็นข้อมูลอ้างอิง.
ชื่อฟิลด์คำอธิบาย<
pe | ข้อผิดพลาดการชำระเงิน |
rge | ข้อผิดพลาดเกมรางวัล |
rcd | ความไม่พอใจของผู้บริโภครางวัล |
rce | ข้อผิดพลาดคูปองรางวัล |
ro | รางวัลต่างประเทศ |
ae | การแลกเปลี่ยนสินทรัพย์ |
e | เหตุการณ์ |
ea | เหตุการณ์อัตโนมัติ |
mc | คูปองขนาดใหญ่ |
uc | คูปองเฉพาะ |
b | การเรียกเก็บเงินในเกมด้วย IAP v2 |
lb | การเรียกเก็บเงิน Lebi |
co | CPI Offerwall |
p | โปรโมชั่น ใช้เท่าเทียมกันสำหรับแบนเนอร์ข้าม, offerwall และ UA |
sr | รางวัลสตรีมมิ่ง |
tcs | ทดสอบ CS |
tgm | ทดสอบ GM |
tpm | ทดสอบ PM |
tqa | ทดสอบ QA |
td | ทดสอบนักพัฒนา |
tg | ทดสอบแขก |
tmb | ทดสอบตลาด, ธุรกิจ |
to | ทดสอบต่างประเทศ (ทดสอบนักพัฒนา) |
re | เรียกคืน (อื่นๆ) |
rr | เรียกคืนการคืนเงิน |
mr | คำขอขนาดใหญ่ |
etc | อื่นๆ |
subReason
เหตุผล | เหตุผลย่อย | คำอธิบาย |
p | รายละเอียดสำหรับคำขอส่งเสริมการขาย | |
1 | CPI บนแบนเนอร์ปกติข้าม | |
2 | CPA บนแบนเนอร์ปกติข้าม | |
3 | CPI บนแบนเนอร์ข้ามระหว่าง | |
4 | CPA บนแบนเนอร์ข้ามระหว่าง | |
5 | CPI บน Offerwall | |
6 | CPA บน Offerwall | |
7 | CPI บน Offerwall พิเศษ | |
8 | CPA บน Offerwall พิเศษ | |
9 | CPI บน UA | |
10 | CPA บน UA | |
11 | CPI บน UC |
ประเภทโปรโมชั่น
- การส่งเสริมข้าม: สามารถโฆษณาเกมอื่นด้วยรูปแบบแบนเนอร์และข้อเสนอ (เงินสดเกมฟรี) บนเกมที่ผู้ใช้กำลังเล่นอยู่ การส่งเสริมข้ามแบ่งออกเป็นแบนเนอร์ปกติและแบนเนอร์แบบเต็มหน้าจอ
- Offerwall: แสดงรายการเกมในรูปแบบแบนเนอร์ที่ยังไม่ติดตั้งในอุปกรณ์ของผู้ใช้ รางวัลจะถูกส่งหลังจากที่ผู้ใช้แตะที่แบนเนอร์และติดตั้งเกมใหม่ Offerwall มีสองประเภท; offerwall และ offerwall พิเศษ
- UA/UC: มีฟีเจอร์การเชิญผ่านโซเชียลมีเดียหรือQR โค้ด ผู้ใช้ที่เชิญและผู้ใช้ที่ถูกเชิญมีอยู่ในUA แต่ผู้ใช้ที่ถูกเชิญมีเฉพาะในUC ใช้UC สำหรับการลงทะเบียนล่วงหน้า
วิธีการให้รางวัล
- CPI: รางวัลจะถูกส่งเมื่อผู้ใช้เล่นเกมเป็นครั้งแรกหลังจากการติดตั้ง.
- CPA: รางวัลจะถูกส่งเมื่อผู้ใช้ทำสำเร็จตามความสำเร็จเฉพาะในเกม สำหรับรายละเอียดเพิ่มเติม โปรดดูที่คู่มือการดำเนินการส่งเสริมการขาย.
ระยะเวลา
- เป็นช่วงเวลาที่เก็บของในกล่องของขวัญ คุณสามารถตั้งค่าในสำนักงานด้านหลังเป็นรายบุคคลตามรายการ
- เซิร์ฟเวอร์เกมประมวลผลตามกรณีต่อไปนี้
- ไม่มีคีย์: จะใช้ค่าปริยายที่เซิร์ฟเวอร์เกมจัดเตรียมไว้ (เช่น การเก็บของสูงสุด 7 วัน)
- 1~9999: จะใช้หนึ่งในตัวเลขเป็นจำนวนวันที่เก็บ (เช่น ค่า 14 หมายถึง 14 วันสำหรับการเก็บของ)
- -1: จะใช้ค่าที่สูงสุดที่สามารถกำหนดได้ที่เซิร์ฟเวอร์เกม (เช่น การเก็บของถาวร)
ข้อกำหนดการตอบสนอง (จากเซิร์ฟเวอร์เกมไปยัง Item)¶
Response (จากเซิร์ฟเวอร์เกมไปยัง รายการ)
ชื่อฟิลด์ | คำอธิบาย | ประเภท | จำเป็น (บังคับ: M, ตัวเลือก: O) |
รหัส | รหัสผลลัพธ์ของกระบวนการ ดูเพิ่มเติม | จำนวนเต็ม | M |
ข้อความ | ข้อความผลลัพธ์ของกระบวนการ | สตริง | M |
- รหัสข้อผิดพลาด
รหัส คำอธิบาย 2xxxx ชัดเจน. การประมวลผลสำเร็จ ㄴ 20000 ชัดเจน. การประมวลผลสำเร็จ ㄴ 20001 ชัดเจน กรณีสำเร็จมีอยู่แล้ว (ในกรณีที่มีการร้องขอซ้ำ) การทำธุรกรรมที่ประมวลผลตามปกติมีอยู่แล้ว 4xxxx ข้อผิดพลาดของพารามิเตอร์การร้องขอ ㄴ 40001 ข้อผิดพลาด JSON ของการร้องขอ ㄴ 40002 ข้อผิดพลาดแฮช ㄴ 40003 คีย์พารามิเตอร์ที่จำเป็นถูกละเว้น ㄴ 40004 ข้อผิดพลาดประเภทคีย์พารามิเตอร์ที่จำเป็น ㄴ 40005 พารามิเตอร์ที่จำเป็นเป็นค่า null ㄴ 40006 พารามิเตอร์ที่จำเป็นผิดพลาด (เช่น หมายเลขลบ) 5xxxx ข้อผิดพลาดในการประมวลผลของเซิร์ฟเวอร์ ㄴ 50001 ผู้ใช้ไม่ถูกต้อง ㄴ 50004 ข้อผิดพลาดในการลงทะเบียน DB ㄴ 50005 ข้อผิดพลาดของพารามิเตอร์ (เช่น รหัสสินค้าไม่ถูกต้อง)
- Call Sample<
curl -L -v \ -d '{"transactionId":"27905","idCategory":"vid","id":"828292","detail":[{"action":"p","assetCode":"gold","amount":500,"method":""},{"action":"p","assetCode":"gem","amount":200,"method":""}],"reason":"td","subReason":"","userMessage":"","templateMessage":{"ko":{"title":"\ud55c\uae00 \uba54\uc138\uc9c0","body":"\ud55c\uae00 \ub0b4\uc6a9"},"en":{"title":"English Message","body":"English Contents"}},"serverId":"kr","additionalinfo":"","gameIndex":539}' \ -H "Content-Type: text/html" \ -H "Apihash: e9d7307948ff0134fb59c5f96e68f5ae21e3e47f" \ https://sandbox-misample.com2us.net/hive/item
- Request Sample<
- Response Sample<
Request ample(PHP)<
// data request
$data = array(
'transactionId' => '12321',
'idCategory' => 'vid',
'id' => '828292',
'detail' => array(
array(
'action' => 's',
'assetCode' => 'gold',
'amount' => 500,
),
array(
'action' => 's',
'assetCode' => 'gem',
'amount' => 200,
),
),
'reason' => 'p',
'subReason' => '3',
'userMessage' => '',
'templateMessage' => array(
'ko' => array(
'title' => '한글 메세지',
'body' => '한글 내용'
),
'en' => array(
'title' => 'English Message',
'body' => 'English Contents'
),
),
'serverId' => 'GLOBAL',
'additionalinfo' => '{"character":1}',
'gameIndex' => 539
);
$jsonData = json_encode($data); // convert to JSON
/********************************************************************
Conversion result (add a line and spaces for readability) :
{
"transactionId": "12321",
"idCategory": "vid",
"id": "828292",
"detail": [
{
"action": "s",
"assetCode": "gold",
"amount": 500
},
{
"action": "s",
"assetCode": "gem",
"amount": 200
}
],
"reason": "p",
"subReason": "3",
"userMessage": "",
"templateMessage": {
"ko": {
"title": "한글 메세지",
"body": "한글 내용"
},
"en": {
"title": "English Message",
"body": "English Contents"
}
},
"serverId": "GLOBAL",
"additionalinfo": "{\"character\":1}",
"gameIndex": 539
}
********************************************************************/
// set header as application/json & set hash
$hash = sha1('!@#COM2US!@#' . $jsonData);
$header = array(
'Content-type: application/json',
'Apihash: ' . $hash
);
$url = 'http://game.com2us.com/gms.php'; // game server url
$curl = curl_init();
curl_setopt($curl, CURLOPT_HTTPHEADER, $header);
curl_setopt($curl, CURLOPT_URL, $url);
curl_setopt($curl, CURLOPT_POST, true);
curl_setopt($curl, CURLOPT_POSTFIELDS, $jsonData);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
$result = curl_exec( $curl );
curl_close( $curl );
// process the result data
$response = json_decode($result);
Response Sample(PHP)<
// php header declaration
header('Content-type: application/json');
// json Data
$rawData = file_get_contents('php://input');
//confirm Hash value
$hash = sha1('!@#COM2US!@#' . $rawData);
$requestHash = $_SERVER['Apihash'];
if ($requestHash != $hash) {
/*****************************************************************
Process if the hash value differs (optional to use hash)
*****************************************************************/
}
// Decode requested JSON data
$requestData = json_decode($rawData, TRUE);
foreach ($requestData['detail'] as $item) {
/*****************************************************************
Process the asset as requested
*****************************************************************/
}
$returnData = array(
'code' => 50001,
'message' => 'user not exists',
);
//To avoid adding UTF-8BOM
ob_clean()
//Convert to JSON and send the response
echo json_encode($returnData);
/*****************************************************************
Conversion result (insert a line) :
{
"code" : 50001,
"message" : "user not exists"
}
*****************************************************************/
ขอ API สำหรับการส่ง/ดึงรายการโดยใช้ซ็อกเก็ต¶
TCP/IP ของ Request API สำหรับการส่ง/ดึงรายการโดยใช้ซ็อกเก็ตเป็นการสื่อสารข้อมูลแพ็กเก็ต ข้อมูล API ใช้โปรโตคอล และพอร์ตของมันคือ 20080. ข้อมูลพื้นฐานอยู่ในรูปแบบ JSON ซึ่งเป็นรูปแบบเดียวกับการสื่อสาร HTTP และรูปแบบการจัดเรียงไบต์คือ Network byte order (Big-endian).
ข้อกำหนดแพ็กเก็ตคำขอ (จาก Item ไปยังเซิร์ฟเวอร์เกม)¶
ขนาดแพ็กเกจ | 4ไบต์ | 4ไบต์ | ตัวแปร | 4ไบต์ | ตัวแปร |
คำอธิบาย | ความยาวทั้งหมดของแพ็กเกจ | ความยาวของส่วนหัว | เนื้อหาของส่วนหัว | ความยาวของเนื้อหา | เนื้อหาของเนื้อหา |
- ใน 4 ไบต์แรก ให้ระบุความยาวทั้งหมดของแพ็กเกจรวมถึง 4 ไบต์ เช่น หากส่วนหัวมีความยาว 46 ไบต์และเนื้อหามีความยาว 100 ไบต์ ความยาวของแพ็กเกจคือ 4+4+46+4+100=158 ไบต์。
- 4 ไบต์ถัดไประบุความยาวของ Header ที่ตามมา。
- Header เป็นรูปแบบ JSON String เช่นเดียวกับค่าแฮชของการสื่อสาร HTTP เช่น,
{"Apihash":"912ec803b2ce49e4a541068d495ab570"}
- 4 ไบต์ถัดไประบุความยาวของ Body ที่ตามมา。
- Body เป็นรูปแบบ JSON String เช่นเดียวกับค่าที่ร้องขอของการสื่อสาร HTTP。
ข้อกำหนดแพ็คเกจการตอบกลับ (จากเซิร์ฟเวอร์เกมไปยัง Item)¶
ขนาดแพ็กเก็ต | 4ไบต์ | ตัวแปร |
เนื้อหา | ความยาวทั้งหมดของแพ็กเก็ต | เนื้อหา |
- ใน 4 ไบต์แรก ให้ระบุความยาวทั้งหมดของแพ็กเกจรวมถึง 4 ไบต์
- Body เป็นรูปแบบ JSON String ซึ่งเหมือนกับค่าการตอบสนองของการสื่อสาร HTTP