跳轉至

与项目同步

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
  • 身份验证 v4: playerid
字符串 M
id 与 idCategory 对应的 ID 值 字符串 M
detail 三个项目的对象数组 数组 M
ㄴaction 是否授予/撤销
  • s 或 p: 授予
  • w 或 r: 撤销
字符串 M
ㄴassetCode 要授予的项目代码 字符串 M
ㄴamount 要授予的数量 整数 M
reason 请求的原因 详细信息 字符串 M
subReason 请求的原因 详细信息 字符串 O
serverId 目标用户连接的服务器(服务器标识符) 字符串 M
additionalinfo 从客户端传递到游戏服务器的附加信息(全部小写)(以 JSON 字符串格式) 字符串 O
duration 邮箱保留期(可选) 详细信息
  • 1-9999: 保留天数
  • -1: 游戏服务器可以设置的最大值
整数 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 &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 格式,字節順序為網絡字節順序(大端)。

請求封包規範 (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字串格式。