与项目同步
Item是一個系統,用於整合和管理遊戲貨幣和遊戲中的物品的發送和檢索功能。通過 Item,您可以連接到多種系統,例如優惠券系統、活動、獎勵牆和CPI,以發送或檢索物品,並且可用於管理員的後台可以手動查詢發送和檢索物品的歷史記錄。
Note
- 請求 API 以交付/檢索項目 是異步的,並根據請求信息註冊的成功或失敗來響應 API 請求。
- 您可以從 交付/檢索項目請求或交付/檢索項目成功日誌 頁面中,通過點擊搜索結果中的 狀態 圖標顯示的詳細頁面來確認對實際過程的響應,例如調用遊戲伺服器 API;前往 控制台 > 計費 > 項目 > 交付/檢索項目請求或交付/檢索項目成功日誌。
連接準備¶
確保在項目管理菜單上註冊遊戲伺服器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 的主體中)。
- 請求主體
欄位名稱 | 描述 | 類型 | 必填 (必填: M, 選填: O) |
---|---|---|---|
transactionId | 用於區分每個請求的識別碼(檢查重複請求) 查看更多 | 字串 | M |
idCategory | ID * 單一模組: hiveuid * 認證 v1: vid * 認證 v4: playerid | 字串 | M |
id | 與 idCategory 對應的 ID 值 | 字串 | M |
detail | 以下三個項目的陣列(物件) | 陣列 | M |
ㄴ action | 是否發送或檢索 * s 或 p: 發送 * w 或 r: 檢索 | 字串 | M |
ㄴ assetCode | 要發送的項目代碼 | 字串 | M |
ㄴ amount | 發送項目的數量 | 整數 | M |
reason | 請求的原因 查看更多 | 字串 | M |
subReason | 請求的原因 查看更多 | 字串 | O |
serverId | 目標用戶訪問的伺服器(伺服器 ID) | 字串 | M |
additionalinfo | 從客戶端發送到遊戲伺服器的附加信息(全小寫) | 字串 | O |
duration | 存放物品在禮品盒中的期間(選填) 查看更多 1-9999: 存放物品的期間 -1: 可在遊戲伺服器上配置的最大值 | 整數 | O |
userMessage | 傳遞的消息數據是不可更改的,並且可以與不使用 templateMessage 的舊遊戲進行互換 | 字串 | O |
templateMessage | 設定給項目交付的消息數據,消息鍵帶有語言代碼,值帶有標題和消息正文 (如果數據存在,默認格式為物件,但如果為空,則返回的值為字串類型。) | 物件 | O |
gameIndex | AppCenter 中每個遊戲的序號 | 整數 | M |
transactionId
- 透過識別每個請求的transactionId來區分請求是否已經處理過。(避免重複發送/檢索)
- 在重複請求的情況下,請在響應值中指定。(參考響應規範)
原因
Note
原因字段的详细信息可以添加或更改,因此请将发生原因作为参考。
字段名稱描述<
pe | 付款錯誤 |
rge | 獎勵遊戲錯誤 |
rcd | 獎勵消費者不滿意 |
rce | 獎勵優惠券錯誤 |
ro | 獎勵海外 |
ae | 資產交換 |
e | 事件 |
ea | 事件自動化 |
mc | 大量優惠券 |
uc | 獨特優惠券 |
b | 遊戲內收費(IAP v2) |
lb | Lebi 收費 |
co | CPI 提供牆 |
p | 促銷 用於跨橫幅、提供牆和用戶獲取 |
sr | 串流獎勵 |
tcs | 測試客服 |
tgm | 測試 GM |
tpm | 測試 PM |
tqa | 測試 QA |
td | 測試開發者 |
tg | 測試訪客 |
tmb | 測試市場、商業 |
to | 測試海外(測試開發者) |
re | 檢索(等) |
rr | 檢索退款 |
mr | 大量請求 |
etc | 等等 |
subReason<
原因 | 子原因 | 描述 |
p | 促銷請求的詳細信息 | |
1 | 跨正常橫幅的CPI | |
2 | 跨正常橫幅的CPA | |
3 | 跨插頁橫幅的CPI | |
4 | 跨插頁橫幅的CPA | |
5 | Offerwall上的CPI | |
6 | Offerwall上的CPA | |
7 | Offerwall特別的CPI | |
8 | Offerwall特別的CPA | |
9 | UA上的CPI | |
10 | UA上的CPA | |
11 | UC上的CPI |
促銷類型
- 交叉推廣:可以在用戶當前遊玩的遊戲中以橫幅和獎勵牆(免費遊戲現金)格式廣告其他遊戲。交叉推廣分為普通橫幅和插頁橫幅。
- 獎勵牆:顯示從未在用戶設備上安裝過的遊戲的橫幅類型列表。用戶點擊橫幅並安裝新遊戲後會發送獎勵。獎勵牆有兩種類型;獎勵牆和特別獎勵牆。
- UA/UC:通過社交媒體或QR碼進行邀請。邀請和被邀請的用戶都存在於UA中,但被邀請的用戶僅存在於UC中。使用UC進行預註冊。
如何獎勵
- CPI: 當用戶在安裝後第一次玩遊戲時,會發送獎勵。
- CPA: 當用戶在遊戲中完成特定成就時,會發送獎勵。欲了解更多詳情,請參閱促銷操作指南。
持續時間
- 這是將物品存放在禮品盒中的期間。您可以在後台根據物品單獨設置。
- 遊戲伺服器根據以下情況進行處理。
- 鍵不存在:使用遊戲伺服器提供的預設值。(例如,存放物品最多7天)
- 1~9999:使用其中一個數字作為存放天數。(例如,值14表示存放物品14天)
- -1:使用遊戲伺服器上可配置的最大值。(例如,永久存放物品)
回應規範 (從遊戲伺服器到項目)¶
回應 (從遊戲伺服器到 物品)
字段名称 | 描述 | 类型 | 必需 (强制: M, 选项: O) |
代码 | 处理结果代码 查看更多 | 整数 | M |
消息 | 处理结果消息 | 字符串 | M |
- 錯誤代碼
代碼 描述 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<
- 回應 範例<
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字節 | 可變 | 4字節 | 可變 |
描述 | 封包的整體長度 | 標頭的長度 | 標頭的內容 | 主體的長度 | 主體的內容 |
- 在前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个字节中,指定整个数据包的长度,包括这4个字节。
- Body 是 JSON String 格式,与 HTTP 通信的响应值相同。