跳轉至

与项目同步

Hive 物品是一個系統,用於管理遊戲內貨幣或物品的支付/檢索功能。Hive 物品整合提供了與優惠券系統、活動、優惠牆、CPI 等結合的給予或檢索物品的功能。在管理後台,物品可以手動給予/檢索或查詢歷史記錄。

Note
  • 項目授予/恢復請求API 以非同步方式運作,並僅在API請求時通過確定請求信息註冊的成功或失敗來回應。
  • 對於_實際處理行動_(例如遊戲伺服器API調用)的回應,可以在Hive控制台菜單下的計費 > Hive 項目 > 授予/恢復請求授予/恢復成功日誌中檢查,方法是搜索相關內容並點擊搜索結果彈出窗口中的狀態項目。
  • Hive 項目需要處理大規模流量,因此如果開發者的應用伺服器的平均響應時間超過0.5秒,則可能會在單獨的隊列中運作,而不是主隊列。在這種情況下,項目授予處理可能會出現顯著延遲。為了確保項目授予處理的順暢,建議將開發者的應用伺服器的平均響應時間保持在0.5秒以下

整合準備要求

要整合 Hive 物品,您必須首先在 Hive 物品管理 菜單中註冊遊戲伺服器 URL 和物品。

付款/恢復請求 API

檢查支付/退款請求 API 的基本資訊

API 通信方法

  • 授權/恢復請求 API 提供兩種類型的通信:HTTP 通信和基於套接字的 JSON 字串通信。
  • 它以 JSON 字串格式從遊戲伺服器請求授權或恢復到 Hive 項目。
  • 遊戲伺服器以 JSON 字串格式將結果返回到 Hive 項目。
  • 回應結果包括處理代碼和消息。
  • 所有 JSON 字串必須以 UTF8 編碼。

如何申請遊戲

  • 在服務開放之前,將使用測試伺服器來發送整合測試結果,而在服務開放後,將使用生產伺服器。
  • 即使遊戲已經上線,也必須與測試伺服器整合。
  • 所有項目將通過郵箱提供。
  • 如果需要在郵箱中顯示訊息給用戶,請參考 請求規範 > 請求原因。遊戲伺服器必須根據每種語言處理顯示訊息。
  • 項目請求將每位用戶發送一次。可以同時發送多個授予/檢索項目的請求,但單個請求必須在一個事務中處理。如果一個項目授予/檢索失敗,則實現為在完全回滾後響應失敗。

遊戲伺服器防火牆釋放

要與伺服器通信,您需要在遊戲伺服器上為以下 IP 禁用入站防火牆規則。

  • 52.79.76.25
  • 3.37.22.75
  • 43.133.238.219 (沙盒服务器)

遊戲伺服器健康檢查

Hive 項目將以下詳細信息發送到授予/撤銷請求 API,以檢查遊戲伺服器的狀態。Hive 項目伺服器在請求主體中每 5 分鐘間隔向遊戲伺服器發送此信息兩次。

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

接收上述內容的遊戲伺服器可能會遇到驗證錯誤,在這種情況下,它應該在響應值的代碼和消息字段中回應錯誤信息。Hive 項目並不單獨決定代碼值。如果代碼和消息字段存在,則遊戲伺服器被視為正常;如果缺失,則遊戲伺服器被視為異常狀態。

Apihash 值驗證

遊戲伺服器可以通過標頭中的 Apihash 值來驗證從 Hive 物品伺服器接收到的數據。在驗證哈希值之前,將從 Hive 物品伺服器接收到的請求主體數據轉換為 JSON 編碼或 Unicode 是至關重要的。(參考示例代碼)
通過將請求規範的前綴與轉換後的 JSON 字符串值混合(前綴 + JSON 字符串),生成 SHA1 格式的哈希值,並將該值與 Apihash 值進行比較以進行驗證。

  • 範例代碼
    // 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 uc9c0uae09 uba54uc138uc9c0 QA ud55cuad6d",
            "body": "HIVE Item uc9c0uae09 uba54uc138uc9c0 QA ud55cuad6duc5b4 ub178ucd9c"
        }
    },
    "serverId": "kr",
    "additionalinfo": "",
    "gameIndex": 539
}

用於 HTTP 通信方法的付款/退款請求 API

支付/檢索請求 API 通過 HTTP 協議與在 Hive 控制台 > 計費 > 項目 > 項目註冊 菜單中設置的遊戲伺服器 (URL) 進行通信,請求數據傳輸方法為 POST

請求規範 (hive 項目 -> 遊戲伺服器)

HTTP 標頭 : Apihash

  • 要驗證數據,請將哈希值與鍵 Apihash 一起發送。
  • 對於哈希值,使用 SHA1。 (將前綴 !@#COM2US!@# 添加到主體 JSON 字符串)

請求主體 (Hive 項目 -> 遊戲伺服器)

字段名称 描述 类型 必填 (必填: M, 可选: O)
transactionId 用于区分每个请求的标识符(用于重复请求验证) 详细信息 字符串 M
idCategory ID
  • 单个模块: hiveuid
  • 身份验证 v1: vid
  • 身份验证 v4: playerid
字符串 M
id__ITALICS_MD_0__ 它识别请求是否已经通过 transactionId 处理过。 (防止重复支付/收款)
在重复请求的情况下,响应值指定相关细节。 (请参阅响应规范)

原因

Note

原因字段的详细信息可能会在稍后添加/更改,因此此请求的原因仅应用于参考目的。

字段名称 描述
pe__ITALICS_MD_1__ro__ITALICS_MD_2__ae__ITALICS_MD_3__e__ITALICS_MD_4__ea__ITALICS_MD_5__mc__ITALICS_MD_6__uc__ITALICS_MD_7__b 账单 * HIVE IAP v2
lb__ITALICS_MD_8__co__ITALICS_MD_9__p 促销 * 用于跨横幅、提供墙、UA
*sr 流媒体奖励
tcs 测试 CS
tgm 测试 GM
tpm 测试 PM
tqa 测试 QA
td 测试开发者
tg 测试市场、业务
tmb 测试海外 (测试开发者)
re 检索等
rr 检索退款
mr 大规模请求
etc 等等

子原因

原因 子原因 描述
p 推廣子請求詳情
1 跨一般橫幅CPI
2 跨一般橫幅CPA
3 跨前端橫幅CPI
4 跨前端橫幅CPA
5 提供牆一般CPI
6 提供牆一般CPA
7 提供牆特殊CPI
8 提供牆特殊CPA
9 UA CPI
10 UA CPA
11 UC CPI

促銷功能分類

交叉推廣:用戶可以在他們正在玩的當前遊戲中以橫幅和優惠牆(免費充值站)的形式廣告其他遊戲。它分為常規橫幅和全屏橫幅。 * 優惠牆:優惠牆以橫幅的形式顯示用戶設備上尚未安裝的遊戲列表。用戶在觸摸橫幅並從連接的市場安裝遊戲時會獲得獎勵。它分為常規優惠牆和特殊優惠牆。 * UA/UC:利用社交媒體和二維碼的遊戲邀請功能。UA 涉及邀請用戶和接收用戶,而 UC 僅包括接收用戶。UC 可用於預註冊。

獎勵方式

  • CPI: 獎勵在安裝後啟動遊戲後給予。
  • CPA: 獎勵在遊戲中達成指定目標時給予。欲了解更多詳情,請查看推廣操作指南

持續時間

  • 所請求項目在郵箱中存放的期限可以在後台為每個項目單獨設置。
  • 遊戲伺服器根據情況處理三種情況。
    • 如果密鑰不存在:使用遊戲伺服器設置的默認值。(例如,默認存放7天)
    • 1~9999:指定的數字用作天數。(例如,如果值為14,則表示存放14天)
    • -1:使用遊戲伺服器可以設置的最大值。(例如,永久存放)

回應規範 (遊戲伺服器 -> 蜂巢物品)

回應 (遊戲伺服器 -> Hive 物品)

欄位名稱 描述 類型 必填 (必填: M, 選填: O)
code 處理結果代碼 詳情 整數 M
message 處理結果訊息 字串 M
  • 錯誤代碼
代碼值 描述
2xxxx 請求沒有問題。處理成功
20000 請求沒有問題。處理成功
20001 請求沒有問題。
已經成功處理(重複請求)
如果已經存在正常處理的 transactionId
4xxxx 請求參數錯誤
40001 請求 JSON 錯誤
40002 Hash 錯誤
40003 缺少必需的參數鍵
40004 必需的參數鍵類型錯誤
40005 必需的參數值為空
40006 無效的必需參數值(例如:負數)
5xxxx 伺服器處理錯誤
50001 不存在的用戶
50004 DB 註冊錯誤
50005 參數錯誤(例如:不存在的項目代碼)
  • 請求範例
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":"ud55cuae00 uba54uc138uc9c0","body":"ud55cuae00 ub0b4uc6a9"},"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":"this request has already been processed"}

請求範本(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);

回應範例 (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的Socket通信方法

使用 Socket 的支付/檢索請求 API 基於 TCP/IP 操作,這是一種數據包通信的協議,默認端口為 20080。數據格式與 HTTP 通信期間相同,為 JSON 格式,字節順序為網絡字節順序(大端)。

請求封包規範 (蜂巢物品 -> 遊戲伺服器)

封包大小 4 字節 4 字節 可變 4 字節 可變
描述 總封包長度 標頭長度 標頭內容 主體長度 主體內容
  • 前4个字节表示数据包的总长度,包括这4个字节。
    例如,如果头部是46字节,主体是100字节,那么4+4+46+4+100 = 158字节
  • 接下来的4个字节表示后续头部的长度。
  • 头部采用与HTTP通信中的哈希值相同的JSON字符串格式。
    例如,{"Apihash":"912ec803b2ce49e4a541068d495ab570"}
  • 最后4个字节表示后续主体的长度。
  • 主体采用与HTTP通信中的请求值相同的JSON字符串格式。

回應封包規範 (遊戲伺服器 -> 蜜蜂物品)

封包大小 4 字節 可變
內容 總封包長度 主體
  • 前4個字節指定整個數據包的長度,包括這4個字節。
  • 主體與HTTP通信中的響應值採用相同的JSON字符串格式。