跳转至

铸造

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发行页面是一个网页,用户可以将他们拥有的物品转换为NFT。此网页由Hive区块链服务器提供。游戏服务器调用链接生成API以获取此网页URL(webLinkUrl)。当用户访问此网页时,他们可以在区块链上铸造游戏内物品为NFT。

注意事项

以下是开发人员在进行 API 调用时的注意事项。

游戏服务器网址

gameServerUrl 用作 Hive 区块链服务器调用游戏服务器的 请求 URL物品验证 API结果检查 API)。

游戏服务器网址和令牌

当 Hive 区块链服务器调用 项目验证 API结果检查 API 时,游戏服务器可以使用 身份验证令牌(头部参数) 进行 API 调用,这对开发者来说是可选的。如果游戏服务器选择在 API 调用中使用身份验证令牌,则必须在调用 NFT 发行页面链接生成 API 时,将此身份验证令牌作为 token(查询参数)预先发送到 Hive 区块链服务器。下面是一个示例。

"gameServerUrl": "https://api.com2us.com/hive?token=sInR5cCI6IkpXVC..."

属性

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: 错误状态码,表示服务器错误