铸造
Mint 是一个将游戏物品作为 NFT 发行的功能。在 Hive 控制台中,它根据用户发行选项卡下的 配置详情 发行 NFT,位于 区块链 > XPLA > NFT 菜单中。
铸造功能实现流程¶
以下是Mint功能的实现过程。要实现Mint功能,请遵循流程图图像和下面的指南内容,在游戏客户端 (Hive SDK,游戏客户端) 和游戏服务器区域中实现代码。下图中标有蓝色星号的部分是开发人员需要工作的部分。有关主要任务的更多细节,请参阅下面的指南。
Note
完成准备后,您需要实现Mint功能。
Note
要实现Mint功能,您必须使用Hive SDK。
在 hive SDK 中实现登录¶
在游戏客户端中实现代码,以允许用户使用IdP登录通过Hive SDK身份验证功能登录。还支持网页登录作为登录方式。
实现 NFT 铸造按钮¶
在游戏客户端中实现一个用户界面,允许用户打开NFT发行页面。例如,当用户在访问游戏后从角色库存中选择一个物品时,应该出现一个将物品转换为NFT按钮。当按下此按钮时,应该根据以下内容打开NFT发行页面。
请求将物品转换为NFT¶
实现代码以从游戏客户端向游戏服务器请求用户游戏物品作为NFT的发行。这是为了实现用户选择NFT发行按钮时的操作。当游戏服务器收到来自游戏客户端的请求时,它会检查要作为NFT发行的游戏物品,然后调用API以创建NFT发行页面的链接来将物品作为NFT发行。
NFT 发行页面链接创建 API 调用¶
NFT发行页面是一个网页,用户可以将他们拥有的物品转换为NFT。此网页由Hive区块链服务器提供。游戏服务器调用链接生成API以获取此网页URL(webLinkUrl
)。当用户访问此网页时,他们可以在区块链上铸造游戏内物品为NFT。
注意事项¶
以下是开发人员在进行 API 调用时的注意事项。
游戏服务器网址¶
gameServerUrl
用作 Hive 区块链服务器调用游戏服务器的 请求 URL(物品验证 API 和 结果检查 API)。
游戏服务器网址和令牌¶
当 Hive 区块链服务器调用 项目验证 API 或 结果检查 API 时,游戏服务器可以使用 身份验证令牌(头部参数) 进行 API 调用,这对开发者来说是可选的。如果游戏服务器选择在 API 调用中使用身份验证令牌,则必须在调用 NFT 发行页面链接生成 API 时,将此身份验证令牌作为 token
(查询参数)预先发送到 Hive 区块链服务器。下面是一个示例。
属性¶
attributes
用作请求体,当 Hive 区块链服务器调用 物品验证 API 和 结果确认 API 到游戏服务器时。
当您使用 attributes
中包含的项目唯一代码调用 API 时,唯一代码也可以包含在 结果检查 API 的请求体 attributes
中。在这种情况下,您可以使用相应的唯一代码更新项目状态。
NFT发行页面链接有效期¶
一次创建的页面链接有效期为仅10分钟,基于第一次访问的会话。
请求 URL¶
项目 | 值 |
---|---|
直播网址 | https://bc-platform-api.withhive.com/web3/v1/web-link |
沙盒网址 | https://sandbox-bc-platform-api.withhive.com/web3/v1/web-link |
HTTP 方法 | POST |
内容类型 | application/json |
头部参数¶
字段名称 | 描述 | 类型 | 必需 |
---|---|---|---|
Authorization | API 调用的认证令牌 | 字符串 | 是 |
请求体¶
字段名称 | 描述 | 类型 | 必需 |
---|---|---|---|
type | MINT | 字符串 | 是 |
playerId | 玩家ID | 数字 | 是 |
characterId | 角色ID | 字符串 | 是 |
gameServerUrl | 接收物品验证和功能执行后成功/失败结果的地址。将身份验证令牌作为token 查询参数发送,用于物品验证/结果确认API头 | 字符串 | 是 |
data | 根据类型请求参数信息 | json | 否 |
数据对象¶
字段名称 | 描述 | 类型 | 必需 |
---|---|---|---|
itemId | 用户 NFT 模板标识符(控制台注册) | 字符串 | 是 |
attributes | 每个代币应用的附加元数据属性(例如,唯一物品代码、力量、敏捷等属性,以包含在 NFT 中) | json 数组 | 否 |
attributes.traitType | 组成属性的物品名称 | 字符串 | 否 |
attributes.value | 特征值 | 字符串 | 否 |
请求示例¶
curl -X 'POST' \
'https://sandbox-bc-platform-api.withhive.com/web3/v1/web-link' \
-H 'accept: application/json' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXlObyI6NiwiaWQiOiIvVWpXN....' \
-H 'Content-Type: application/json' \
-d '{
"type": "MINT",
"playerId": 1276814678,
"characterId": "zeratu",
"gameServerUrl": "https://api.com2us.com/hive" //인증 토큰 전송 시: "gameServerUrl": "https://api.com2us.com/hive?token=sInR5cCI6IkpXVC..."
"data": {
"itemId": "HIVE",
"attributes": [
{
"traitType": "item_id",
"value": "sward-3283272101239"
},
{
"traitType": "strength",
"value": "50"
},
{
"traitType": "agility",
"value": "10"
}
]
},
}'
响应¶
字段名称 | 描述 | 类型 |
---|---|---|
code | API 调用结果代码,0: 成功 | number |
message | 结果消息 | string |
data | API 响应数据 | json |
data.webLinkId | 网页链接 ID (UUID) | string |
data.webLinkUrl | 生成的一次性网页链接 (URL) | string |
data.expiration | 网页链接过期日期 (ISO 8601) | string |
响应示例¶
{
"code": 0,
"message": "success",
"data": {
"webLinkid": "b6d2ca1b-b43a-4129-bf54-9a189e3aa664",
"webLinkUrl": "https://sandbox-xpla-platform.withhive.com/api/v1/web-link/redirect?token=b256c85c-aee8-4837-b54d-9a03fe8a7435.f94140b71c9ebf058956547753131adde9968a0266f208d7e3059bbb6dd0c7bc",
"expiration": "2024-08-05T08:33:15.448Z"
}
}
使用 hive SDK 实现 NFT 发行页面¶
NFT发行页面链接创建API 响应中接收到的网页URL通过 Hive SDK. 暴露给外部浏览器
以下是NFT发行页面的示例。
作为NFT发行的项目资料 |
---|
![]() |
当您打开 NFT 发行页面时,将出现一个窗口,用于登录 X-PLANET 钱包 或 XLPA Vault。用户必须选择一个特定的钱包地址,以便在登录 X-PLANET 钱包或 XLPA Vault 后执行铸造或销毁。
Note
XPLA Vault 计划于 2025 年 6 月支持。
X-PLANET | XPLA Vault |
---|---|
![]() | ![]() |
NFT铸造(执行铸造)¶
在NFT发行页面,用户选择一个项目,然后执行铸造。
在发行NFT之前确认佣金 |
---|
![]() |
项目验证 API 调用 (hive 区块链服务器 → 游戏服务器)¶
Note
此 API 不是游戏服务器调用 Hive 区块链服务器的 API,而是 Hive 区块链服务器调用游戏服务器的 API。因此,游戏服务器必须以 Hive 区块链服务器所需的形式配置 API 端点。
在将游戏物品转换为NFT之前,Hive 区块链服务器会向游戏服务器请求物品验证。在从游戏服务器提供的响应中验证物品信息后,Hive 区块链服务器会在区块链上发行NFT。如果item verification fails,Hive 区块链服务器将不会发行NFT。
Note
在游戏服务器中,在通过result confirmation API接收到NFT发行结果之前,应该限制在游戏中已验证物品的使用。
注意事项¶
以下是开发人员在配置 API 端点时的一些考虑事项。
游戏服务器网址¶
此 API 使用从 NFT 发行页面链接创建 API 请求的 gameServerUrl
向游戏服务器请求验证。
授权头部¶
如果在从NFT发行页面链接创建API请求的gameServerUrl
中存在token
查询参数,请使用此token
值以Bearer格式。
属性¶
在生成 NFT 发行页面链接的 API 请求体中包含 attributes
。
请求 URL¶
以下是需要在游戏服务器上准备的API端点信息。
项目 | 值 |
---|---|
URL | {gameServerUrl}/items/validate |
HTTP 方法 | POST |
内容类型 | application/json |
头部参数¶
字段名称 | 描述 | 类型 | 必需 |
---|---|---|---|
授权 | 作为 gameServerUrl 中的 token 查询参数发送的身份验证令牌。以 Bearer ${token} 的形式调用。 | Bearer | 否 |
用户代理 | HiveBlockchain/1.0 | 字符串 | 是 |
请求体¶
字段名称 | 描述 | 类型 | 必需 |
---|---|---|---|
type | MINT | 字符串 | 是 |
itemId | NFT 项目标识符代码 | 字符串 | 是 |
playerId | 玩家 ID | 数字 | 是 |
characterId | 角色 ID | 字符串 | 否 |
webLinkId | 网页链接 ID (UUID) | 字符串 | 是 |
tokenId | NFT ID | 字符串 | 否 |
attributes | 每个代币应用的附加元数据属性(例如,唯一项目代码、力量、敏捷等包含在 NFT 中的属性) | json 数组 | 否 |
attributes.traitType | 组成属性的项目名称 | 字符串 | 否 |
attributes.value | 特征值 | 字符串 | 否 |
请求示例¶
curl -X 'POST' \
'https://api.com2us.com/hive/items/validate' \
-H 'accept: */*' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyb2xlIjoieHBsYS13ZWJ2aWV3IiwiYXBwIjoiY29tLmdjcC5zdGVwYnlzdGVwLnBjd2ViLmJs...' \ // 인증 토크 사용 시
-H 'User-Agent: HiveBlockchain/1.0' \
-d '{
"type": "MINT",
"itemId": "HIVE",
"playerId": 2319123897,
"characterId": "zeratu",
"webLinkId": "b6d2ca1b-b43a-4129-bf54-9a189e3aa664",
"attributes": [ // NFT 발행 페이지 링크 생성 시 attributes
{
"traitType": "item_id",
"value": "sward-3283272101239"
},
{
"traitType": "strength",
"value": "50"
},
{
"traitType": "agility",
"value": "10"
}
]
}'
响应¶
HTTP 状态码如下。
- 成功
- 200
- 失败
- 4xx: 错误状态码用于错误请求
- 5xx: 错误状态码用于服务器错误
结果检查 API 调用 (hive 区块链 → 游戏服务器)¶
Note
这个API不是游戏服务器调用Hive区块链服务器的API,而是Hive区块链服务器调用游戏服务器的API。因此,游戏服务器必须按照Hive区块链服务器所需的形式配置API端点。
当Hive区块链服务器将NFT发行结果传递给游戏服务器时,游戏服务器处理该结果,使得该物品无法在游戏中使用,然后通过API将结果返回给Hive区块链服务器。
游戏服务器将根据发行结果执行的操作如下。
- NFT发行成功
- 使物品在游戏中不可用的过程(例如,从游戏用户的库存中删除物品)
- NFT发行失败
- 使物品在游戏中可用的过程(例如,解除使用限制以允许物品在游戏用户的库存中再次使用)
- 如果用户取消NFT发行或超过某个时间限制,则发送NFT发行失败结果
Warning
您必须在游戏服务器上限制相应物品在游戏中的使用,直到您收到NFT发行结果。
以下是游戏服务器成功响应NFT发行时的NFT发行页面屏幕示例。
注意事项¶
以下是开发人员在配置 API 端点时的一些考虑因素。
属性¶
通过在attributes
中包含唯一物品代码并调用NFT发行页面链接创建API,您还可以在请求体attributes
中包含唯一代码。在这种情况下,您可以使用相应的唯一代码更新物品状态。
授权头¶
如果在从NFT发行页面链接创建API请求的gameServerUrl
中存在token
查询参数,请以Bearer形式使用此token
值。
请求 URL¶
项目 | 值 |
---|---|
URL | {gameServerUrl}/items/callback |
HTTP 方法 | POST |
内容类型 | application/json |
头部参数¶
字段名称 | 描述 | 类型 | 必需 |
---|---|---|---|
Authorization | 在NFT发行页面链接创建API的gameServerUrl 中作为token 查询参数发送的身份验证令牌。以Bearer ${token}的形式调用。 | Bearer | N |
User-Agent | HiveBlockchain/1.0 | string | Y |
请求体¶
字段名称 | 描述 | 类型 | 必需 |
---|---|---|---|
type | MINT | 字符串 | 是 |
itemId | NFT 项目识别码 | 字符串 | 是 |
playerId | 玩家 ID | 数字 | 是 |
characterId | 角色 ID | 字符串 | 否 |
webLinkId | 网页链接 ID (UUID) | 字符串 | 是 |
tokenId | NFT ID (成功时包含) | 字符串 | 否 |
status | 交易结果 (成功,失败) | 字符串 | 是 |
attributes | 每个代币应用的附加元数据属性 (例如,唯一项目代码、力量、敏捷等 NFT 中包含的属性) | json 数组 | 否 |
attributes.traitType | 组成属性的项目名称 | 字符串 | 否 |
attributes.value | 属性值 | 字符串 | 否 |
请求示例¶
curl -X 'POST' \
'https://api.com2us.com/hive/items/callback' \
-H 'accept: */*' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyb2xlIjoieHBsYS13ZWJ2aWV3IiwiYXBwIjoiY29tLmdjcC5zdGVwYnlzdGVwLnBjd2ViLmJs...' \ // 인증 토크 사용 시
-H 'User-Agent: HiveBlockchain/1.0' \
-d '{
"type": "MINT",
"itemId": "HIVE",
"playerId": 2319123897,
"characterId": "zeratu",
"webLinkId": "b6d2ca1b-b43a-4129-bf54-9a189e3aa664",
"tokenId": "HIVE#348",
"status": "success",
"attributes": [ // NFT 발행 페이지 링크 생성 시 attributes
{
"traitType": "item_id",
"value": "sward-3283272101239"
},
{
"traitType": "strength",
"value": "50"
},
{
"traitType": "agility",
"value": "10"
}
]
}'
响应¶
HTTP状态码如下。
- 成功
- 200
- 失败
- 4xx: 错误状态码,表示错误请求
- 5xx: 错误状态码,表示服务器错误