跳轉至

与项目同步

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": "player_id",
    "id": "1004",
    "detail": [
        {
            "action": "p",
            "assetCode": "gem",
            "amount": 1
        }
    ],
    "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 Hive 用户类型(使用固定值 player_id 字符串 M
id Hive 用户 ID(player_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":"player_id","id":"828292","detail":[{"action":"p","assetCode":"gold","amount":500},{"action":"p","assetCode":"gem","amount":200}],"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":"GLOBAL","additionalinfo":"{\"character\":1}","gameIndex":539}' 
-H "Content-Type: text/html" 
-H "Apihash: 54e7a0fc8abfdba398e30213496c2d85ec6e0e06" 
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: 54e7a0fc8abfdba398e30213496c2d85ec6e0e06
> 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'        => 'player_id',
    '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": "player_id",
    "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字符串格式。