Hive item is a system to integrate and manage the delivering and retrieving features of game money & item in games. By Hive 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.
- Request API for Delivering/Retrieving Items is asynchronous, and responds to API requests according to success or failure of request information registration.
You can confirm the responses to the actual process, such as the calling game server API, from the detailed page that is displayed when clicking the Status icon from the search results on the Delivering/retrieving Items Request or Delivering/Retrieving Items Success Log page; go to Hive Console > Billing > Hive Item > Delivering/retrieving Items Request or Delivering/Retrieving Items Success Log.
Preparation for Connection
Make sure to register the game server URL and items on Hive 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.
- Hive item sends JSON string to game server to request sending or retrieving items.
- Game server returns the result with JSON string to Hive 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.202.181.123 (Sandbox server)
Monitoring game server health
Hive item sends the below fields to Request Body (from Hive item to game server) in the Request API for delivering/retrieving items every five minutes for two times. By doing this, Hive item can monitor the game server health.
|
1 |
{"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 Hive item. The Hive 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 Hive 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
1234567891011121314151617181920212223242526// 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 \uc9c0\uae09 \uba54\uc138\uc9c0 QA \ud55c\uad6d","body": "HIVE 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
In the Request API for delivering/retrieving items with the method of HTTP communication, 80 is required as default port, and other ports needs a request to unable the firewall. The request from Hive item to game server is sent to POST.
Request specification (From Hive 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 (From Hive item to game server)
| Field Name | Description | Type | Required (Madatory: M, Option: O) |
| transactionId | Identifier to distinguish each request (for checking duplicate request) See more | String | M |
| idCategory | ID
|
String | M |
| id | The ID value corresponding to idCategory | String | M |
| detail | Array of three items (object) below | Array | M |
| ㄴaction | Whether to send or retrieve
|
String | M |
| ㄴassetCode | Item code to send | String | M |
| ㄴamount | The amount of sending items | Integer | M |
| reason | Reason for the request See more | String | M |
| subReason | Reason for the request See more | String | O |
| serverId | The server where the target user accessed (Server ID) | String | M |
| additionalinfo | Additional information sent from client to game server (all small letters) | String | O |
| duration | The period of storing items in gift box (Optional) See more
|
Integer | O |
| userMessage | Message data delivered items is non-changeable and is able to interchange with old games which are not using templateMessage |
String | O |
| templateMessage | Message data set for the item delivery messagekey with language code, value with title and body of a message (If data exist, the default format is Object, but if it’s empty, the value returns as String type.) |
Object | O |
| gameIndex | The serial number of each game in Hive AppCenter | Integer | M |
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
| pe | Payment Error |
| rge | Reward Game Error |
| rcd | Reward Consumer Dissatisfaction |
| rce | Reward Coupon Error |
| ro | Reward Overseas |
| ae | Asset Exchange |
| e | Event |
| ea | Event Automatic |
| mc | Massive Coupon |
| uc | Unique Coupon |
| b | In-game Billing with HIVE IAP v2 |
| lb | Lebi Billing |
| co | CPI Offerwall |
| p | Promotion Use equally for cross banner, offerwall and UA |
| sr | Streaming reward |
| tcs | Test CS |
| tgm | Test GM |
| tpm | Test PM |
| tqa | Test QA |
| td | Test Developer |
| tg | Test Guest |
| tmb | Test Market, Business |
| to | Test Overseas (Test Developer) |
| re | Retrieve (Etc.) |
| rr | Retrieve Refund |
| mr | Massive Request |
| etc | Etc. |
subReason
| Reason | subReason | Description |
| p | Details for the promotion request | |
| 1 | CPI on Cross normal banner | |
| 2 | CPA on Cross normal banner | |
| 3 | CPI on Cross full banner | |
| 4 | CPA on Cross full banner | |
| 5 | CPI on Offerwall | |
| 6 | CPA on Offerwall | |
| 7 | CPI on Offerwall special | |
| 8 | CPA on Offerwall special | |
| 9 | CPI on UA | |
| 10 | CPA on UA | |
| 11 | CPI on UC |
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 full 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 Hive item)
Response (From game server to Hive item)
| Field Name | Description | Type | Required (Madatory: M, Option: O) |
| code | Process result code See more | Integer | M |
| message | Process result message | String | M |
- 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 exists4xxxx 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
123456curl -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
1234567> 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
1234567< 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)
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 |
// 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)
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 |
// 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 Hive item to game server)
| Packet Size | 4byte | 4byte | variable | 4byte | variable |
| Description | The whole length of Packet | The length of Header | The content of Header | The length of Body | The content of Body |
- 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 Hive item)
| Packet Size | 4byte | Variable |
| Content | The whole length of packet | Body |
- 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.