与项目同步
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。
請求規範 (蜂巢項目 -> 遊戲伺服器)¶
HTTP 標頭 : Apihash
- 要驗證數據,請將哈希值與鍵 Apihash 一起發送。
- 使用 SHA1 作為哈希值。 (將前綴 !@#COM2US!@# 添加到主體 JSON 字符串)
請求主體 (Hive 物品 -> 遊戲伺服器)
字段名称 | 描述 | 类型 | 必需 (必需: M, 可选: O) |
---|---|---|---|
transactionId | 用于区分每个请求的标识符(用于重复请求验证) 详细信息 | 字符串 | M |
idCategory | ID
| 字符串 | M |
id | 与 idCategory 对应的 ID 值 | 字符串 | M |
detail | 三个项目的对象数组 | 数组 | M |
ㄴaction | 是否授予/撤销
| 字符串 | M |
ㄴassetCode | 要授予的项目代码 | 字符串 | M |
ㄴamount | 要授予的数量 | 整数 | M |
reason | 请求的原因 详细信息 | 字符串 | M |
subReason | 请求的原因 详细信息 | 字符串 | O |
serverId | 目标用户连接的服务器(服务器标识符) | 字符串 | M |
additionalinfo | 从客户端传递到游戏服务器的附加信息(全部小写)(以 JSON 字符串格式) | 字符串 | O |
duration | 邮箱保留期(可选) 详细信息
| 整数 | O |
userMessage | 项目授予消息(固定消息) 兼容不使用 templateMessage 的旧游戏 | 字符串 | O |
templateMessage | 为项目授予消息设置的消息 数据键是语言代码,值由消息(标题)和正文组成 (但是,如果数据存在,默认格式为对象,如果为空,则作为空字符串发送) | 对象 | O |
gameIndex | 每个 Hive 应用中心游戏的序列号 | 整数 | M |
交易識別碼¶
- 它識別請求是否已由 transactionId 處理過。(防止重複付款/收款)
- 在重複請求的情況下,響應值指定相關細節。(請參考響應規範)
原因¶
Note
此原因字段的詳細信息可能會在稍後添加/更改,因此此請求的原因僅應用於參考目的。
欄位名稱 | 描述 |
---|---|
pe | 付款錯誤 |
rge | 獎勵遊戲錯誤 |
rcd | 獎勵消費者不滿意 |
rce | 獎勵優惠券錯誤 |
ro | 獎勵海外 |
ae | 資產交換 |
e | 事件 |
ea | 事件自動 |
mc | 大量優惠券 |
uc | 獨特優惠券 |
b | 計費 * HIVE IAP v2 |
lb | Lebi 計費 |
co | Cpi 提供牆 |
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:利用社交媒體和QR碼的遊戲邀請功能。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 | 數據庫註冊錯誤 |
ㄴ 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 格式,字節順序為網絡字節順序(大端)。
請求封包規範 (hive 物品 -> 遊戲伺服器)¶
封包大小 | 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字串格式。