ซิงค์กับรายการ

รายการ Hive เป็นระบบที่จัดเตรียมไว้เพื่อจัดการฟังก์ชันการชำระเงิน/การเรียกคืนของสกุลเงินหรือรายการในเกม การรวม Hive ช่วยให้สามารถให้หรือเรียกรายการได้ร่วมกับระบบคูปอง, กิจกรรม, แผนผังข้อเสนอ, CPI เป็นต้น ในสำนักงานหลังบ้านของผู้ดูแลระบบ สามารถให้/เรียกรายการด้วยตนเองหรือค้นหาประวัติได้

ข้อกำหนดการเตรียมการรวม¶

ในการรวมกับ Hive รายการ คุณต้องลงทะเบียน URL เซิร์ฟเวอร์เกมและรายการในเมนู การจัดการรายการ Hive ก่อน

API การขอชำระเงิน/การกู้คืน¶

ตรวจสอบพื้นฐานของ API การขอชำระเงิน/คืนเงิน¶

วิธีการสื่อสาร API¶

• API การขอรับเงินช่วยเหลือ/การกู้คืนให้บริการการสื่อสารสองประเภท: การสื่อสารผ่าน HTTP และการสื่อสารแบบ JSON String ผ่านซ็อกเก็ต.
• มันขอรับเงินช่วยเหลือหรือการกู้คืนในรูปแบบ JSON String จากเซิร์ฟเวอร์เกมไปยัง Hive item.
• เซิร์ฟเวอร์เกมจะส่งผลลัพธ์กลับในรูปแบบ JSON String ไปยัง Hive item.
• ผลลัพธ์การตอบสนองรวมถึงรหัสการประมวลผลและข้อความ.
• JSON String ทั้งหมดต้องเข้ารหัสในรูปแบบ UTF8.

วิธีการสมัครเกม¶

• ก่อนที่บริการจะเปิดใช้งาน เซิร์ฟเวอร์ทดสอบจะถูกใช้เพื่อส่งผลการทดสอบการรวม และหลังจากที่บริการเปิดใช้งาน เซิร์ฟเวอร์การผลิตจะถูกใช้
• แม้ว่าเกมจะเปิดให้บริการแล้ว ก็ต้องรวมเข้ากับเซิร์ฟเวอร์ทดสอบ
• รายการทั้งหมดจะถูกจัดเตรียมผ่านกล่องจดหมาย
• หากต้องการข้อความแสดงผลสำหรับผู้ใช้ในกล่องจดหมาย โปรดดูที่ Request Specification > Request Reason เซิร์ฟเวอร์เกมต้องจัดการข้อความแสดงผลตามแต่ละภาษา
• การขอรายการจะถูกส่งทีละรายการต่อผู้ใช้ การขอหลายรายการเพื่อมอบ/ดึงรายการสามารถส่งได้พร้อมกัน แต่การขอเดียวต้องได้รับการประมวลผลภายในธุรกรรมเดียว หากการมอบ/ดึงรายการหนึ่งรายการล้มเหลว ให้ดำเนินการตอบกลับด้วยความล้มเหลหลังจากการย้อนกลับทั้งหมด

การปล่อยไฟร์วอลล์เซิร์ฟเวอร์เกม¶

ในการสื่อสารกับเซิร์ฟเวอร์ คุณต้องปิดกฎไฟร์วอลล์ขาเข้าสำหรับ IP ด้านล่างบนเซิร์ฟเวอร์เกม

• 52.79.76.25
• 3.37.22.75
• 43.133.238.219 (เซิร์ฟเวอร์แซนด์บ็อกซ์)

การตรวจสอบสุขภาพเซิร์ฟเวอร์เกม¶

Hive รายการส่งรายละเอียดต่อไปนี้ไปยัง API ขออนุญาต/เพิกถอนเพื่อตรวจสอบสถานะของเซิร์ฟเวอร์เกม เซิร์ฟเวอร์รายการ Hive จะส่งสิ่งนี้ไปยังเซิร์ฟเวอร์เกมสองครั้งในช่วงเวลา 5 นาทีใน Request Body.

{"transactionId":"","idCategory":"","id":"","detail":[{"action":"","assetCode":"","amount":0}],"reason":""}

เซิร์ฟเวอร์เกมที่รับเนื้อหาข้างต้นอาจพบข้อผิดพลาดในการตรวจสอบความถูกต้อง และในกรณีนี้ ควรตอบสนองด้วยข้อมูลข้อผิดพลาดในฟิลด์รหัสและข้อความของค่าการตอบสนอง Hive รายการไม่ได้กำหนดค่ารหัสเพียงอย่างเดียว หากฟิลด์รหัสและข้อความมีอยู่ เซิร์ฟเวอร์เกมถือว่าปกติ; หากไม่มี เซิร์ฟเวอร์เกมถือว่าอยู่ในสถานะผิดปกติ

การตรวจสอบค่า Apihash¶

เซิร์ฟเวอร์เกมสามารถตรวจสอบข้อมูลที่ได้รับจากเซิร์ฟเวอร์ไอเท็ม Hive ผ่านค่า Apihash ใน Header ก่อนที่จะตรวจสอบค่าแฮช จำเป็นต้องแปลงข้อมูล Request Body ที่ได้รับจากเซิร์ฟเวอร์ไอเท็ม Hive เป็น JSON encode หรือ unicode (ดูที่ตัวอย่างโค้ด)
โดยการผสมผสานพรีฟิกซ์ของข้อกำหนดการร้องขอและค่าที่แปลงเป็น JSON String (พรีฟิกซ์ + JSON String) จะสร้างค่าแฮชในรูปแบบ SHA1 และค่านี้จะถูกเปรียบเทียบกับค่า Apihash เพื่อการตรวจสอบ

• ตัวอย่างโค้ด

    // Example of a transformed JSON String (add a line and spaces for readability)
 {
    "transactionId": "123456789",
    "idCategory": "player_id",
    "id": "1004",
    "detail": [
        {
            "action": "p",
            "assetCode": "gem",
            "amount": 1
        }
    ],
    "reason": "td",
    "subReason": "",
    "userMessage": "",
    "templateMessage": {
        "ko": {
            "title": "HIVE Item uc9c0uae09 uba54uc138uc9c0 QA ud55cuad6d",
            "body": "HIVE Item uc9c0uae09 uba54uc138uc9c0 QA ud55cuad6duc5b4 ub178ucd9c"
        }
    },
    "serverId": "kr",
    "additionalinfo": "",
    "gameIndex": 539
}

API การขอชำระเงิน/คืนเงิน สำหรับวิธีการสื่อสาร HTTP¶

API การชำระเงิน/การเรียกคืนจะสื่อสารกับเซิร์ฟเวอร์เกม (URL) ที่ตั้งไว้ใน Hive Console > Billing > Items > Item Registration เมนูผ่านโปรโตคอล HTTP และวิธีการส่งข้อมูลคำขอคือ POST.

ข้อกำหนดการร้องขอ (hive item -> game server)¶

HTTP Header : Apihash

• เพื่อยืนยันข้อมูล ให้ส่งค่าแฮชพร้อมกับคีย์ Apihash.
• ใช้ SHA1 สำหรับค่าแฮช (เพิ่มคำนำหน้า !@#COM2US!@# ลงในสตริง JSON ของร่าง)

เนื้อหาคำขอ (Hive item -> เซิร์ฟเวอร์เกม)

transactionid¶

• มันระบุได้ว่าคำขอได้ถูกประมวลผลแล้วโดย transactionId หรือไม่ (ป้องกันการชำระเงิน/การเก็บเงินซ้ำ)
• ในกรณีที่มีคำขอซ้ำ ค่าการตอบกลับจะระบุรายละเอียดที่เกี่ยวข้อง (ดูที่ข้อกำหนดการตอบกลับ)

เหตุผล¶

สาเหตุย่อย¶

การจำแนกฟีเจอร์โปรโมชั่น

• การโปรโมตข้าม: ผู้ใช้สามารถโฆษณาเกมอื่นในเกมปัจจุบันที่พวกเขากำลังเล่นในรูปแบบของแบนเนอร์และกำแพงข้อเสนอ (สถานีชาร์จฟรี) แบ่งออกเป็นแบนเนอร์ปกติและแบนเนอร์แบบเต็มหน้าจอ
• กำแพงข้อเสนอ: กำแพงข้อเสนอจะแสดงรายการเกมที่ยังไม่ได้ติดตั้งบนอุปกรณ์ของผู้ใช้ในรูปแบบของแบนเนอร์ ผู้ใช้จะได้รับรางวัลเมื่อพวกเขาสัมผัสแบนเนอร์และติดตั้งเกมจากตลาดที่เชื่อมต่อ แบ่งออกเป็นกำแพงข้อเสนอปกติและกำแพงข้อเสนอพิเศษ
• UA/UC: ฟีเจอร์เชิญเกมที่ใช้โซเชียลมีเดียและรหัส QR UA เกี่ยวข้องกับผู้ใช้ที่เชิญและผู้ใช้ที่รับ ในขณะที่ UC รวมเฉพาะผู้ใช้ที่รับ UC สามารถใช้ในระหว่างการลงทะเบียนล่วงหน้า

วิธีการให้รางวัล

• CPI: รางวัลจะถูกมอบให้หลังจากที่เปิดเกมหลังจากการติดตั้ง
• CPA: รางวัลจะถูกมอบให้สำหรับการบรรลุเป้าหมายที่กำหนดระหว่างเกม สำหรับรายละเอียดเพิ่มเติม โปรดตรวจสอบที่ คู่มือการดำเนินการส่งเสริมการขาย

ระยะเวลา¶

• ระยะเวลาที่รายการที่ร้องขอถูกเก็บไว้ในกล่องจดหมายหลังจากออกสามารถตั้งค่าได้เป็นรายบุคคลสำหรับแต่ละรายการในสำนักงานหลัง
• เซิร์ฟเวอร์เกมจัดการในสามกรณีตามสถานการณ์
  • หากกุญแจไม่มีอยู่: จะใช้ค่าดีฟอลต์ที่ตั้งโดยเซิร์ฟเวอร์เกม (เช่น การเก็บข้อมูล 7 วันเป็นค่าเริ่มต้น)
  • 1~9999: จะใช้หมายเลขที่ระบุเป็นจำนวนวัน (เช่น หากค่าคือ 14 หมายความว่าเก็บข้อมูล 14 วัน)
  • -1: จะใช้ค่ามากที่สุดที่สามารถตั้งโดยเซิร์ฟเวอร์เกม (เช่น การเก็บข้อมูลถาวร)

ข้อกำหนดการตอบสนอง (เซิร์ฟเวอร์เกม -> ไอเท็มในรัง)¶

การตอบสนอง (เซิร์ฟเวอร์เกม -> Hive รายการ)

• รหัสข้อผิดพลาด

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

curl -L -v 
-d '{"transactionId":"27905","idCategory":"player_id","id":"828292","detail":[{"action":"p","assetCode":"gold","amount":500},{"action":"p","assetCode":"gem","amount":200}],"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":"GLOBAL","additionalinfo":"{\"character\":1}","gameIndex":539}' 
-H "Content-Type: text/html" 
-H "Apihash: 54e7a0fc8abfdba398e30213496c2d85ec6e0e06" 
https://sandbox-misample.com2us.net/hive/item

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

> POST /hive/item HTTP/2
> Host: sandbox-misample.com2us.net
> user-agent: curl/7.68.0
> accept: */*
> content-type: text/html
> apihash: 54e7a0fc8abfdba398e30213496c2d85ec6e0e06
> content-length: 447

• ตัวอย่างการตอบกลับ

< HTTP/2 200
< server: nginx
< date: Tue, 12 Jul 2022 11:29:21 GMT
< content-type: application/json; charset=utf-8
<
* Connection #0 to host sandbox-misample.com2us.net left intact
{"status":"200","code":"20001","message":"this request has already been processed"}

ตัวอย่างคำขอ(PHP)

    // data request
$data = array(
    'transactionId'     => '12321',
    'idCategory'        => 'player_id',
    '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": "player_id",
    "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);

ตัวอย่างการตอบกลับ (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 การขอชำระเงิน/คืนเงิน¶

API การชำระเงิน/การเรียกคืนที่ใช้ Socket ทำงานบน TCP/IP ซึ่งเป็นโปรโตคอลสำหรับการสื่อสารข้อมูลแบบแพ็กเก็ต โดยมีพอร์ตเริ่มต้นที่ 20080 ข้อมูลอยู่ในรูปแบบ JSON เดียวกันกับการสื่อสารผ่าน HTTP และลำดับไบต์เป็นลำดับไบต์เครือข่าย (Big-endian)

ข้อกำหนดแพ็กเก็ตคำขอ (รายการรังผึ้ง -> เซิร์ฟเวอร์เกม)¶

• 4 ไบต์แรกแสดงถึงความยาวรวมของแพ็กเกจรวมถึง 4 ไบต์นี้
  ตัวอย่างเช่น หากส่วนหัวมีขนาด 46 ไบต์และเนื้อหามีขนาด 100 ไบต์ ดังนั้น 4+4+46+4+100 = 158 ไบต์
• 4 ไบต์ถัดไปแสดงถึงความยาวของส่วนหัวที่ตามมา
• ส่วนหัวอยู่ในรูปแบบสตริง JSON เดียวกันกับค่าแฮชในการสื่อสาร HTTP
  ตัวอย่างเช่น, {"Apihash":"912ec803b2ce49e4a541068d495ab570"}
• 4 ไบต์สุดท้ายแสดงถึงความยาวของเนื้อหาที่ตามมา
• เนื้อหาอยู่ในรูปแบบสตริง JSON เดียวกันกับค่าคำขอในการสื่อสาร HTTP.

ข้อกำหนดแพ็กเก็ตการตอบกลับ (เซิร์ฟเวอร์เกม -> ไอเท็มฮีฟ)¶

• 4 ไบต์แรกระบุความยาวของแพ็กเก็ตทั้งหมด รวมถึง 4 ไบต์นั้น
• เนื้อหาอยู่ในรูปแบบสตริง JSON เดียวกันกับค่าการตอบกลับในสื่อสาร HTTP.