跳转至

与 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
  • 身份验证 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 促销 * 用于跨横幅、提供墙、用户获取的相同内容
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 &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格式,字节顺序为网络字节顺序(大端)。

请求数据包规范(蜂巢项目 -> 游戏服务器)

数据包大小 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字符串格式。