ข้ามไปที่เนื้อหา

เบิร์น

การเผาเป็นฟีเจอร์ที่อนุญาตให้ผู้ใช้เผา NFT ที่ออกแล้วและแปลงเป็นไอเทมที่สามารถใช้ในเกมได้ กระบวนการสำหรับผู้ใช้ในการแปลง NFT เป็นไอเทมโดยทั่วไปมีดังนี้

  1. ผู้ใช้ตรวจสอบ NFT ที่พวกเขาเป็นเจ้าของในหน้าแสดง NFT.
  2. ผู้ใช้เลือก NFT ที่ตรวจสอบแล้วและแปลงเป็นไอเทมเพื่อใช้ซ้ำในเกม (= การเผา NFT).

กระบวนการดำเนินการของฟังก์ชันการเผาไหม้

ด้านล่างนี้คือกระบวนการในการดำเนินการสำหรับฟีเจอร์การเผา (Burn feature) เพื่อดำเนินการฟีเจอร์การเผา กรุณาปฏิบัติตามภาพไดอะแกรมและเนื้อหาคู่มือด้านล่างเพื่อดำเนินการโค้ดใน เกมไคลเอนต์ (Hive SDK, เกมไคลเอนต์) และพื้นที่เซิร์ฟเวอร์เกม ส่วนที่มี ดอกจันสีน้ำเงิน ในภาพด้านล่างคือพื้นที่ที่นักพัฒนาต้องทำงาน สำหรับรายละเอียดเพิ่มเติมเกี่ยวกับงานหลัก กรุณาอ้างอิงจากคู่มือด้านล่าง

Note

ก่อนอื่นคุณต้องทำการ เตรียมการ ให้เสร็จก่อนที่จะดำเนินการฟีเจอร์ Burn

Note

เพื่อที่จะดำเนินการฟีเจอร์ Burn คุณต้องใช้ Hive SDK.

การนำเข้าฟังก์ชันล็อกอินใน SDK ของ hive

ดำเนินการเขียนโค้ดในไคลเอนต์เกมเพื่ออนุญาตให้ผู้ใช้เข้าสู่ระบบโดยใช้ IdP login ด้วยฟีเจอร์การตรวจสอบสิทธิ์ SDK Hive นอกจากนี้ยังรองรับ Web login เป็นวิธีการเข้าสู่ระบบอีกด้วย

การนำปุ่มค้นหา NFT ไปใช้

สร้าง UI ที่อนุญาตให้ผู้ใช้เปิดรายการ NFT ของพวกเขาในไคลเอนต์เกม ตัวอย่างเช่น สร้างปุ่ม ดูรายการ NFT ที่เป็นเจ้าของ ในคลังของตัวละครผู้ใช้ เมื่อกดปุ่มนี้ คุณต้องทำให้มันเปิดหน้าแสดง NFT ตามเนื้อหาด้านล่าง

คำขอสอบถาม NFT

การดำเนินการโค้ดที่ร้องขอ NFT ของผู้ใช้จากไคลเอนต์เกมไปยังเซิร์ฟเวอร์เกม นี่คือการดำเนินการเมื่อผู้ใช้เลือก ปุ่มค้นหา NFT เมื่อเซิร์ฟเวอร์เกมได้รับคำขอจากไคลเอนต์เกม มันจะเรียกใช้ API การสร้างลิงก์หน้า NFT เพื่อแสดงรายการ NFT ของผู้ใช้

หน้าเว็บการค้นหา NFT เป็นหน้าเว็บที่ผู้ใช้สามารถดูรายการ NFT ที่พวกเขาเป็นเจ้าของ หน้าเว็บนี้จัดทำโดยเซิร์ฟเวอร์บล็อกเชน Hive เซิร์ฟเวอร์เกมเรียก API การสร้างลิงก์เพื่อรับ URL ของหน้าเว็บนี้ (webLinkUrl) เมื่อผู้ใช้เข้าถึงหน้าเว็บนี้ พวกเขาสามารถดูรายการ NFT ที่พวกเขาเป็นเจ้าของและเผา NFT เฉพาะบนบล็อกเชนได้

หมายเหตุ

นี่คือข้อควรระวังที่นักพัฒนาควรปฏิบัติเมื่อทำการเรียก API

เกมเซิร์ฟเวอร์ URL

gameServerUrl ถูกใช้เป็น Request URL สำหรับ API ที่เซิร์ฟเวอร์บล็อกเชน Hive เรียกไปยังเซิร์ฟเวอร์เกม (Item Validation API และ Result Check API).

URL เกมเซิร์ฟเวอร์และโทเค็น

เมื่อเซิร์ฟเวอร์บล็อกเชน Hive เรียกใช้ API การตรวจสอบรายการ หรือ API ตรวจสอบผลลัพธ์ เซิร์ฟเวอร์เกมสามารถใช้ โทเค็นการตรวจสอบสิทธิ์ (Header Parameters) สำหรับการเรียก API ซึ่งเป็นทางเลือกสำหรับนักพัฒนา หากต้องการใช้โทเค็นการตรวจสอบสิทธิ์สำหรับการเรียก API เซิร์ฟเวอร์เกมจะต้องส่งโทเค็นการตรวจสอบสิทธิ์นี้ล่วงหน้าเป็น token (Query Parameter) ที่แนบมากับ gameServerUrl เมื่อเรียกใช้ API การสร้างลิงก์การค้นหา NFT ไปยังเซิร์ฟเวอร์บล็อกเชน Hive ตัวอย่างแสดงด้านล่าง

"gameServerUrl": "https://api.com2us.com/hive?token=sInR5cCI6IkpXVC..."

ระยะเวลาความถูกต้องของลิงก์หน้าแสดง 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

พารามิเตอร์หัวข้อ

ชื่อฟิลด์ คำอธิบาย ประเภท จำเป็น
Authorization โทเค็นการตรวจสอบสิทธิ์สำหรับการเรียก API สตริง ใช่

เนื้อหาคำขอ

ชื่อฟิลด์ คำอธิบาย ประเภท จำเป็น
type HOME string ใช่
playerId รหัสผู้เล่น number ใช่
characterId รหัสตัวละคร string ใช่
gameServerUrl ที่อยู่เพื่อรับผลลัพธ์ความสำเร็จ/ความล้มเหลวหลังจากการตรวจสอบรายการและการดำเนินการฟังก์ชัน ส่งโทเค็นการตรวจสอบสิทธิ์ผ่านพารามิเตอร์การค้นหา token สำหรับการตรวจสอบรายการ/การยืนยันผลลัพธ์ API header string ใช่

ตัวอย่างคำขอ

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 รหัสลิงก์เว็บ (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"
  }
}

การสร้างหน้าแสดง NFT ด้วย hive SDK

API การสร้างลิงก์หน้าคิวรี NFT จะแสดง URL ของหน้าเว็บที่ได้รับเป็นการตอบกลับเพื่อเปิดในเบราว์เซอร์ในเกมโดยใช้ Hive SDK.


ด้านล่างนี้คือตัวอย่างของหน้าแสดง NFT.

รายการ NFT ที่เป็นเจ้าของ


เมื่อคุณเปิดหน้าคำถาม NFT หน้าต่างจะปรากฏขึ้นเพื่อเข้าสู่ระบบ กระเป๋าเงิน X-PLANET หรือ XLPA Vault. ผู้ใช้ต้องเลือกที่อยู่กระเป๋าเงินเฉพาะเพื่อทำการ Mint หรือ Burn หลังจากเข้าสู่ระบบกระเป๋าเงิน X-PLANET หรือ XLPA Vault.

X-PLANET XPLA Vault XPLA Games

การเผา NFT

ในหน้าการดู NFT ผู้ใช้เลือก NFT และจากนั้นดำเนินการเผา

เลือก NFT ที่จะเผาจากรายการ ตรวจสอบค่าธรรมเนียม

การตรวจสอบรายการ API call (เซิร์ฟเวอร์บล็อกเชนของ hive → เซิร์ฟเวอร์เกม)

Note

API นี้ไม่ใช่ API ที่เซิร์ฟเวอร์เกมเรียกเซิร์ฟเวอร์บล็อกเชน Hive แต่เป็น API ที่เซิร์ฟเวอร์บล็อกเชน Hive เรียกเซิร์ฟเวอร์เกม ดังนั้นเซิร์ฟเวอร์เกมจะต้องกำหนดค่า endpoint API ในรูปแบบที่เซิร์ฟเวอร์บล็อกเชน Hive ต้องการ

เซิร์ฟเวอร์บล็อกเชน Hive ขอการตรวจสอบรายการจากเซิร์ฟเวอร์เกมเพื่อตรวจสอบว่า NFTs ที่ผู้ใช้เป็นเจ้าของนั้นเป็นรายการที่สามารถใช้งานได้ในเกมหรือไม่

เซิร์ฟเวอร์บล็อกเชน Hive ตรวจสอบว่าสิ่งของสามารถใช้งานในเกมได้หรือไม่ผ่านค่าการตอบกลับที่ส่งโดยเซิร์ฟเวอร์เกม เมื่อการตรวจสอบเสร็จสิ้น เซิร์ฟเวอร์บล็อกเชน Hive จะทำการเผา NFT บนบล็อกเชน หาก การตรวจสอบสิ่งของล้มเหลว เซิร์ฟเวอร์บล็อกเชน Hive จะไม่ทำการเผา NFT

หมายเหตุ

นี่คือข้อพิจารณาสำหรับนักพัฒนาขณะกำหนดค่า API endpoints

เกมเซิร์ฟเวอร์ URL

API นี้ขอการตรวจสอบจากเซิร์ฟเวอร์เกมโดยใช้ gameServerUrl ที่ร้องขอจาก API สร้างลิงก์หน้า NFT

หัวข้อการอนุญาต

หากพารามิเตอร์การค้นหา token มีอยู่ใน gameServerUrl ที่ร้องขอจาก API การสร้างลิงก์หน้า NFT Query ให้ใช้ค่าของ token นี้ในรูปแบบ Bearer.

คุณสมบัติ

attributes ที่ร้องขอเมื่อเรียกใช้ API การสร้างลิงก์หน้า NFT issuance จะรวมอยู่ใน Request Body ของ API การตรวจสอบรายการ

URL การร้องขอ

ข้อมูลจุดสิ้นสุด API ต่อไปนี้คือข้อมูลที่ต้องเตรียมบนเซิร์ฟเวอร์เกม

รายการ ค่า
URL {gameServerUrl}/items/validate
HTTP Method POST
PORT 80, 443
Content-Type application/json

พารามิเตอร์หัวเรื่อง

ชื่อฟิลด์ คำอธิบาย ประเภท จำเป็น
Authorization โทเค็นการตรวจสอบสิทธิ์ที่ส่งเป็นพารามิเตอร์การค้นหา token ใน gameServerUrl ของ API หน้าค้นหา NFT. เรียกว่าในรูปแบบ Bearer ${token}. Bearer N
User-Agent HiveBlockchain/1.0 string Y

เนื้อหาคำขอ

ชื่อฟิลด์ คำอธิบาย ประเภท จำเป็น
type BURN string Y
itemId รหัสการระบุ NFT item string Y
playerId รหัสผู้เล่น number Y
characterId รหัสตัวละคร string N
webLinkId รหัสลิงก์เว็บ (UUID) string Y
tokenId รหัส NFT string Y
attributes คุณสมบัติเมตาดาต้าที่จะนำไปใช้เพิ่มเติมกับโทเค็น (เช่น รหัสเฉพาะ, ความแข็งแกร่ง, ความคล่องแคล่ว, ฯลฯ คุณสมบัติที่รวมอยู่ใน NFT) json array N
attributes.traitType ชื่อรายการที่ประกอบขึ้นเป็นคุณสมบัติ string N
attributes.value ค่าคุณสมบัติ string N

ตัวอย่างคำขอ

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 call (บล็อกเชน hive → เซิร์ฟเวอร์เกม)

Note

API นี้ไม่ใช่ API ที่เซิร์ฟเวอร์เกมเรียกเซิร์ฟเวอร์บล็อกเชน Hive แต่เป็น API ที่เซิร์ฟเวอร์บล็อกเชน Hive เรียกเซิร์ฟเวอร์เกม ดังนั้นเซิร์ฟเวอร์เกมจะต้องกำหนดค่า API endpoint ในรูปแบบที่เซิร์ฟเวอร์บล็อกเชน Hive ต้องการ

เมื่อเซิร์ฟเวอร์บล็อกเชน Hive ส่งผลการเผา NFT ใน Request Body ไปยังเซิร์ฟเวอร์เกม เซิร์ฟเวอร์เกมจะสร้างไอเท็มในเกมและจากนั้นส่งผลลัพธ์กลับไปยังเซิร์ฟเวอร์บล็อกเชน Hive ผ่าน API


งานที่เซิร์ฟเวอร์เกมจะดำเนินการตามผลการเผาไหม้มีดังนี้

  • การเผา NFT สำเร็จ
    • ประมวลผลเพื่อใช้ไอเทมในเกม (เช่น การสร้างไอเทมในคลังของผู้ใช้เกม)
  • การเผา NFT ล้มเหลว
    • ไม่ต้องการการประมวลผลแยกต่างหากในเกม
    • ส่งผลลัพธ์การเผา NFT ล้มเหลวหากผู้ใช้ยกเลิกการเผา NFT หรือหากเกินเวลาที่กำหนด


ด้านล่างคือตัวอย่างของหน้าจอหน้าเผา NFT เมื่อเซิร์ฟเวอร์บล็อกเชน Hive ส่งข้อมูลการเผา NFT สำเร็จ

หมายเหตุ

นี่คือข้อพิจารณาสำหรับนักพัฒนาขณะกำหนดค่า API endpoints.

คุณสมบัติ

เมื่อเรียกใช้ API การสร้างลิงก์หน้า NFT issuance attributes ที่ร้องขอจะถูกนำไปใช้ใน Request Body ของ API ยืนยันผล หากมีรหัสเฉพาะรวมอยู่ใน attributes สถานะของรายการสามารถอัปเดตด้วยรหัสเฉพาะนั้นได้

หัวข้อการอนุญาต

หากพารามิเตอร์การค้นหา token มีอยู่ใน gameServerUrl ที่ร้องขอจาก API การสร้างลิงก์หน้า NFT Query ให้ใช้ค่า token นี้ในรูปแบบ Bearer.

URL ที่ร้องขอ

รายการ ค่า
URL {gameServerUrl}/items/callback
HTTP Method POST
PORT 80, 443
Content-Type application/json

พารามิเตอร์หัวเรื่อง

ชื่อฟิลด์ คำอธิบาย ประเภท จำเป็น
Authorization โทเค็นการตรวจสอบสิทธิ์ที่ส่งเป็นพารามิเตอร์ token ใน gameServerUrl ของ API การสร้างลิงก์หน้า NFT query. เรียกในรูปแบบ Bearer ${token}. Bearer N
User-Agent HiveBlockchain/1.0 string Y

เนื้อหาคำขอ

ชื่อฟิลด์ คำอธิบาย ประเภท จำเป็น
type BURN string ใช่
itemId รหัสตัวระบุ NFT item string ใช่
playerId รหัสผู้เล่น number ใช่
characterId รหัสตัวละคร string ไม่
webLinkId รหัสลิงก์เว็บ (UUID) string ใช่
tokenId รหัส NFT (รวมถ้าสำเร็จ) string ไม่
status ผลลัพธ์การทำธุรกรรม (สำเร็จ, ล้มเหลว) string ใช่
attributes คุณสมบัติเพิ่มเติมที่ใช้ต่อแต่ละโทเคน (เช่น รหัสรายการที่ไม่ซ้ำ, ความแข็งแกร่ง, ความคล่องแคล่ว, ฯลฯ คุณสมบัติที่รวมอยู่ใน NFT) json array ไม่
attributes.traitType ชื่อของรายการที่ประกอบขึ้นเป็นคุณสมบัติ string ไม่
attributes.value ค่าคุณสมบัติ string ไม่

ตัวอย่างคำขอ

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: รหัสสถานะข้อผิดพลาดสำหรับข้อผิดพลาดของเซิร์ฟเวอร์