Hệ thống Vật phẩm và Cửa hàng Trả phí Nền tảng

Hệ thống này cung cấp giải pháp quản lý vật phẩm trả phí thống nhất cho nền tảng trò chơi, hỗ trợ các chức năng như mua, phân phối và thống kê vật phẩm cho trò chơi đơn lẻ, triển khai các chức năng mua, truy vấn, thêm/bớt vật phẩm và phân phối kích hoạt theo quy trình trò chơi.

• Chức năng chính: Mua vật phẩm, Truy vấn sở hữu, Thao tác thêm/bớt, Giám sát thay đổi, Phân phối kích hoạt theo quy trình trò chơi

1. Chức năng Quản lý Backend cho Nhà phát triển

• Nhà phát triển có thể tạo dữ liệu vật phẩm thủ công thông qua backend, hỗ trợ tải lên bảng (bảng đơn vị vật phẩm) và biểu tượng vật phẩm.
• Vật phẩm trả phí trong cửa hàng hiện chỉ hỗ trợ tạo thủ công.
• Hỗ trợ tạo tối đa 5000 mục dữ liệu vật phẩm.
• Tạm thời chỉ hỗ trợ trò chơi loại mua một lần và mua trong ứng dụng.
• Vật phẩm cần được phê duyệt sau khi tạo; sau khi được chấp thuận, chúng sẽ chuyển sang trạng thái bật theo mặc định.

Chức năng Quản lý Vật phẩm:

‌ID Vật phẩm‌: Định danh duy nhất, không thể sửa đổi sau khi tạo
‌Tên và Biểu tượng Vật phẩm‌: Được sử dụng để hiển thị frontend
‌Biểu tượng Vật phẩm‌: Hỗ trợ thay đổi thủ công hình ảnh biểu tượng
‌Quy tắc Tạo Vật phẩm: Hỗ trợ lựa chọn giữa Vật phẩm Trò chơi và Vật phẩm Trả phí Cửa hàng
Hạn chế Vật phẩm: Hỗ trợ thiết lập hạn chế để phân phối cho người chơi thông qua nền tảng, chẳng hạn như giới hạn số lượng phân phối hàng ngày, giới hạn tổng số lượng hoặc không giới hạn
‌Tồn kho Vật phẩm‌: Có thể chọn nhập số lượng hoặc không giới hạn
Thiết lập Giá trị Vật phẩm:
Vật phẩm Miễn phí (Platform activities): Hỗ trợ phân phối thông qua hoạt động nền tảng.
Mua Trả phí (Paid purchase): Hỗ trợ mua trả phí trong cửa hàng vật phẩm.
Định giá bằng Đô la Mỹ theo mặc định
Giá đơn vị vật phẩm hỗ trợ chính xác đến 0.0001 USD
Giá trị nhập tối thiểu cho vật phẩm trả phí cửa hàng là 1 USD

Đề xuất

• Đầu tiên đăng ký các đơn vị vật phẩm, sau đó nhập thủ công các vật phẩm để mua trả phí trong cửa hàng; hỗ trợ lựa chọn một hoặc nhiều vật phẩm để tạo thành sản phẩm gói để bán.
• Khi một vật phẩm được đặt là vật phẩm miễn phí, nền tảng có thể chọn phân phối nó cho người chơi theo kế hoạch vận hành; nó sẽ được giao đến nhân vật trò chơi của người chơi khi họ vào trò chơi.

2. Tích hợp SDK Vật phẩm

Mô tả Giao diện Cốt lõi

Tên Giao diện	Chữ ký Phương thức	Mô tả Chức năng
Mở Cửa sổ Mua hàng	openBuyGameItemsDialog(level: number)	Mở hộp thoại mua vật phẩm cửa hàng thông qua UI chức năng bên trong trò chơi.
Lấy Vật phẩm Sở hữu	getUserGameItems(): GameItem[]	Truy vấn danh sách vật phẩm hiện tại của người chơi khi vào trò chơi (bao gồm ID và số lượng).
Thêm Vật phẩm	addGameItem(itemId: string, amount: number)	Phân phối vật phẩm trong quá trình chơi game (hỗ trợ các kịch bản như mua hàng, phần thưởng cấp độ, hoàn thành nhiệm vụ, v.v.).
Giảm Vật phẩm	subtractGameItem(itemId: string, amount: number)	Tiêu thụ vật phẩm (các kịch bản sử dụng hoặc tiêu thụ trong quá trình chơi game, số lượng sau khi khấu trừ là không âm).
Đăng ký Thông báo Thay đổi	subscribeGameItemChange(callback: (res: GameItemChange) => void)	Phương thức callback được thực thi khi thanh toán cho vật phẩm trả phí cửa hàng hoàn tất.

Định dạng Dữ liệu Quan trọng

• ​**GameItem (Thông tin Vật phẩm)**​: { itemId: string, amount: number }
• ​**GameItemChange (Thông tin Thay đổi)**​: { itemId: string, amount: number, changeType: 'add'|'subtract', total: number }

2.1 Lấy Danh sách Vật phẩm Sở hữu

// Lấy danh sách vật phẩm sở hữu của người chơi (được gọi trong quá trình khởi tạo trò chơi)
const items = window.JOGOS_SDK.gameItem.getUserGameItems();
console.log('Vật phẩm sở hữu:', items);

2.2 Mở Cửa sổ Mua Vật phẩm

// Mở cửa sổ mua vật phẩm
window.JOGOS_SDK.gameItem.openBuyGameItemsDialog(10);

2.3 Thêm Vật phẩm

// Thêm vật phẩm (ID: 3232addasdda3aa2, số lượng: 10)
window.JOGOS_SDK.gameItem.addGameItem('3232addasdda3aa2', 10);

2.4 Giảm Vật phẩm

// Giảm vật phẩm (ID: 3232addasdda3aa2, số lượng: 5)
window.JOGOS_SDK.gameItem.subtractGameItem('3232addasdda3aa2', 5);

2.5 Đăng ký Thông báo Thay đổi Vật phẩm

// Đăng ký thông báo thay đổi vật phẩm
window.JOGOS_SDK.gameItem.subscribeGameItemChange((res) => {
  console.log('Thay đổi vật phẩm:', res);
});

2.6 Quy trình Mua Vật phẩm Trả phí Đầy đủ

// 1. Bắt đầu mua vật phẩm trả phí (ID sản phẩm: item_gold_100, tương ứng với vật phẩm 100 xu vàng)
async function buyGoldItem() {
  try {
    const orderNo = await window.JOGOS_SDK.payment.buyGoods('item_gold_100');
    console.log('Đơn hàng tạo thành công, số đơn hàng:', orderNo);
  } catch (err) {
    console.error('Tạo đơn hàng thất bại:', err);
    alert('Bắt đầu mua thất bại, vui lòng thử lại sau');
  }
}

// 2. Đăng ký thông báo thanh toán thành công (được gọi trong quá trình khởi tạo trò chơi)
window.JOGOS_SDK.payment.subscribeOrderPaid(async (order) => {
  console.log('Thanh toán thành công, chi tiết đơn hàng:', order);
  if (order.status === 'success') {
    // 3. Phân phối vật phẩm tương ứng (ID sản phẩm: item_gold_100 tương ứng với ID vật phẩm: 3232addasdda3aa2)
    window.JOGOS_SDK.gameItem.addGameItem('3232addasdda3aa2', 100);
    // 4. Thông báo nền tảng giao hàng (phải được gọi, nếu không trạng thái đơn hàng sẽ bất thường)
    await window.JOGOS_SDK.payment.deliverGoods(order.orderNo);
    alert('Mua 100 xu vàng thành công, đã được phân phối đến ba lô!');
  }
});

// 3. Kịch bản ngoại lệ: Truy vấn chi tiết đơn hàng (ví dụ: nếu không nhận được vật phẩm sau khi thanh toán)
async function checkOrder(orderNo) {
  try {
    const order = await window.JOGOS_SDK.payment.getOrderDetail(orderNo);
    console.log('Truy vấn chi tiết đơn hàng:', order);
    if (order.status === 'success') {
      // Phân phối lại vật phẩm
      window.JOGOS_SDK.gameItem.addGameItem('3232addasdda3aa2', 100);
      await window.JOGOS_SDK.payment.deliverGoods(orderNo);
    }
  } catch (err) {
    console.error('Truy vấn đơn hàng thất bại:', err);
  }
}

2.7 Phân phối Vật phẩm Kích hoạt theo Quy trình Trò chơi (Ví dụ: Phần thưởng Vượt qua Cấp độ)

// Vượt qua cấp độ 10 kích hoạt phân phối vật phẩm (bao gồm logic chống trùng lặp để tránh nhận trùng)
function onLevel10Clear() {
  // Trò chơi đơn lẻ: sử dụng bộ nhớ cục bộ để ghi lại trạng thái phân phối
  const hasIssued = localStorage.getItem('level10_award_issued');
  if (hasIssued) {
    alert('Phần thưởng cấp độ này đã được nhận, không thể nhận lại');
    return;
  }

  // Phân phối vật phẩm (ID: 3232addasdda3aa2, số lượng: 10)
  window.JOGOS_SDK.gameItem.addGameItem('3232addasdda3aa2', 10);
  // Ghi lại trạng thái phân phối
  localStorage.setItem('level10_award_issued', 'true');
  alert('Vượt qua cấp độ 10 thành công! Nhận được 10 phần thưởng vật phẩm');
}