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.
Note
- 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 Console > Billing > 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 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
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 * Single module: hiveuid * Auth v1: vid * Auth v4: playerid | 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 * s or p: Send * w or r: 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 1-9999: The period of storing items -1: The maximum available to configure on game server | 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 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
Note
The details of reason field are possible to be added or changed, so see the occurrance reason as a reference.
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 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 interstitial banner | |
4 | CPA on Cross interstitial 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 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)
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 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
- Response Sample
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)¶
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 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.