鑄造
Mint是一個將遊戲物品發行為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發行的遊戲物品，然後調用NFT發行頁面鏈接創建API來將物品發行為NFT。
NFT 發行頁面連結生成 API 呼叫¶
NFT 發行頁面是一個允許用戶將其擁有的物品轉換為 NFT 的網頁。此網頁由 Hive 區塊鏈伺服器提供。遊戲伺服器調用鏈接生成 API 以檢索此網頁 URL (webLinkUrl)。當用戶訪問此網頁時，他們可以在區塊鏈上鑄造遊戲內物品為 NFT。
註解¶
這些是開發者在進行 API 呼叫時應該採取的預防措施。
遊戲伺服器網址¶
gameServerUrl 被用作 Hive 區塊鏈伺服器調用遊戲伺服器的 請求 URL（項目驗證 API 和 結果檢查 API）。
遊戲伺服器網址和令牌¶
當 Hive 區塊鏈伺服器呼叫 項目驗證 API 或 結果確認 API 時，遊戲伺服器可以選擇性地使用身份驗證令牌 (標頭參數)進行 API 呼叫，這由開發者自行決定。如果要在 API 呼叫中使用身份驗證令牌，則遊戲伺服器必須在呼叫 NFT 發行頁面鏈接生成 API 時，將此身份驗證令牌預先附加為 token (查詢參數) 到 gameServerUrl，並將其發送到 Hive 區塊鏈伺服器。以下是示例。
屬性¶
attributes 用作请求体，当 Hive 区块链服务器调用 项目验证 API 和 结果确认 API 到游戏服务器时。
當您使用attributes中的項目唯一代碼調用API時，唯一代碼也可以包含在結果檢查API的請求主體attributes中。在這種情況下，您可以使用相應的唯一代碼更新項目狀態。
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 | 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：成功 | 数字 |
| 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發行前檢查費用 |
|---|
 |
項目驗證 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 |
| 端口 | 80, 443 |
| 內容類型 | application/json |
標頭參數¶
| 欄位名稱 | 描述 | 類型 | 是否必填 |
|---|---|---|---|
| 授權 | 作為 token 查詢參數發送到 NFT 發行頁面 API 的 gameServerUrl 的身份驗證令牌。格式為 Bearer ${token}。 | Bearer | N |
| 用戶代理 | HiveBlockchain/1.0 | 字串 | Y |
請求主體¶
| 欄位名稱 | 描述 | 類型 | 是否必填 |
|---|---|---|---|
| type | MINT | 字串 | Y |
| itemId | NFT 物品識別碼 | 字串 | Y |
| playerId | 玩家 ID | 數字 | Y |
| characterId | 角色 ID | 字串 | N |
| webLinkId | 網頁連結 ID (UUID) | 字串 | Y |
| tokenId | NFT ID | 字串 | N |
| attributes | 每個代幣應用的附加元數據屬性 (例如，唯一物品代碼、力量、敏捷等屬性包含在 NFT 中) | json 陣列 | N |
| attributes.traitType | 構成屬性的物品名稱 | 字串 | N |
| attributes.value | 特徵值 | 字串 | N |
請求範例¶
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 |
標頭參數¶
| 欄位名稱 | 描述 | 類型 | 必填 |
|---|---|---|---|
| 授權 | 在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...' \ // 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: 伺服器錯誤的錯誤狀態碼