銷毀
燒毀是一項功能，允許用戶燒毀已發行的NFT並將其轉換為可以在遊戲中使用的物品。用戶將NFT轉換為物品的過程大致如下。
- 使用者在 NFT 查看頁面檢查他們擁有的 NFT。
- 使用者選擇已勾選的 NFT，並將其轉換為可在遊戲中重用的物品（= NFT 燒毀）。
燒錄功能的實作流程¶
以下是燒錄功能的實作過程。要實作燒錄功能，請遵循下面的流程圖圖片和指導內容，在遊戲客戶端 (Hive SDK，遊戲客戶端) 和遊戲伺服器區域中實作代碼。下面圖片中標有藍色星號的部分是開發者需要工作的區域。欲了解主要任務的更多詳細資訊，請參考下面的指導。
Note
首先，您需要在实现烧录功能之前完成准备工作。
Note
要实现烧录功能，您需要使用Hive SDK。
在 hive SDK 中實現登錄¶
在遊戲客戶端實現代碼，以允許用戶使用IdP 登錄和 Hive SDK 認證功能登錄。還支持網頁登錄作為登錄方式。
實現 NFT 查詢按鈕¶
實現一個用戶界面，允許用戶在遊戲客戶端中打開他們的 NFT 列表。例如，在用戶角色的庫存中實現一個 查看擁有的 NFT 列表 按鈕。當按下此按鈕時，您需要實現它，以便打開 NFT 查看頁面，遵循以下內容。
NFT 查詢請求¶
實現從遊戲客戶端向遊戲伺服器請求用戶的NFT的代碼。這是為了實現用戶選擇NFT查詢按鈕時的操作。當遊戲伺服器收到遊戲客戶端的請求時，它會調用NFT查詢頁面鏈接創建API來顯示用戶的NFT列表。
NFT 查詢頁面連結生成 API 呼叫¶
NFT查詢頁面是一個用戶可以查看他們擁有的NFT列表的網頁。此網頁由Hive區塊鏈伺服器提供。遊戲伺服器調用鏈接生成API以獲取此網頁URL（webLinkUrl）。當用戶訪問此網頁時，他們可以查看自己擁有的NFT列表並在區塊鏈上燒毀特定的NFT。
註解¶
這些是開發人員在進行 API 呼叫時應採取的預防措施。
遊戲伺服器網址¶
gameServerUrl 被用作 Hive 區塊鏈伺服器調用遊戲伺服器的 請求 URL（項目驗證 API 和 結果檢查 API）。
遊戲伺服器網址和令牌¶
當 Hive 區塊鏈伺服器呼叫 項目驗證 API 或 結果檢查 API 時，遊戲伺服器可以使用身份驗證令牌 (標頭參數)進行 API 呼叫，這對開發者來說是可選的。如果要在 API 呼叫中使用身份驗證令牌，則遊戲伺服器必須在呼叫 NFT 查詢頁面鏈接生成 API 時，將此身份驗證令牌作為 token (查詢參數) 附加到 gameServerUrl，發送到 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 呼叫的驗證令牌 | 字串 | 是 |
請求主體¶
| 字段名稱 | 描述 | 類型 | 必需 |
|---|---|---|---|
| 類型 | HOME | 字串 | 是 |
| 玩家ID | 玩家ID | 數字 | 是 |
| 角色ID | 角色ID | 字串 | 是 |
| 遊戲伺服器網址 | 接收項目驗證和功能執行後成功/失敗結果的地址。通過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" // When sending authentication token: "gameServerUrl": "https://api.com2us.com/hive?token=sInR5cCI6IkpXVC..."
}'
回應¶
| 字段名称 | 描述 | 类型 |
|---|---|---|
| code | API 调用结果代码，0：成功 | 数字 |
| message | 结果消息 | 字符串 |
| data | API 响应数据 | json |
| data.webLinkId | 网页链接 ID (UUID) | 字符串 |
| data.webLinkUrl | 生成的一次性网页链接 (URL) | 字符串 |
| data.expiration | 网页链接过期日期 (ISO 8601) | 字符串 |
回應範例¶
{
"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 後選擇特定的錢包地址以執行 Mint 或 Burn。
| X-PLANET | XPLA Vault | XPLA Games |
|---|---|---|
 |  |  |
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 |
| 端口 | 80, 443 |
| 內容類型 | application/json |
標頭參數¶
| 欄位名稱 | 描述 | 類型 | 必填 |
|---|---|---|---|
| 授權 | 作為 gameServerUrl 中的 token 查詢參數發送的身份驗證令牌。以 Bearer ${token} 的形式調用。 | Bearer | 否 |
| 用戶代理 | HiveBlockchain/1.0 | 字串 | 是 |
請求主體¶
| 欄位名稱 | 描述 | 類型 | 必需 |
|---|---|---|---|
| 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": [ // When generating NFT query page link
{
"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。因此，遊戲伺服器必須按照 Hive 區塊鏈伺服器所需的形式配置 API 端點。
當 Hive 區塊鏈伺服器將 NFT 燒毀結果發送到遊戲伺服器的請求主體時，遊戲伺服器會在遊戲中生成物品，然後通過 API 將結果發送回 Hive 區塊鏈伺服器。
遊戲伺服器根據焚燒結果將執行的任務如下。
- NFT 燒毀成功
- 處理以使用遊戲中的物品（例如，創建遊戲用戶的庫存物品）
- NFT 燒毀失敗
- 遊戲中不需要單獨處理
- 如果用戶取消 NFT 燒毀或超過某個時間限制，則發送 NFT 燒毀失敗結果
以下是當Hive區塊鏈伺服器成功傳達NFT燒毀時的NFT燒毀頁面螢幕示例。
註解¶
以下是開發人員在配置 API 端點時的一些考量。
屬性¶
當呼叫NFT發行頁面鏈接創建API時，請求的attributes會包含在結果確認API請求主體中。如果attributes中包含唯一代碼，則可以使用該唯一代碼更新項目狀態。
授權標頭¶
如果在從NFT查詢頁面鏈接創建API請求的gameServerUrl中存在token查詢參數，請以Bearer形式使用此token值。
請求網址¶
| 項目 | 值 |
|---|---|
| URL | {gameServerUrl}/items/callback |
| HTTP 方法 | POST |
| 端口 | 80, 443 |
| 內容類型 | application/json |
標頭參數¶
| 欄位名稱 | 描述 | 類型 | 必填 |
|---|---|---|---|
| 授權 | 在 NFT 查詢頁面鏈接創建 API 的 gameServerUrl 中作為 token 查詢參數發送的身份驗證令牌。以 Bearer ${token} 的形式調用。 | Bearer | N |
| 用戶代理 | 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": [ // Attributes when generating NFT query page link
{
"traitType": "item_id",
"value": "sward-3283272101239"
},
{
"traitType": "strength",
"value": "50"
},
{
"traitType": "agility",
"value": "10"
}
]
}'
回應¶
HTTP 狀態碼如下。
- 成功
- 200
- 失敗
- 4xx: 錯誤請求的錯誤狀態碼
- 5xx: 伺服器錯誤的錯誤狀態碼