鑄造
鑄造是一個將遊戲物品發行為 NFT 的功能。在 Hive 控制台中，它根據 區塊鏈 > XPLA > NFT 菜單下的用戶發行標籤中的 配置詳細信息 發行 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 |
標頭參數¶
| 欄位名稱 | 描述 | 類型 | 必填 |
|---|---|---|---|
| 授權 | API 調用的身份驗證令牌 | 字串 | 是 |
請求主體¶
| 欄位名稱 | 描述 | 類型 | 必填 |
|---|---|---|---|
| 類型 | MINT | 字串 | 是 |
| 玩家ID | 玩家ID | 數字 | 是 |
| 角色ID | 角色ID | 字串 | 是 |
| 遊戲伺服器網址 | 接收項目驗證和功能執行後成功/失敗結果的地址。將身份驗證令牌作為token查詢參數發送，用於項目驗證/結果確認API標頭 | 字串 | 是 |
| 數據 | 根據類型的請求參數信息 | json | 否 |
資料物件¶
| 欄位名稱 | 描述 | 類型 | 必需 |
|---|---|---|---|
| itemId | 用戶 NFT 模板識別碼（控制台註冊） | 字串 | Y |
| attributes | 每個代幣應用的附加元數據屬性（例如，唯一項目代碼、力量、敏捷等屬性，將包含在 NFT 中） | json 陣列 | N |
| attributes.traitType | 組成屬性的項目名稱 | 字串 | N |
| attributes.value | 特徵值 | 字串 | N |
請求範例¶
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: 成功 | 數字 |
| 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。
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 查詢參數，請以 Bearer 格式使用此 token 值。
屬性¶
在生成 NFT 發行頁面鏈接的 API 請求主體中包含 attributes。
請求 URL¶
以下是需要在遊戲伺服器上準備的API端點資訊。
| 項目 | 值 |
|---|---|
| URL | {gameServerUrl}/items/validate |
| HTTP 方法 | POST |
| 內容類型 | application/json |
標頭參數¶
| 字段名稱 | 描述 | 類型 | 必需 |
|---|---|---|---|
| 授權 | 作為 gameServerUrl 的 token 查詢參數發送的身份驗證令牌。它以 Bearer ${token} 的形式調用。 | Bearer | N |
| 用戶代理 | 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...' \ // 인증 토크 사용 시
-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查詢參數，則使用此token值作為Bearer形式。
請求 URL¶
| 項目 | 值 |
|---|---|
| URL | {gameServerUrl}/items/callback |
| HTTP 方法 | POST |
| 內容類型 | application/json |
標頭參數¶
| 欄位名稱 | 描述 | 類型 | 必填 |
|---|---|---|---|
| 授權 | 在 NFT 發行頁面鏈接創建 API 的 gameServerUrl 中作為 token 查詢參數發送的身份驗證令牌。以 Bearer ${token} 的形式調用。 | Bearer | 否 |
| 用戶代理 | HiveBlockchain/1.0 | 字串 | 是 |
請求主體¶
| 字段名称 | 描述 | 类型 | 是否必需 |
|---|---|---|---|
| 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: 伺服器錯誤的錯誤狀態碼