与项目同步

Item是一個系統，用於整合和管理遊戲貨幣和遊戲中的物品的發送和檢索功能。通過 Item，您可以連接到多種系統，例如優惠券系統、活動、獎勵牆和CPI，以發送或檢索物品，並且可用於管理員的後台可以手動查詢發送和檢索物品的歷史記錄。

連接準備¶

確保在項目管理菜單上註冊遊戲伺服器URL和項目以進行同步。

請求 API 以交付/檢索項目¶

檢查請求 API 的基本原則以交付/檢索項目¶

API 通信方法¶

• Request 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":""}

在接收到Request Body字段後，遊戲伺服器可能會發生驗證錯誤。在這種情況下，請在Response值中填寫錯誤數據的代碼和消息字段，並對項目作出回應。如果代碼和消息字段存在，則項目會識別遊戲伺服器是正常的。如果響應中缺少這兩個字段，則遊戲伺服器被視為異常。

驗證 apihash 值¶

您的遊戲伺服器能夠通過使用項目伺服器發送的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
  }
  

Request 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	清除 成功案例已存在（在重複請求的情況下） 正常處理的交易ID已存在
  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
  

• 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
  

• 回應 範例<

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

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);

回應 範例(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 通信的响应值相同。