铸造

Mint是一个将游戏物品作为NFT发行的功能。它根据用户发行选项卡中的[i]配置内容[/i]在Hive控制台的区块链 > XPLA > NFT菜单中发行NFT。

铸造函数的实现流程¶

以下是Mint功能的实现过程。要实现Mint功能，请按照下面的流程图和指导内容在游戏客户端（Hive SDK，游戏客户端）和游戏服务器区域中实现代码。下面图像中标有蓝色星号的部分是开发人员需要工作的区域。有关主要任务的更多详细信息，请参阅下面的指南。

Note

完成准备后，您需要实现Mint功能。

Note

要实现Mint功能，您必须使用Hive SDK。

在 hive SDK 中实现登录¶

在游戏客户端中实现代码，以允许用户使用 IdP 登录和 Hive SDK 认证功能登录。 Web 登录也支持作为登录方式。

NFT铸造按钮实现¶

在游戏客户端中实现一个用户界面，允许用户打开NFT发行页面。例如，当用户在访问游戏后从角色库存中选择一个物品时，应该出现一个将物品转换为NFT按钮。当按下此按钮时，应根据以下内容打开NFT发行页面。

请求将物品转换为 NFT¶

实现从游戏客户端向游戏服务器请求将用户游戏物品作为NFT发行的代码。这是为了实现用户选择NFT发行按钮时的操作。当游戏服务器收到来自游戏客户端的请求时，它会检查要作为NFT发行的游戏物品，然后调用NFT发行页面链接创建API将物品作为NFT发行。

NFT 发行页面链接生成 API 调用¶

NFT发行页面是一个允许用户将他们拥有的物品转换为NFT的网页。该网页由Hive区块链服务器提供。游戏服务器调用链接生成API以检索此网页的URL（webLinkUrl）。当用户访问此网页时，他们可以在区块链上铸造游戏内物品为NFT。

注意事项¶

开发人员在进行 API 调用时应采取的预防措施。

游戏服务器网址¶

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

游戏服务器网址和令牌¶

当 Hive 区块链服务器调用物品验证 API 或结果确认 API 时，游戏服务器可以选择性地使用 身份验证令牌（头部参数） 进行 API 调用，这由开发者自行决定。如果要在 API 调用中使用身份验证令牌，游戏服务器必须在调用 NFT 发行页面链接生成 API 时，将此身份验证令牌预先附加为 token（查询参数）到 gameServerUrl 并发送给 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 调用的身份验证令牌	字符串	Y

请求体¶

字段名称	描述	类型	必需
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" // When sending authentication token: "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后执行铸造或销毁。

X-PLANET	XPLA Vault	XPLA Games

NFT 铸造 (执行铸造)¶

在NFT发行页面，用户选择一个项目，然后执行铸造。

在NFT发行前检查费用

项目验证 API 调用 (蜂巢区块链服务器 → 游戏服务器)¶

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查询参数，请以Bearer形式使用此token值。

属性¶

在生成NFT发行页面链接的API请求体中包含attributes。

请求 URL¶

这是需要在游戏服务器上准备的API端点信息。

项目	值
URL	{gameServerUrl}/items/validate
HTTP 方法	POST
端口	80, 443
内容类型	application/json

头部参数¶

字段名称	描述	类型	必需
Authorization	作为 `token` 查询参数发送到 NFT 发行页面 API 的 `gameServerUrl` 的身份验证令牌。格式为 Bearer ${token}。	Bearer	N
User-Agent	HiveBlockchain/1.0	字符串	Y

请求体¶

字段名称	描述	类型	必需
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...' \ // When using authentication token
  -H 'User-Agent: HiveBlockchain/1.0' \
  -d '{
    "type": "MINT",
    "itemId": "HIVE",
    "playerId": 2319123897,
    "characterId": "zeratu",
    "webLinkId": "b6d2ca1b-b43a-4129-bf54-9a189e3aa664",
    "attributes": [ // Attributes when generating NFT issuance page link
        {
          "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
端口	80, 443
内容类型	application/json

头部参数¶

字段名称	描述	类型	是否必需
Authorization	作为 `token` 查询参数发送的身份验证令牌，在NFT发行页面链接创建API的 `gameServerUrl` 中使用。以 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...' \  // When using authentication token
  -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": [ // Attributes when generating NFT issuance page link
        {
          "traitType": "item_id",
          "value": "sward-3283272101239"
        },
        {
          "traitType": "strength",
          "value": "50"
        },
        {
          "traitType": "agility",
          "value": "10"
        }
      ]
  }'

响应¶

HTTP 状态码如下。

成功
- 200
失败
- 4xx: 错误状态码，表示错误请求
- 5xx: 错误状态码，表示服务器错误