Sistema di Oggetti e Negozio a Pagamento della Piattaforma

Questo sistema fornisce una soluzione unificata per la gestione di oggetti a pagamento per la piattaforma di gioco, supporta funzionalità come l'acquisto, la distribuzione e le statistiche degli oggetti per giochi standalone, e implementa le funzioni di acquisto, consultazione, aggiunta/riduzione degli oggetti e distribuzione attivata dal processo di gioco.

• Funzionalità principali: Acquisto di oggetti, Consultazione del possesso, Operazioni di aggiunta/riduzione, Monitoraggio delle modifiche, Distribuzione attivata dal processo di gioco

1. Funzionalità di Gestione Backend per Sviluppatori

• Gli sviluppatori possono creare manualmente dati degli oggetti tramite il backend, supporta il caricamento di tabelle (tabella unità oggetti) e icone degli oggetti.
• Gli oggetti a pagamento del negozio attualmente supportano solo la creazione manuale.
• Supporta la creazione di fino a 5000 voci di dati oggetti.
• Attualmente supporta solo giochi di tipo acquisto singolo e acquisti in-app.
• Gli oggetti devono essere approvati dopo la creazione; una volta approvati, passano allo stato abilitato per impostazione predefinita.

Funzionalità di Gestione Oggetti:

‌ID Oggetto‌: Identificatore univoco, non può essere modificato dopo la creazione
‌Nome e Icona Oggetto‌: Utilizzati per la visualizzazione frontend
‌Icona Oggetto‌: Supporta la sostituzione manuale dell'immagine dell'icona
‌Regole di Creazione Oggetti: Supporta la selezione tra Oggetto di Gioco e Oggetto a Pagamento del Negozio
Limitazioni Oggetto: Supporta l'impostazione di limiti per la distribuzione ai giocatori tramite la piattaforma, come limite quantità distribuzione giornaliera, limite quantità totale o nessun limite
‌Scorta Oggetti‌: Può scegliere di inserire una quantità o non impostare limiti
Impostazioni Valore Oggetto:
Oggetto Gratuito (Platform activities): Supporta la distribuzione tramite attività della piattaforma.
Acquisto a Pagamento (Paid purchase): Supporta l'acquisto a pagamento nel negozio oggetti.
Prezzatura predefinita in Dollari USA
Il prezzo unitario dell'oggetto supporta una precisione fino a 0,0001 USD
Il valore minimo di inserimento per oggetti a pagamento del negozio è 1 USD

Suggerimento

• Prima registra le unità oggetti, poi inserisci manualmente gli oggetti per l'acquisto a pagamento nel negozio; supporta la selezione di uno o più oggetti per formare un prodotto in bundle per la vendita.
• Quando un oggetto è impostato come oggetto gratuito, la piattaforma può scegliere di distribuirlo ai giocatori secondo i piani operativi; sarà consegnato al personaggio di gioco del giocatore quando entrerà nel gioco.

2. Integrazione SDK Oggetti

Descrizione Interfacce Principali

Nome Interfaccia	Firma Metodo	Descrizione Funzionalità
Apri Finestra Acquisto	openBuyGameItemsDialog(level: number)	Apre la finestra di dialogo per l'acquisto di oggetti del negozio tramite l'interfaccia utente funzionale all'interno del gioco.
Ottieni Oggetti Posseduti	getUserGameItems(): GameItem[]	Interroga l'elenco corrente degli oggetti del giocatore all'ingresso nel gioco (include ID e quantità).
Aggiungi Oggetto	addGameItem(itemId: string, amount: number)	Distribuisce oggetti durante la progressione del gioco (supporta scenari come acquisti, ricompense livello, completamento missione, ecc.).
Riduci Oggetto	subtractGameItem(itemId: string, amount: number)	Consuma oggetti (scenari di utilizzo o consumo durante la progressione del gioco, la quantità dopo la detrazione è non negativa).
Sottoscrivi Notifica Cambiamenti	subscribeGameItemChange(callback: (res: GameItemChange) => void)	Metodo di callback eseguito quando il pagamento di un oggetto a pagamento del negozio è completato.

Formati Dati Chiave

• ​**GameItem (Informazioni Oggetto)**​: { itemId: string, amount: number }
• ​**GameItemChange (Informazioni Cambiamento)**​: { itemId: string, amount: number, changeType: 'add'|'subtract', total: number }

2.1 Ottieni Elenco Oggetti Posseduti

// Ottieni l'elenco degli oggetti posseduti dal giocatore (chiamato durante l'inizializzazione del gioco)
const items = window.JOGOS_SDK.gameItem.getUserGameItems();
console.log('Oggetti posseduti:', items);

2.2 Apri Finestra Acquisto Oggetti

// Apri finestra acquisto oggetti
window.JOGOS_SDK.gameItem.openBuyGameItemsDialog(10);

2.3 Aggiungi Oggetto

// Aggiungi oggetto (ID: 3232addasdda3aa2, quantità: 10)
window.JOGOS_SDK.gameItem.addGameItem('3232addasdda3aa2', 10);

2.4 Riduci Oggetto

// Riduci oggetto (ID: 3232addasdda3aa2, quantità: 5)
window.JOGOS_SDK.gameItem.subtractGameItem('3232addasdda3aa2', 5);

2.5 Sottoscrivi Notifica Cambiamenti Oggetto

// Sottoscrivi notifica cambiamenti oggetto
window.JOGOS_SDK.gameItem.subscribeGameItemChange((res) => {
  console.log('Cambiamento oggetto:', res);
});

2.6 Flusso Completo Acquisto Oggetto a Pagamento

// 1. Avvia acquisto oggetto a pagamento (ID prodotto: item_gold_100, corrisponde a oggetto 100 monete d'oro)
async function buyGoldItem() {
  try {
    const orderNo = await window.JOGOS_SDK.payment.buyGoods('item_gold_100');
    console.log('Ordine creato con successo, numero ordine:', orderNo);
  } catch (err) {
    console.error('Creazione ordine fallita:', err);
    alert('Avvio acquisto fallito, riprova più tardi');
  }
}

// 2. Sottoscrivi notifica pagamento riuscito (chiamato durante l'inizializzazione del gioco)
window.JOGOS_SDK.payment.subscribeOrderPaid(async (order) => {
  console.log('Pagamento riuscito, dettagli ordine:', order);
  if (order.status === 'success') {
    // 3. Distribuisci oggetto corrispondente (ID prodotto: item_gold_100 corrisponde a ID oggetto: 3232addasdda3aa2)
    window.JOGOS_SDK.gameItem.addGameItem('3232addasdda3aa2', 100);
    // 4. Notifica la piattaforma per la consegna (deve essere chiamato, altrimenti lo stato dell'ordine sarà anomalo)
    await window.JOGOS_SDK.payment.deliverGoods(order.orderNo);
    alert("100 monete d'oro acquistate con successo, sono state consegnate nello zaino!");
  }
});

// 3. Scenario eccezione: Interroga dettagli ordine (ad esempio, se l'oggetto non viene ricevuto dopo il pagamento)
async function checkOrder(orderNo) {
  try {
    const order = await window.JOGOS_SDK.payment.getOrderDetail(orderNo);
    console.log('Interrogazione dettagli ordine:', order);
    if (order.status === 'success') {
      // Ridistribuisci oggetto
      window.JOGOS_SDK.gameItem.addGameItem('3232addasdda3aa2', 100);
      await window.JOGOS_SDK.payment.deliverGoods(orderNo);
    }
  } catch (err) {
    console.error('Interrogazione ordine fallita:', err);
  }
}

2.7 Distribuzione Oggetti Attivata da Processo di Gioco (Esempio: Ricompensa Completamento Livello)

// Completamento livello 10 attiva distribuzione oggetti (include logica deduplicazione per evitare rivendicazioni duplicate)
function onLevel10Clear() {
  // Gioco standalone: usa archiviazione locale per registrare stato distribuzione
  const hasIssued = localStorage.getItem('level10_award_issued');
  if (hasIssued) {
    alert('Questa ricompensa livello è già stata rivendicata, non può essere rivendicata nuovamente');
    return;
  }

  // Distribuisci oggetto (ID: 3232addasdda3aa2, quantità: 10)
  window.JOGOS_SDK.gameItem.addGameItem('3232addasdda3aa2', 10);
  // Registra stato distribuzione
  localStorage.setItem('level10_award_issued', 'true');
  alert('Livello 10 completato con successo! 10 ricompense oggetto ottenute');
}