与 Item 同步

Item 是一个集成和管理游戏货币和物品的交付与检索功能的系统。通过 Item，您可以连接到各种系统，例如优惠券系统、活动、提供墙和 CPI，以发送或检索物品，并且管理员的后台可以手动搜索发送和检索物品的历史记录。

连接准备¶

确保在项目管理菜单中注册游戏服务器URL和项目，以便与之同步。

请求 API 以交付/检索物品¶

检查请求 API 的基本知识以交付/检索项目¶

API通信方法¶

• 请求 API 用于交付/检索物品提供两种类型的通信；HTTP 类型和使用套接字的JSON 字符串类型。
• 物品向游戏服务器发送JSON 字符串以请求发送或检索物品。
• 游戏服务器将结果以JSON 字符串的形式返回给 物品。
• 响应的结果包括处理代码和消息。
• JSON 字符串应编码为UTF8。

如何申请游戏¶

• 在服务开放之前，请在测试服务器上测试连接。服务启动后，交付到公共服务器。
• 测试服务器在服务期间应保持连接。
• 物品基本上通过礼品盒发送。
• 如果需要在礼品盒上让用户看到物品发送描述的文本，请参考请求体 > 原因。游戏服务器应按语言处理描述文本。
• 物品请求由用户逐个发送。可以同时发送多个交付/获取物品，但请确保在一个事务内处理一个请求。如果交付/获取的物品之一失败，请实现回滚整个请求并响应失败。

禁用游戏服务器防火墙¶

您应该禁用来自游戏服务器的以下IP的入站防火墙规则，以便进行服务器通信。
• • 52.79.76.25
  • 3.37.22.75
  • 43.202.181.123（沙盒服务器）

监控游戏服务器健康¶

项目每五分钟向Request Body（从 项目到游戏服务器）发送以下字段，在Request API中交付/检索物品两次。通过这样做， 项目可以监控游戏服务器的健康状况。

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

在接收到请求 主体字段后，游戏服务器可能会发生验证错误。在这种情况下，请在响应值中填写代码和消息字段，并对项目进行响应。如果代码和消息字段存在，项目会识别游戏服务器是正常的。如果响应中缺少这两个字段，则游戏服务器被视为异常。

验证一个 apihash 值¶

您的游戏服务器能够通过使用 Item服务器发送的Apihash值的Header来验证数据。在验证哈希值之前，您需要将请求主体数据转换为JSON 编码或unicode。（请参阅下面的示例代码）将请求规范的前缀添加到转换后的JSON字符串值中，以创建SHA1格式的哈希值。然后，您可以通过将Apihash值与创建的SHA1哈希进行比较来验证它。

• 示例 代码

  // 转换后的 JSON 字符串示例（添加行和空格以提高可读性）
  {
  "transactionId": "123456789",
  "idCategory": "vid",
  "id": "1004",
  "detail": [
      {
          "action": "p",
          "assetCode": "gem",
          "amount": 1,
          "method": ""
      }
  ],
  "reason": "td",
  "subReason": "",
  "userMessage": "",
  "templateMessage": {
      "ko": {
          "title": "物品 \uc9c0\uae09 \uba54\uc138\uc9c0 QA \ud55c\uad6d",
          "body": "物品 \uc9c0\uae09 \xba54\uc138\uc9c0 QA \ud55c\uad6d\uc5b4 \ub178\ucd9c"
      }
  },
  "serverId": "kr",
  "additionalinfo": "",
  "gameIndex": 539
  }
  

请求 API 以通过HTTP通信的方法交付/检索项目¶

授予/撤销请求 API 使用 HTTP 协议与在 Hive 控制台 > 计费 > 项目 > 项目注册 菜单中设置的游戏服务器 (URL) 进行通信，请求数据传输方式为 POST。

请求 规范（从 项目到游戏服务器）¶

HTTP Header: Apihash<

• 对于数据验证，传输哈希值和键值，Apihash。
• 使用 sha1 作为哈希值（将前缀 !@#COM2US!@# 添加到 JSON String 的主体中）。

• 请求体

transactionId<

• 通过识别每个请求的 transactionId 来区分请求是否已经处理过。 (避免重复发送/检索)
• 在重复请求的情况下，在响应值中指定它。 (参考响应规范)

原因

字段名称描述<

subReason<

促销类型

• 交叉推广：可以在用户当前玩的游戏中以横幅和奖励墙（免费游戏现金）格式宣传其他游戏。交叉推广分为普通横幅和插页横幅。
• 奖励墙：它显示一个横幅类型的游戏列表，这些游戏从未在用户设备上安装过。用户点击横幅并安装新游戏后会发送奖励。奖励墙有两种类型；奖励墙和特别奖励墙。
• UA/UC：它通过社交媒体或QR代码进行邀请。邀请用户和被邀请用户都存在于UA中，但被邀请用户仅存在于UC中。使用UC进行预注册。

如何奖励

• CPI: 当用户在安装后第一次玩游戏时，奖励将被发送。
• CPA: 当用户在游戏中完成特定成就时，奖励将被发送。有关更多详细信息，请参阅推广操作指南。

持续时间

• 这是存储物品在礼品盒中的时期。您可以在后台单独设置物品。
• 游戏服务器根据以下情况进行处理。
  • 密钥不存在：使用游戏服务器提供的默认值。（例如，存储物品最多7天）
  • 1~9999：使用其中一个数字作为存储天数。（例如，值14表示存储物品14天）
  • -1：使用游戏服务器上可配置的最大值。（例如，永久存储物品）

响应规范（从游戏服务器到项目）¶

响应 (从游戏服务器到 项目)

• 错误代码

  代码	描述
  2xxxx	清除。处理成功
  ㄴ 20000	清除。处理成功
  ㄴ 20001	清除 成功案例已存在（在重复请求的情况下） 正常处理的 transactionId 已存在
  4xxxx	请求参数错误
  ㄴ 40001	请求 JSON 错误
  ㄴ 40002	哈希错误
  ㄴ 40003	必需参数键遗漏
  ㄴ 40004	必需参数键类型错误
  ㄴ 40005	必需参数为空
  ㄴ 40006	必需参数错误（例如，负数）
  5xxxx	服务器处理错误
  ㄴ 50001	无效用户
  ㄴ 50004	数据库注册错误
  ㄴ 50005	参数错误（例如，无效的项目代码）

• 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
  

• 请求 示例<

  > 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
  

• 响应 示例<

  < 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":"此请求已被处理"}
  

请求 示例(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"
    }
    *****************************************************************/

通过使用套接字请求API以交付/检索项目¶

TCP/IP 的 Request API 用于通过套接字传递/检索项目，是一种数据包通信。API 使用协议，其端口为 20080。 数据基本上是 JSON 格式，与 HTTP 通信相同，字节顺序格式为 Network 字节顺序（Big-endian）。

请求数据包规范（从项目到游戏服务器）¶

• 在前4字节中，指定整个数据包的长度，包括这4字节。 例如，如果头部是46字节，主体是100字节，则数据包的长度为4+4+46+4+100=158字节。
• 接下来的4字节指定后面Header的长度。
• Header是JSON String格式，与HTTP通信的哈希值相同。 例如，{"Apihash":"912ec803b2ce49e4a541068d495ab570"}
• 接下来的4字节指定后面Body的长度。
• Body是JSON String格式，与HTTP通信的请求值相同。

响应数据包规范（从游戏服务器到物品）¶

• 在前4字节中，指定整个数据包的长度，包括这4字节。
• Body 是 JSON String 格式，与 HTTP 通信的响应值相同。