道具系統與平台付費商店

本系統為遊戲平台提供統一的付費道具管理解決方案，支援單機遊戲的道具購買、發放、統計等功能，實現道具購買、查詢、增減及進程觸發發放功能。

• 核心功能：道具購買、持有查詢、增減操作、變更監聽、遊戲進程觸發發放

1. 開發者後台管理功能

• 開發者可透過後台手動建立道具資料，支援上傳表格(道具單元表)與道具圖示。
• 付費的商城道具目前只支援手動建立。
• 支援建立最多 5000 條道具資料。
• 暫時只支援買斷制和內購類型的遊戲使用。
• 道具建立後需要經過審核，通過審核後，會預設進入啟用狀態。

道具管理功能：

‌道具ID‌：唯一標識，建立後不可修改
‌道具名稱與圖示‌：用於前端展示
‌道具圖示‌：支援手動更換Icon圖
‌道具建立規則：支援選擇遊戲道具、商城付費道具
道具限制：支援設定透過平台發放給玩家的限制，每日發放數量限制、總計數量限制或者不限制
‌道具庫存‌：可選擇輸入數量或不限制
道具價值設定：
免費道具(Platform activities)：支援到平台活動投放。
付費購買(Paid purchase)：支援道具商城付費購買。
預設美元計價
道具單元定價支援精確到0.0001美元
商城付費道具最小價值輸入1美元

建議

• 先錄入道具單元後，再手動錄入道具商城付費購買的道具，支援選擇1個或者多個道具組成一個集合商品進行銷售。
• 當道具設定為免費道具時，平台可能會根據營運計劃選擇投放給玩家，在玩家進入遊戲後會發放到玩家的遊戲角色。

2. 道具 SDK 接入

核心介面說明

介面名稱	方法簽名	功能描述
開啟購買視窗	openBuyGameItemsDialog(level: number)	透過遊戲內的功能 UI 喚起商城道具的購買彈窗
取得持有道具	getUserGameItems(): GameItem[]	進入遊戲時查詢玩家目前道具列表（含 ID 和數量）
增加道具	addGameItem(itemId: string, amount: number)	遊戲進程中發放道具（支援購買、關卡獎勵、任務完成等場景）
減少道具	subtractGameItem(itemId: string, amount: number)	消耗道具（遊戲進程中使用、消耗等場景，扣除後數量非負）
訂閱變更通知	subscribeGameItemChange(callback: (res: GameItemChange) => void)	商城付費道具支付完成回呼方法

關鍵資料格式

• ​**GameItem（道具資訊）**​：{ itemId: string, amount: number }
• ​**GameItemChange（變更資訊）**​：{ itemId: string, amount: number, changeType: 'add'|'subtract', total: number }

2.1 取得持有道具列表

// 取得玩家持有道具列表（遊戲初始化時呼叫）
const items = window.JOGOS_SDK.gameItem.getUserGameItems();
console.log('持有道具：', items);

2.2 開啟道具購買視窗

// 開啟道具購買視窗
window.JOGOS_SDK.gameItem.openBuyGameItemsDialog(10);

2.3 增加道具

// 增加道具（ID：3232addasdda3aa2，數量10）
window.JOGOS_SDK.gameItem.addGameItem('3232addasdda3aa2', 10);

2.4 減少道具

// 減少道具（ID：3232addasdda3aa2，數量5）
window.JOGOS_SDK.gameItem.subtractGameItem('3232addasdda3aa2', 5);

2.5 訂閱道具變更通知

// 訂閱道具變更通知
window.JOGOS_SDK.gameItem.subscribeGameItemChange((res) => {
  console.log('道具變更：', res);
});

2.6 付費道具購買全流程

// 1. 發起付費道具購買（商品ID：item_gold_100，對應100金幣道具）
async function buyGoldItem() {
  try {
    const orderNo = await window.JOGOS_SDK.payment.buyGoods('item_gold_100');
    console.log('訂單建立成功，訂單號：', orderNo);
  } catch (err) {
    console.error('訂單建立失敗：', err);
    alert('購買發起失敗，請稍後重試');
  }
}

// 2. 訂閱支付成功通知（遊戲初始化時呼叫）
window.JOGOS_SDK.payment.subscribeOrderPaid(async (order) => {
  console.log('支付成功，訂單詳情：', order);
  if (order.status === 'success') {
    // 3. 發放對應道具（商品ID：item_gold_100 對應道具ID：3232addasdda3aa2）
    window.JOGOS_SDK.gameItem.addGameItem('3232addasdda3aa2', 100);
    // 4. 通知平台發貨（必須呼叫，否則訂單狀態異常）
    await window.JOGOS_SDK.payment.deliverGoods(order.orderNo);
    alert('100金幣購買成功，已發放到背包！');
  }
});

// 3. 異常場景：查詢訂單詳情（如支付後未收到道具）
async function checkOrder(orderNo) {
  try {
    const order = await window.JOGOS_SDK.payment.getOrderDetail(orderNo);
    console.log('訂單詳情查詢：', order);
    if (order.status === 'success') {
      // 補發放道具
      window.JOGOS_SDK.gameItem.addGameItem('3232addasdda3aa2', 100);
      await window.JOGOS_SDK.payment.deliverGoods(orderNo);
    }
  } catch (err) {
    console.error('訂單查詢失敗：', err);
  }
}

2.7 遊戲進程觸發道具發放（範例：關卡通關獎勵）

// 關卡10通關觸發道具發放（含去重邏輯，避免重複領取）
function onLevel10Clear() {
  // 單機遊戲：用本地儲存記錄發放狀態
  const hasIssued = localStorage.getItem('level10_award_issued');
  if (hasIssued) {
    alert('該關卡獎勵已領取，不可重複領取');
    return;
  }

  // 發放道具（ID：3232addasdda3aa2，數量10）
  window.JOGOS_SDK.gameItem.addGameItem('3232addasdda3aa2', 10);
  // 記錄發放狀態
  localStorage.setItem('level10_award_issued', 'true');
  alert('關卡10通關成功！獲得10個道具獎勵');
}