与 Item 同步
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 值验证¶
游戏服务器可以通过 Header 中的 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__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 | 促销 * 用于跨横幅、提供墙、用户获取相同 |
*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 | 哈希错误 |
ㄴ 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操作,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个字节。
- Body的格式与HTTP通信中的响应值相同,都是JSON字符串格式。