Sync with Item

Item is a system to integrate and manage the delivering and retrieving features of game money & Item in games. By Item, you can connect with diverse systems such as coupon system, event, offerwall and CPI to send or retrieve items, and back office for administrator is available to manually search the history of sending and retrieving items.

Preparation for connection¶

Make sure to register the game server URL and items on Item Management menu to sync with it.

Request API for delivering/retrieving Items¶

Checking fundamentals of request API for delivering/retrieving items¶

API communication method¶

• Request API for delivering/retrieving items provides two types of communication; HTTP type and JSON string type using socket.
• Item sends JSON string to game server to request sending or retrieving items.
• Game server returns the result with JSON string to Item.
• The result of response includes process code and messages.
• JSON string should be encoded into UTF8.

How to apply the game¶

• Prior to service open, test the connection on the test server. After starting the service, deliver to common server.
• Test server should be connected while in service.
• Item is sent basically through the giftbox.
• If text for Item-sending description is needed for users to see on the giftbox, refer to Request Body > reason. Game server should process the description text by language.
• Item request is sent by user one by one. More than one delivering/retrieving Item can be sent simultaneously, but make sure to process one request within one transaction. If one of delivering/retrieving items is failed, implement to rollback the whole request and respond to the failure.

Disable game server firewall¶

You should disable inbound firewall rules on the IP below from the game server for server communication.
• • 52.79.76.25
  • 3.37.22.75
  • 43.133.238.219 (Sandbox server)

Monitoring game server health¶

Item sends the below fields to Request Body (from Item to game server) in the Request API for delivering/retrieving items every five minutes for two times. By doing this, Item can monitor the game server health.

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

After receiving the Request Body fields, a validation error may occur on the game server. In this case, fill the code and message field in the Response value with the error data, and respond to Item. The Item recognizes that the game server is normal if the code and message fields exist. Without two fields in the response, the game server is considered as abnormal.

Verifying an apihash value¶

Your game’s server is able to validate the data that Item server sent by using an Apihash value of Header. Before verifying the hash value, you need to convert the request body data into JSON encode or unicode. (Refer to the sample code below) Add the prefix of request specification to the converted JSON string value to create a hash value in a SHA1 format. Then, you can validate the Apihash value by comparing it with the created SHA1 hash.

• Sample Code

  // Example of a transformed JSON String (add a line and spaces for readability)
  {
  "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 for delivering/retrieving items with the method of HTTP communication¶

The grant/revoke request API communicates with the game server (URL) set in the Hive Console > Billing > Item > Item Registration menu using the HTTP protocol, and the request data transmission method is POST.

Request specification (From Item to game server)¶

HTTP Header: Apihash

• For data validation, transmit the hash value with a key value, Apihash.
• Use sha1 for the hash value (add the prefix !@#COM2US!@# to the body of JSON String).

• Request Body

transactionId

• Distinguish whether the request has processed already by identifying transactionId of each request. (Avoid duplicate send/retrieve)
• In the case of duplicate request, specify it in the response value. (Refer to response specification)

reason

Field NameDescription

subReason

Promotion types

• Cross promotion: It is available to advertise other games with banner and offerwall (Free game cash) formaton the game which user currently play. Cross promotion is divided into normal banner and interstitial banner.
• Offerwall: It displays a banner-typed list of games which have never installed on user device. Rewards are sent after user touches the banner and installs a new game. Offerwall has two types; offerwall and offerwall special.
• UA/UC: It features an invitation through social media or QR code. Both inviting and invited users exist in UA, but invited users only in UC. Use UC for pre-registration.

How to reward

• CPI: Rewards are sent when user plays the game for the first time after installation.
• CPA: Rewards are sent when user completes the specific achievement in the game. For more deails, refer to Guide for operating promotion.

duration

• It is the period of storing items in gift box. You can set on the back office individually by items.
• Game server processes in accordance with the following cases.
  • Non-existence of the key: It uses the default value provided by game server. (e.g., Storing items up to 7 days)
  • 1~9999: It uses one of the numbers as storing days. (e.g., The value 14 means 14 days for storing items)
  • -1: It uses the maximum available to configure on game server. (e.g., Storing items permanently)

Response specification (From game server to Item)¶

Response (From game server to Item)

• Error code

  Code	Description
  2xxxx	Clear. Process success
  ㄴ 20000	Clear. Process success
  ㄴ 20001	Clear Success case already exists (in the case of duplicate request) Normally processed transactionId already exists
  4xxxx	Request parameter error
  ㄴ 40001	Request JSON error
  ㄴ 40002	Hash error
  ㄴ 40003	Essential parameter key omitted
  ㄴ 40004	Essential parameter key type error
  ㄴ 40005	Essential parameter null
  ㄴ 40006	Essential parameter wrong (e.g., negative number)
  5xxxx	Server process error
  ㄴ 50001	Invalid user
  ㄴ 50004	DB registration error
  ㄴ 50005	Parameter error (e.g., invalid Item code)

• 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"
    }
    *****************************************************************/

Request API for delivering/retrieving items by using socket¶

TCP/IP of Request API for delivering/retrieving items by using socket is a packet data communication. The API uses protocol, and its port is 20080. Data is basically JSON format, the same format as HTTP communication, and byte order format is Network byte order (Big-endian).

Request packet specification (From Item to game server)¶

• In the first 4byte, specify the whole length of the packet including the 4byte. e.g., If header is 46byte and body is 100byte, the length of packet is 4+4+46+4+100=158byte.
• The next 4byte specifies the length of Header coming after.
• Header is JSON String format, the same as hash value of HTTP communication. e.g.,{"Apihash":"912ec803b2ce49e4a541068d495ab570"}
• The next 4byte specifies the length of Body coming after.
• Body is JSON String format, the same as request value of HTTP communication.

Response packet specification (From game server to Item)¶

• In the first 4byte, specify the whole length of the packet including the 4byte.
• Body is JSON String format, the same as response value of HTTP communication.