Sync with Item

The Hive item is a system provided to manage the payment/retrieval functions of in-game currency or items. Hive item integration provides the functionality to give or retrieve items in conjunction with coupon systems, events, offer walls, CPI, etc. In the admin back office, items can be manually given/retrieved or history can be searched.

Integration preparation requirements¶

To integrate with Hive items, you must first register the game server URL and items in the Hive Item Management menu.

Payment/recovery request API¶

Check the basics of the payment/refund request API¶

API communication method¶

• The grant/recovery request API provides two types of communication: HTTP communication and socket-based JSON String communication.
• It requests the grant or recovery in JSON String format from the game server to the Hive item.
• The game server returns the result in JSON String format to the Hive item.
• The response result includes a processing code and message.
• All JSON Strings must be encoded in UTF8.

How to apply the game¶

• Before the service opens, the test server will be used to send integration test results, and after the service opens, the production server will be used.
• Even if the game is already in service, it must be integrated with the test server.
• All items will be provided via the mailbox.
• If a display message is needed for the user in the mailbox, please refer to Request Specification > Request Reason. The game server must handle the display message according to each language.
• Item requests will be sent one per user. Multiple requests for granting/retrieving items can be sent simultaneously, but a single request must be processed within one transaction. If one item grant/retrieval fails, implement it to respond with a failure after a complete rollback.

Game server firewall release¶

To communicate with the server, you need to disable the inbound firewall rules for the IP below on the game server.

• 52.79.76.25
• 3.37.22.75
• 43.133.238.219 (sandbox server)

Game server health check¶

Hive items send the following details to the grant/revoke request API to check the status of the game server. The Hive item server sends this to the game server twice at 5-minute intervals in the Request Body.

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

The game server that receives the above content may encounter a validation error, and in this case, it should respond with the error information in the code and message fields of the response value. Hive items do not determine the code value alone. If the code and message fields are present, the game server is considered normal; if they are absent, the game server is considered to be in an abnormal state.

Apihash value verification¶

The game server can validate the data received from the Hive item server through the Apihash value in the Header. Before verifying the hash value, it is essential to convert the Request Body data received from the Hive item server to JSON encode or unicode. (Refer to the example code)
By mixing the prefix of the request specification and the converted JSON String value (prefix + JSON String), a SHA1 formatted hash value is generated, and this value is compared with the Apihash value for verification.

• Example 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": "HIVE Item uc9c0uae09 uba54uc138uc9c0 QA ud55cuad6d",
            "body": "HIVE Item uc9c0uae09 uba54uc138uc9c0 QA ud55cuad6duc5b4 ub178ucd9c"
        }
    },
    "serverId": "kr",
    "additionalinfo": "",
    "gameIndex": 539
}

Payment/refund request API for HTTP communication methods¶

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

Request specification (hive item -> game server)¶

HTTP Header : Apihash

• To validate the data, send the hash value with the key Apihash.
• Use SHA1 for the hash value. (Add the prefix !@#COM2US!@# to the body JSON String)

Request Body (Hive item -> game server)

transactionid¶

• It identifies whether the request has already been processed by the transactionId. (Prevention of duplicate payments/collections)
• In the case of duplicate requests, the response value specifies the relevant details. (Refer to the response specification)

reason¶

subreason¶

Promotion Feature Classification

• Cross Promotion: Users can advertise other games in the current game they are playing in the form of banners and offer walls (free recharge stations). It is divided into regular banners and full-screen banners.
• Offer Wall: The offer wall displays a list of games that have not been installed on the user's device in the form of banners. Users receive rewards when they touch the banner and install the game from the connected market. It is divided into regular offer walls and special offer walls.
• UA/UC: A game invitation feature that utilizes social media and QR codes. UA involves both the inviting user and the receiving user, while UC only includes the receiving user. UC can be utilized in pre-registration.

Reward Method

• CPI: Rewards are given after launching the game after installation.
• CPA: Rewards are given for achieving specified goals during the game. For more details, please check the Promotion Operation Guide.

duration¶

• The period for which the requested item is stored in the mailbox after being issued can be individually set for each item in the back office.
• The game server handles it in three cases according to the situation.
  • If the key does not exist: The default value set by the game server is used. (e.g. default 7 days storage)
  • 1~9999: The specified number is used as the number of days. (e.g. if the value is 14, it means 14 days of storage)
  • -1: The maximum value that can be set by the game server is used. (e.g. permanent storage)

Response specification (game server -> hive item)¶

Response (Game server -> Hive item)

• Error code

• Request 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":"ud55cuae00 uba54uc138uc9c0","body":"ud55cuae00 ub0b4uc6a9"},"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 Sample(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"
}
*****************************************************************/

Socket communication method for payment/refund request API¶

The payment/retrieval request API using Socket operates on TCP/IP, which is a protocol for packet data communication, with a default port of 20080. The data is in the same JSON format as during HTTP communication, and the byte order is Network Byte order (Big-endian).

Request packet specification (hive item -> game server)¶

• The first 4 bytes indicate the total length of the packet including these 4 bytes.
  For example, if the header is 46 bytes and the body is 100 bytes, then 4+4+46+4+100 = 158 bytes
• The next 4 bytes indicate the length of the Header that follows.
• The Header is in the same JSON string format as the hash value in HTTP communication.
  For example, {"Apihash":"912ec803b2ce49e4a541068d495ab570"}
• The last 4 bytes indicate the length of the Body that follows.
• The Body is in the same JSON string format as the request value in HTTP communication.

Response packet specification (game server -> hive item)¶

• The first 4 bytes specify the length of the entire packet, including those 4 bytes.
• The Body is in the same JSON string format as the response value in HTTP communication.