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

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

การเตรียมความพร้อมสำหรับการเชื่อมต่อ¶

โปรดตรวจสอบให้แน่ใจว่าคุณได้ลงทะเบียน 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).

• เนื้อหาคำขอ

transactionId

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

เหตุผล

ชื่อฟิลด์คำอธิบาย<

subReason

ประเภทโปรโมชั่น

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

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

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

ระยะเวลา

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

ข้อกำหนดการตอบสนอง (จากเซิร์ฟเวอร์เกมไปยัง Item)¶

Response (จากเซิร์ฟเวอร์เกมไปยัง รายการ)

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

  รหัส	คำอธิบาย
  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<

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

• Response Sample<

  < 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"}
  

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 ไบต์ เช่น หากส่วนหัวมีความยาว 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 ไบต์
• Body เป็นรูปแบบ JSON String ซึ่งเหมือนกับค่าการตอบสนองของการสื่อสาร HTTP