与项目同步
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
| 字符串 | 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 & 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字符串格式。