Item System and Platform Paid Store

This system provides a unified paid item management solution for the gaming platform, supporting functions such as item purchase, distribution, and statistics for standalone games, implementing item purchase, query, addition/reduction, and process-triggered distribution functionalities.

• Core functions: Item purchase, Possession query, Addition/reduction operations, Change monitoring, Game process-triggered distribution

1. Developer Backend Management Functions

• Developers can manually create item data through the backend, supporting the upload of tables (item unit table) and item icons.
• Paid store items currently only support manual creation.
• Supports creating up to 5000 item data entries.
• Currently only supports games of the buy-to-play and in-app purchase types.
• Items need to be reviewed after creation; once approved, they will enter the enabled state by default.

Item Management Functions:

‌Item ID‌: Unique identifier, cannot be modified after creation
‌Item Name and Icon‌: Used for frontend display
‌Item Icon‌: Supports manual replacement of the Icon image
‌Item Creation Rules: Supports selection between Game Item and Store Paid Item
Item Restrictions: Supports setting limits for distribution to players through the platform, such as daily distribution quantity limit, total quantity limit, or no limit
‌Item Stock‌: Can choose to input a quantity or set no limit
Item Value Settings:
Free Item (Platform activities): Supports distribution through platform activities.
Paid Purchase (Paid purchase): Supports paid purchase in the item store.
Default pricing in US Dollars
Item unit pricing supports precision up to 0.0001 USD
Minimum value input for store paid items is 1 USD

Suggestion

• First register the item units, then manually enter the items for paid purchase in the store; supports selecting one or multiple items to form a bundled product for sale.
• When an item is set as a free item, the platform may choose to distribute it to players according to operational plans; it will be delivered to the player's game character when they enter the game.

2. Item SDK Integration

Core Interface Description

Interface Name	Method Signature	Function Description
Open Purchase Window	openBuyGameItemsDialog(level: number)	Opens the store item purchase dialog through the functional UI within the game.
Get Possessed Items	getUserGameItems(): GameItem[]	Queries the player's current item list when entering the game (includes ID and quantity).
Add Item	addGameItem(itemId: string, amount: number)	Distributes items during game progress (supports scenarios such as purchases, level rewards, mission completion, etc.).
Subtract Item	subtractGameItem(itemId: string, amount: number)	Consumes items (scenarios of use or consumption during game progress, quantity after deduction is non-negative).
Subscribe to Change Notification	subscribeGameItemChange(callback: (res: GameItemChange) => void)	Callback method executed when payment for a store paid item is completed.

Key Data Formats

• ​**GameItem (Item Information)**​: { itemId: string, amount: number }
• ​**GameItemChange (Change Information)**​: { itemId: string, amount: number, changeType: 'add'|'subtract', total: number }

2.1 Get Possessed Items List

// Get the player's possessed items list (called during game initialization)
const items = window.JOGOS_SDK.gameItem.getUserGameItems();
console.log('Possessed items:', items);

2.2 Open Item Purchase Window

// Open item purchase window
window.JOGOS_SDK.gameItem.openBuyGameItemsDialog(10);

2.3 Add Item

// Add item (ID: 3232addasdda3aa2, quantity: 10)
window.JOGOS_SDK.gameItem.addGameItem('3232addasdda3aa2', 10);

2.4 Subtract Item

// Subtract item (ID: 3232addasdda3aa2, quantity: 5)
window.JOGOS_SDK.gameItem.subtractGameItem('3232addasdda3aa2', 5);

2.5 Subscribe to Item Change Notification

// Subscribe to item change notification
window.JOGOS_SDK.gameItem.subscribeGameItemChange((res) => {
  console.log('Item change:', res);
});

2.6 Complete Paid Item Purchase Flow

// 1. Initiate paid item purchase (Product ID: item_gold_100, corresponds to 100 gold coin item)
async function buyGoldItem() {
  try {
    const orderNo = await window.JOGOS_SDK.payment.buyGoods('item_gold_100');
    console.log('Order created successfully, order number:', orderNo);
  } catch (err) {
    console.error('Order creation failed:', err);
    alert('Purchase initiation failed, please try again later');
  }
}

// 2. Subscribe to payment success notification (called during game initialization)
window.JOGOS_SDK.payment.subscribeOrderPaid(async (order) => {
  console.log('Payment successful, order details:', order);
  if (order.status === 'success') {
    // 3. Distribute corresponding item (Product ID: item_gold_100 corresponds to Item ID: 3232addasdda3aa2)
    window.JOGOS_SDK.gameItem.addGameItem('3232addasdda3aa2', 100);
    // 4. Notify platform to deliver goods (must be called, otherwise order status will be abnormal)
    await window.JOGOS_SDK.payment.deliverGoods(order.orderNo);
    alert('100 gold coins purchased successfully, have been delivered to your backpack!');
  }
});

// 3. Exception scenario: Query order details (e.g., if item not received after payment)
async function checkOrder(orderNo) {
  try {
    const order = await window.JOGOS_SDK.payment.getOrderDetail(orderNo);
    console.log('Order details query:', order);
    if (order.status === 'success') {
      // Re-distribute item
      window.JOGOS_SDK.gameItem.addGameItem('3232addasdda3aa2', 100);
      await window.JOGOS_SDK.payment.deliverGoods(orderNo);
    }
  } catch (err) {
    console.error('Order query failed:', err);
  }
}

2.7 Game Process-Triggered Item Distribution (Example: Level Clearance Reward)

// Level 10 clearance triggers item distribution (includes deduplication logic to avoid duplicate claims)
function onLevel10Clear() {
  // Standalone game: use local storage to record distribution status
  const hasIssued = localStorage.getItem('level10_award_issued');
  if (hasIssued) {
    alert('This level reward has already been claimed, cannot claim again');
    return;
  }

  // Distribute item (ID: 3232addasdda3aa2, quantity: 10)
  window.JOGOS_SDK.gameItem.addGameItem('3232addasdda3aa2', 10);
  // Record distribution status
  localStorage.setItem('level10_award_issued', 'true');
  alert('Level 10 cleared successfully! Received 10 item rewards');
}