与 Item 同步
Item 是一个集成和管理游戏货币和物品的交付与检索功能的系统。通过 Item,您可以连接到各种系统,例如优惠券系统、活动、提供墙和 CPI,以发送或检索物品,并且管理员的后台可以手动搜索发送和检索物品的历史记录。
Note
- **请求API以交付/检索项目**是异步的,并根据请求信息注册的成功或失败响应API请求。
- 您可以从**交付/检索项目请求或交付/检索项目成功日志**页面的搜索结果中点击**状态**图标显示的详细页面确认实际过程的响应,例如调用游戏服务器API;前往控制台 > 计费 > 项目 > 交付/检索项目请求或交付/检索项目成功日志。
连接准备¶
确保在项目管理菜单中注册游戏服务器URL和项目,以便与之同步。
请求 API 以交付/检索物品¶
检查请求 API 的基本知识以交付/检索项目¶
API通信方法¶
- 请求 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":""}
在接收到请求 主体字段后,游戏服务器可能会发生验证错误。在这种情况下,请在响应值中填写代码和消息字段,并对项目进行响应。如果代码和消息字段存在,项目会识别游戏服务器是正常的。如果响应中缺少这两个字段,则游戏服务器被视为异常。
验证一个 apihash 值¶
您的游戏服务器能够通过使用 Item服务器发送的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 }
请求 API 以通过HTTP通信的方法交付/检索项目¶
授予/撤销请求 API 使用 HTTP 协议与在 Hive 控制台 > 计费 > 项目 > 项目注册 菜单中设置的游戏服务器 (URL) 进行通信,请求数据传输方式为 POST。
请求 规范(从 项目到游戏服务器)¶
HTTP Header: Apihash<
- 对于数据验证,传输哈希值和键值,Apihash。
- 使用 sha1 作为哈希值(将前缀 !@#COM2US!@# 添加到 JSON String 的主体中)。
- 请求体
字段名称 | 描述 | 类型 | 必需 (强制: M, 选项: O) |
---|---|---|---|
transactionId | 用于区分每个请求的标识符(用于检查重复请求) 查看更多 | 字符串 | M |
idCategory | ID * 单模块: hiveuid * Auth v1: vid * Auth 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 | 测试 CS |
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) |
code | 处理结果代码 查看更多 | 整数 | M |
message | 处理结果消息 | 字符串 | M |
- 错误代码
代码 描述 2xxxx 清除。处理成功 ㄴ 20000 清除。处理成功 ㄴ 20001 清除 成功案例已存在(在重复请求的情况下) 正常处理的 transactionId 已存在 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
- 请求 示例<
- 响应 示例<
请求 示例(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);
Response Sample(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 通信的响应值相同。