Pagamento

Il modulo di pagamento fornisce funzionalità relative all'acquisto di articoli in-game e ai pagamenti forfettari. Dopo aver letto la sezione pertinente al tuo motore di gioco nella pagina Introduzione a JOGOS_SDK, puoi utilizzare le funzioni correlate nel seguente modo:

window.JOGOS_SDK.payment;

Acquisti In-App

Passo 1: Creare un ID prodotto

• Crea prodotti nella pagina Information / Purchase del backend dello sviluppatore.
• Nota: Gli ID prodotto non possono essere duplicati all'interno dello stesso gioco.

Passo 2: Iniziare un ordine

• Quando un giocatore necessita di acquistare un oggetto nel gioco, puoi chiamare questa interfaccia sul pulsante di acquisto per aprire la finestra di pagamento Jogos.
• Lo sviluppatore deve passare l'ID del prodotto (goodsId). Dopo aver aperto con successo la finestra di pagamento, viene restituito un numero d'ordine. Successivamente, lo sviluppatore può utilizzare questo numero d'ordine per interrogare le informazioni relative a questo ordine.
• goodsId è l'ID del prodotto che hai creato nel backend dello sviluppatore.

// Restituisce il numero d'ordine in caso di successo
let orderNo = await window.JOGOS_SDK.payment.buyGoods(goodsId: string);

Passo 3: Attendere il pagamento dell'utente

Sottoscrivere la notifica di completamento pagamento ordine dal client

Potrebbe esserci un ritardo significativo tra quando un giocatore effettua un ordine e quando il pagamento va a buon fine. Gli sviluppatori possono utilizzare questa interfaccia per iscriversi ai messaggi di pagamento riuscito del giocatore. Quando un giocatore paga con successo, la piattaforma notificherà il callback sottoscritto, informando attivamente lo sviluppatore che l'ordine è stato pagato e restituendo le informazioni più aggiornate sull'ordine.

window.JOGOS_SDK.payment.subscribeOrderPaid(callbackFn: (order: PaymentOrder) => void);

Passo 4: Spedire la merce e notificare la piattaforma

Gestire la spedizione lato client (Giochi standalone)

Quando lo sviluppatore viene a conoscenza del pagamento riuscito del giocatore, elabora automaticamente la distribuzione delle ricompense e chiama questa interfaccia per notificare alla piattaforma che la spedizione è stata effettuata.

Promemoria

• Se il tuo gioco (non ha un server di gioco), si consiglia, dopo aver rilevato il pagamento dell'utente sul client, di chiamare questa interfaccia per informare la piattaforma Jogos che hai spedito la merce a questo utente.
• In base al risultato restituito dall'interfaccia, gestisci la distribuzione delle ricompense nel tuo gioco o visualizza messaggi di altre eccezioni.
• Si consiglia, dopo la spedizione, di chiamare l'interfaccia di sincronizzazione dei salvataggi del sistema di archiviazione cloud per salvare i dati del giocatore.

await window.JOGOS_SDK.payment.deliverGoods(orderNo: string);

Metodo tramite integrazione del "Server di Gioco":

Per le API relative all'integrazione del server, consultare la pagina Interfaccia di Integrazione Server.

Altre Interfacce

Suggerimenti per migliorare i pagamenti

• L'iscrizione lato client alle notifiche di pagamento utente riuscito (subscribeOrderPaid) non può garantire la ricezione del 100% delle notifiche a causa di vari fattori incontrollabili come problemi di rete. Ti consigliamo di utilizzare l'Interfaccia di Ottenimento Ordini per verificare lo stato di pagamento più recente di questo ordine.
• Alcuni giochi standalone potrebbero offrire una funzione di eliminazione dei salvataggi. La decisione di redistribuire le ricompense dei pagamenti precedenti spetta a te. Gli sviluppatori possono chiamare l'interfaccia di query dell'elenco ordini per ottenere tutti gli ordini del giocatore ed effettuare una ridistribuzione.
• Dopo aver ottenuto le informazioni sull'ordine, utilizza il campo status per giudicare e elaborare l'ordine.

Informazioni sull'Ordine

Interroga i dettagli di un ordine in base al suo numero. La struttura dell'ordine è la seguente:

// Ordine di Pagamento
export interface PaymentOrder {
  // ID Gioco
  gameId: number;
  // Nome Gioco
  gameName: string;
  // ID Utente
  userId: number;
  // Numero Ordine
  orderNo: string;
  // ID Prodotto
  productId: string;
  // Nome Prodotto
  productName: string;
  // Valuta
  currency: string;
  // Paese
  country: string;
  // Sconto
  discount: number;
  // Deduzione Moneta Jogos (Punti)
  calorcoin: number;
  // Importo Pagato
  paid: number;
  // Canale di Pagamento
  channel: string;
  // Tipo di Pagamento
  paymentType: string;
  // Numero Transazione di Pagamento
  paymentNo: string;
  // Merce già Spedita
  deliverGoods: boolean;
  // Stato Ordine: pending (in attesa), fail (fallito), cancel (annullato), expire (scaduto), success (successo), refunding (rimborso in corso), refunded (rimborsato), refund-fail (rimborso fallito)
  status: 'pending' | 'fail' | 'cancel' | 'expire' | 'success' | 'refunding' | 'refunded' | 'refund-fail';
  // Ora di Creazione Ordine
  createTime: String;
  // Numero Rimborso
  refundNo: String;
  // Descrizione Rimborso
  refundDescription: String;
  // Ora Richiesta Rimborso
  refundTime: String;
  // Ora Rimborso Riuscito
  refundedTime: String;
}

Ottieni Informazioni Ordine

// Restituisce informazioni ordine in caso di successo
let order = await window.JOGOS_SDK.payment.getOrderDetail(orderNo: string);

Ottieni Elenco Ordini

Gli sviluppatori possono utilizzare questa interfaccia per interrogare ordini di stati specifici. Restituisce un elenco di ordini in caso di successo. La struttura delle informazioni dell'ordine è la stessa dei dettagli dell'ordine.

// Restituisce l'elenco ordini in caso di successo
let orderList = await window.JOGOS_SDK.payment.getOrderList(
  status?: 'pending' | 'fail' | 'cancel' | 'expire' | 'success' | 'refunding' | 'refunded',
  pageNo?: number,  // Numero pagina: predefinito 1
  pageSize?: number // Numero record per pagina: predefinito 20
);

Giochi in Acquisto Unico (Buy-to-Play)

1. Imposta il tuo gioco su "Game Pricing" (tipo acquisto unico) nel backend dello sviluppatore e imposta il prezzo del tuo gioco.
2. Crea due versioni di invio per il tuo gioco: una Versione di Prova (Trial) e una Versione Completa (Full).

• Versione di Prova: Si consiglia di rimuovere risorse di livelli inaccessibili al giocatore, modelli, texture, musica, ecc., mantenendo solo il contenuto disponibile per la prova. Pacchettizza e carica questa versione separatamente.
• Versione Completa: La versione in cui i giocatori hanno accesso al contenuto completo del gioco.

3. Configura un pulsante di acquisto nella versione di prova:

• Quando il giocatore termina la prova, ad esempio raggiungendo l'ultimo livello del Capitolo 1 nella versione di prova, e necessita di acquistare la versione completa del gioco, progetta un'interfaccia per "Vendere la Versione Completa" con un pulsante di acquisto:
• Il pulsante di acquisto può chiamare l'interfaccia buyOut per aprire la finestra di pagamento della piattaforma Jogos, permettendo ai giocatori di acquistare rapidamente la versione completa del gioco.
• Una volta che l'utente acquista con successo, la piattaforma Jogos passerà automaticamente alla versione completa per far continuare a giocare il giocatore. Nessuna elaborazione aggiuntiva è richiesta allo sviluppatore.
• Mantieni i numeri di versione della Versione di Prova e della Versione Completa identici. La piattaforma Jogos migrerà automaticamente i salvataggi dell'utente alla versione completa.
• Dopo un pagamento riuscito, viene restituito un numero d'ordine. Lo sviluppatore può utilizzare questo numero d'ordine per interrogare le informazioni relative a questo ordine.

// Restituisce il numero d'ordine in caso di successo
let orderNo = await window.JOGOS_SDK.payment.buyOut();

*Promemoria Importante*

Nota bene: Sia per la versione completa che per quella di prova, l'inizializzazione deve essere eseguita nella prima scena di avvio del progetto di gioco. Attendere che il callback sia completato prima di eseguire la prima riga del codice del tuo gioco. Jogos verifica durante l'inizializzazione se l'utente ha acquistato il tuo gioco; altrimenti, l'utente non potrà continuare a giocare. Questo è un mezzo efficace per proteggere il tuo gioco dalla pirateria e dall'uso da parte di utenti non autorizzati.