Skip to content

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
    > 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 &amp; 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' =&gt; 50001,
    'message' =&gt; '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.