销毁
Burn是一个允许用户销毁已发行NFT并将其转换为可在游戏中使用的物品的功能。用户将NFT转换为物品的过程大致如下。
- 用户在NFT查看页面检查他们拥有的NFT。
- 用户选择已检查的NFT并将其转换为游戏中可重用的物品（= NFT销毁）。
烧录函数的实现流程¶
以下是Burn功能的实现过程。要实现Burn功能，请按照流程图图像和指南内容在游戏客户端（Hive SDK，游戏客户端）和游戏服务器区域中实现代码。下图中标有蓝色星号的部分是开发者需要工作的区域。有关主要任务的更多详细信息，请参阅下面的指南。
Note
首先，您需要在实现 Burn 功能之前完成 准备。
Note
要实现 Burn 功能，您需要使用 Hive SDK。
在 hive SDK 中实现登录¶
在游戏客户端中实现代码，以允许用户使用IdP 登录通过 Hive SDK 认证功能登录。也支持网页登录作为登录方式。
实现 NFT 查询按钮¶
实现一个用户界面，允许用户在游戏客户端中打开他们的NFT列表。例如，在用户角色的库存中实现一个查看拥有的NFT列表按钮。当按下这个按钮时，您需要根据下面的内容实现NFT查看页面的打开。
NFT 查询请求¶
实现请求用户的NFTs从游戏客户端到游戏服务器的代码。这是为了实现用户选择NFT查询按钮时的操作。当游戏服务器收到游戏客户端请求时，它调用NFT查询页面链接创建API来显示用户的NFT列表。
NFT 查询页面链接生成 API 调用¶
NFT查看页面是一个网页，用户可以在其中查看他们拥有的NFT列表。该网页由Hive区块链服务器提供。游戏服务器调用链接生成API以获取此网页的URL（webLinkUrl）。当用户访问此网页时，他们可以查看自己拥有的NFT列表，并在区块链上销毁（删除）特定的NFT。
注意事项¶
以下是开发人员在进行 API 调用时的注意事项。
游戏服务器网址¶
gameServerUrl 用作 Hive 区块链服务器调用游戏服务器的 请求 URL，用于 API（物品验证 API 和 结果检查 API）。
游戏服务器网址和令牌¶
当Hive区块链服务器调用物品验证API或结果检查API时，游戏服务器可以使用身份验证令牌（请求头参数）进行API调用，这对开发者来说是可选的。如果要在API调用中使用身份验证令牌，游戏服务器必须将此身份验证令牌作为token（查询参数）附加到gameServerUrl，并在调用NFT查找页面链接生成API时提前将其发送到Hive区块链服务器。下面是一个示例。
NFT 查询页面链接有效期¶
一次创建的页面链接仅在10分钟内有效，基于第一次访问的会话。
请求 URL¶
| 项目 | 值 |
|---|---|
| 直播 URL | https://bc-platform-api.withhive.com/web3/v1/web-link |
| 沙盒 URL | https://sandbox-bc-platform-api.withhive.com/web3/v1/web-link |
| HTTP 方法 | POST |
| 内容类型 | application/json |
头部参数¶
| 字段名称 | 描述 | 类型 | 必需 |
|---|---|---|---|
| 授权 | API 调用的身份验证令牌 | 字符串 | 是 |
请求体¶
| 字段名称 | 描述 | 类型 | 必需 |
|---|---|---|---|
| type | HOME | 字符串 | 是 |
| playerId | 玩家ID | 数字 | 是 |
| characterId | 角色ID | 字符串 | 是 |
| gameServerUrl | 接收物品验证和功能执行后成功/失败结果的地址。将身份验证令牌作为token查询参数发送到物品验证/结果确认API头部 | 字符串 | 是 |
请求示例¶
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": "HOME",
"playerId": 1276814678,
"characterId": "zeratu",
"gameServerUrl": "https://api.com2us.com/hive" //인증 토큰 전송 시: "gameServerUrl": "https://api.com2us.com/hive?token=sInR5cCI6IkpXVC..."
}'
响应¶
| 字段名称 | 描述 | 类型 |
|---|---|---|
| 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，然后执行销毁。
| 从列表中选择要销毁的NFT | 检查费用 |
|---|---|
 |  |
项目验证 API 调用 (hive 区块链服务器 → 游戏服务器)¶
Note
此 API 不是游戏服务器调用 Hive 区块链服务器的 API，而是 Hive 区块链服务器调用游戏服务器的 API。因此，游戏服务器必须以 Hive 区块链服务器所需的形式配置 API 端点。
Hive 区块链服务器请求游戏服务器验证物品，以检查用户拥有的 NFT 是否为游戏中的可用物品。
Hive 区块链服务器通过游戏服务器传递的响应值验证物品在游戏中是否可用。一旦验证完成，Hive 区块链服务器将在区块链上销毁 NFT。如果 物品验证失败，Hive 区块链服务器将不会销毁 NFT。
注意事项¶
以下是开发人员在配置 API 端点时的一些考虑事项。
游戏服务器网址¶
此 API 使用从 NFT 查找页面链接创建 API 请求的 gameServerUrl 向游戏服务器请求验证。
授权头部¶
如果在从NFT查询页面链接创建API请求的gameServerUrl中存在token查询参数，请使用此token值以Bearer格式。
属性¶
当调用NFT发行页面链接创建API时，请求的attributes将包含在项目验证API请求体中。
请求 URL¶
以下是需要在游戏服务器上准备的API端点信息。
| 项目 | 值 |
|---|---|
| URL | {gameServerUrl}/items/validate |
| HTTP 方法 | POST |
| 内容类型 | application/json |
头部参数¶
| 字段名称 | 描述 | 类型 | 必需 |
|---|---|---|---|
| Authorization | 作为 token 查询参数发送到 NFT 查询页面 API 的 gameServerUrl 的身份验证令牌。格式为 Bearer ${token}。 | Bearer | N |
| User-Agent | HiveBlockchain/1.0 | 字符串 | Y |
请求体¶
| 字段名称 | 描述 | 类型 | 是否必需 |
|---|---|---|---|
| type | BURN | 字符串 | 是 |
| 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": "BURN",
"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"
}
],
"tokenId": "HIVE#01"
}'
响应¶
HTTP 状态码如下。
- 成功
- 200
- 失败
- 4xx: 错误状态码，表示错误的请求
- 5xx: 错误状态码，表示服务器错误
结果检查 API 调用 (hive 区块链 → 游戏服务器)¶
Note
此API并不是游戏服务器调用Hive区块链服务器的API，而是Hive区块链服务器调用游戏服务器的API。因此，游戏服务器必须配置API端点，以Hive区块链服务器所需的形式提供它。
当Hive区块链服务器将NFT销毁结果作为请求体传递给游戏服务器时，游戏服务器在游戏中生成物品，然后通过API将结果发送回Hive区块链服务器。
游戏服务器将根据焚烧结果采取的行动如下。
- NFT销毁成功
- 处理以使用游戏中的物品（例如，在游戏用户的库存中创建物品）
- NFT销毁失败
- 游戏中不需要单独处理
- 如果用户取消NFT销毁或时间超过某个限制，则发送NFT销毁失败结果
以下是Hive区块链服务器成功通信NFT销毁时的NFT销毁页面屏幕示例。
注意事项¶
以下是开发人员在配置 API 端点时的一些考虑事项。
属性¶
在调用NFT发行页面链接创建API时请求的attributes包含在结果确认API请求体中。如果唯一代码包含在attributes中，则可以使用该唯一代码更新项目状态。
授权头部¶
如果在从NFT查询页面链接创建API请求的gameServerUrl中存在token查询参数，请使用此token值以Bearer格式。
请求 URL¶
| 项目 | 值 |
|---|---|
| URL | {gameServerUrl}/items/callback |
| HTTP 方法 | POST |
| 内容类型 | application/json |
头部参数¶
| 字段名称 | 描述 | 类型 | 必需 |
|---|---|---|---|
| Authorization | 作为 gameServerUrl 的 token 查询参数发送的身份验证令牌，用于 NFT 查询页面链接创建 API。以 Bearer ${token} 形式调用。 | Bearer | N |
| User-Agent | HiveBlockchain/1.0 | 字符串 | Y |
请求体¶
| 字段名称 | 描述 | 类型 | 必需 |
|---|---|---|---|
| type | BURN | 字符串 | 是 |
| 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": "BURN",
"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: 错误状态码，表示服务器错误