Item-System und Plattform-Paid-Store

Dieses System bietet eine einheitliche Lösung zur Verwaltung bezahlter Items für die Spieleplattform, unterstützt Funktionen wie Item-Kauf, -Verteilung und -Statistiken für Standalone-Spiele und implementiert Item-Kauf, -Abfrage, -Hinzufügung/Reduzierung und prozessgesteuerte Verteilungsfunktionen.

• Kernfunktionen: Item-Kauf, Besitzabfrage, Hinzufügungs-/Reduzierungsoperationen, Änderungsüberwachung, spielprozessgesteuerte Verteilung

1. Backend-Verwaltungsfunktionen für Entwickler

• Entwickler können Item-Daten manuell über das Backend erstellen, unterstützt den Upload von Tabellen (Item-Einheitentabelle) und Item-Icons.
• Bezahlte Store-Items unterstützen derzeit nur die manuelle Erstellung.
• Unterstützt die Erstellung von bis zu 5000 Item-Dateneinträgen.
• Unterstützt derzeit nur Spiele des Typs Kaufen-und-Besitzen und In-App-Käufe.
• Items müssen nach der Erstellung überprüft werden; nach der Genehmigung wechseln sie standardmäßig in den aktivierten Status.

Item-Verwaltungsfunktionen:

‌Item-ID‌: Eindeutiger Identifikator, kann nach der Erstellung nicht geändert werden
‌Item-Name und -Icon‌: Wird für die Frontend-Anzeige verwendet
‌Item-Icon‌: Unterstützt den manuellen Austausch des Icon-Bildes
‌Item-Erstellungsregeln: Unterstützt die Auswahl zwischen Spiel-Item und Store-Bezahltem-Item
Item-Beschränkungen: Unterstützt das Setzen von Limits für die Verteilung an Spieler über die Plattform, wie tägliches Verteilungsmengenlimit, Gesamtmengenlimit oder kein Limit
‌Item-Bestand‌: Kann eine Menge eingeben oder kein Limit setzen
Item-Werteinstellungen:
Kostenloses Item (Platform activities): Unterstützt die Verteilung über Plattformaktivitäten.
Bezahlter Kauf (Paid purchase): Unterstützt bezahlten Kauf im Item-Store.
Standardpreisgestaltung in US-Dollar
Item-Einheitenpreis unterstützt eine Genauigkeit von bis zu 0,0001 USD
Mindestwert-Eingabe für bezahlte Store-Items beträgt 1 USD

Vorschlag

• Zuerst die Item-Einheiten erfassen, dann manuell die Items für bezahlten Kauf im Store eingeben; unterstützt die Auswahl eines oder mehrerer Items, um ein gebündeltes Produkt für den Verkauf zu bilden.
• Wenn ein Item als kostenloses Item eingestellt wird, kann die Plattform entscheiden, es gemäß Betriebsplänen an Spieler zu verteilen; es wird an den Spielcharakter des Spielers ausgeliefert, wenn dieser das Spiel betritt.

2. Item-SDK-Integration

Kern-Interface-Beschreibung

Interface-Name	Methodensignatur	Funktionsbeschreibung
Kauffenster öffnen	openBuyGameItemsDialog(level: number)	Öffnet den Store-Item-Kaufdialog über die funktionale UI im Spiel.
Besessene Items abrufen	getUserGameItems(): GameItem[]	Fragt die aktuelle Item-Liste des Spielers beim Betreten des Spiels ab (enthält ID und Menge).
Item hinzufügen	addGameItem(itemId: string, amount: number)	Verteilt Items während des Spielfortschritts (unterstützt Szenarien wie Käufe, Level-Belohnungen, Missionsabschluss, etc.).
Item reduzieren	subtractGameItem(itemId: string, amount: number)	Verbraucht Items (Szenarien der Verwendung oder des Konsums während des Spielfortschritts, Menge nach Abzug ist nicht-negativ).
Änderungsbenachrichtigung abonnieren	subscribeGameItemChange(callback: (res: GameItemChange) => void)	Callback-Methode, die ausgeführt wird, wenn die Zahlung für ein bezahltes Store-Item abgeschlossen ist.

Wichtige Datenformate

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

2.1 Liste der besessenen Items abrufen

// Liste der vom Spieler besessenen Items abrufen (wird während der Spielinitialisierung aufgerufen)
const items = window.JOGOS_SDK.gameItem.getUserGameItems();
console.log('Besessene Items:', items);

2.2 Item-Kauf-Fenster öffnen

// Item-Kauf-Fenster öffnen
window.JOGOS_SDK.gameItem.openBuyGameItemsDialog(10);

2.3 Item hinzufügen

// Item hinzufügen (ID: 3232addasdda3aa2, Menge: 10)
window.JOGOS_SDK.gameItem.addGameItem('3232addasdda3aa2', 10);

2.4 Item reduzieren

// Item reduzieren (ID: 3232addasdda3aa2, Menge: 5)
window.JOGOS_SDK.gameItem.subtractGameItem('3232addasdda3aa2', 5);

2.5 Item-Änderungsbenachrichtigung abonnieren

// Item-Änderungsbenachrichtigung abonnieren
window.JOGOS_SDK.gameItem.subscribeGameItemChange((res) => {
  console.log('Item-Änderung:', res);
});

2.6 Vollständiger Ablauf für bezahlten Item-Kauf

// 1. Bezahlten Item-Kauf initiieren (Produkt-ID: item_gold_100, entspricht 100 Goldmünzen-Item)
async function buyGoldItem() {
  try {
    const orderNo = await window.JOGOS_SDK.payment.buyGoods('item_gold_100');
    console.log('Bestellung erfolgreich erstellt, Bestellnummer:', orderNo);
  } catch (err) {
    console.error('Bestellungserstellung fehlgeschlagen:', err);
    alert('Kaufinitiierung fehlgeschlagen, bitte versuchen Sie es später erneut');
  }
}

// 2. Zahlungserfolgsbenachrichtigung abonnieren (wird während der Spielinitialisierung aufgerufen)
window.JOGOS_SDK.payment.subscribeOrderPaid(async (order) => {
  console.log('Zahlung erfolgreich, Bestelldetails:', order);
  if (order.status === 'success') {
    // 3. Entsprechendes Item verteilen (Produkt-ID: item_gold_100 entspricht Item-ID: 3232addasdda3aa2)
    window.JOGOS_SDK.gameItem.addGameItem('3232addasdda3aa2', 100);
    // 4. Plattform über Lieferung benachrichtigen (muss aufgerufen werden, sonst ist der Bestellstatus abnormal)
    await window.JOGOS_SDK.payment.deliverGoods(order.orderNo);
    alert('100 Goldmünzen erfolgreich gekauft, wurden in den Rucksack ausgeliefert!');
  }
});

// 3. Ausnahmeszenario: Bestelldetails abfragen (z.B. wenn Item nach Zahlung nicht erhalten)
async function checkOrder(orderNo) {
  try {
    const order = await window.JOGOS_SDK.payment.getOrderDetail(orderNo);
    console.log('Bestelldetails-Abfrage:', order);
    if (order.status === 'success') {
      // Item erneut verteilen
      window.JOGOS_SDK.gameItem.addGameItem('3232addasdda3aa2', 100);
      await window.JOGOS_SDK.payment.deliverGoods(orderNo);
    }
  } catch (err) {
    console.error('Bestellabfrage fehlgeschlagen:', err);
  }
}

2.7 Spielprozess-gesteuerte Item-Verteilung (Beispiel: Level-Abschlussbelohnung)

// Level 10 Abschluss löst Item-Verteilung aus (enthält Deduplizierungslogik, um doppelte Abholung zu vermeiden)
function onLevel10Clear() {
  // Standalone-Spiel: Lokalen Speicher verwenden, um Verteilungsstatus zu erfassen
  const hasIssued = localStorage.getItem('level10_award_issued');
  if (hasIssued) {
    alert('Diese Level-Belohnung wurde bereits abgeholt, kann nicht erneut abgeholt werden');
    return;
  }

  // Item verteilen (ID: 3232addasdda3aa2, Menge: 10)
  window.JOGOS_SDK.gameItem.addGameItem('3232addasdda3aa2', 10);
  // Verteilungsstatus erfassen
  localStorage.setItem('level10_award_issued', 'true');
  alert('Level 10 erfolgreich abgeschlossen! 10 Item-Belohnungen erhalten');
}