Integra Samsung IAP nel tuo gioco Unreal Engine 5

Galaxy Store, un app store predefinito in bundle con milioni di dispositivi Samsung Galaxy, è una delle principali destinazioni per i giocatori. Dispone di un sistema IAP (acquisto in-app) altamente personalizzabile che supporta tre tipi di articoli IAP:

• Materiali di consumo, che vengono utilizzati una volta e devono essere riacquistati per essere utilizzati nuovamente

• Non materiali di consumo, che hanno usi illimitati dopo l’acquisto

• Abbonamenti, che consentono utilizzi illimitati per una durata fissa

Il plug-in Samsung IAP supporta Unreal Engine, un motore di gioco 3D avanzato con grafica e funzionalità di nuova generazione, popolare tra gli sviluppatori di giochi professionisti. Unreal Engine 5 è ufficialmente supportato a partire dalla versione 6.1.4 del plug-in Samsung IAP, consentendoti di integrare Samsung IAP nei tuoi giochi Unreal Engine.

Questo articolo dimostra come integrare il plug-in Samsung IAP nei giochi Unreal Engine per consentire agli utenti di acquistare articoli IAP.

Prerequisiti

Il plug-in Samsung IAP versione 6.1.4 supporta le versioni Unreal Engine 4.18 e successive. Fondamentalmente, se i tuoi strumenti possono creare ed eseguire un gioco Unreal Engine 5 per dispositivi Android, puoi implementare le funzionalità del plug-in Samsung IAP nel tuo gioco.

La dimostrazione in questo articolo utilizza il seguente ambiente di sviluppo consigliato:

• Motore irreale 5.1

• Visual Studio 2022

• SDK Android:

Impostazione dell’ambiente di sviluppo

Per configurare il tuo progetto di gioco Unreal Engine per implementare il plug-in Samsung IAP:

1. Nelle impostazioni globali di Unreal Engine, verifica di aver definito la versione SDK di destinazione, la versione minima dell’SDK, la posizione dell’SDK Android, la posizione NDK Android, la posizione Java, il livello API SDK e il livello API NDK per il tuo progetto.
2. Apri un progetto Unreal Engine esistente o crea un nuovo progetto. Gli esempi di codice in questo articolo presuppongono un progetto C++ Unreal Engine.

3. Vai a Modifica > Impostazioni progetto > Piattaforme > Android e impostare le seguenti proprietà:

4. Scarica il plug-in Unreal IAP dal sito Web Samsung Developers.

   Estrai il contenuto del file scaricato in una cartella vuota all’interno del file Plugin* cartella della directory del progetto. Se la /Plugin/ la cartella non esiste, devi crearla.

   

   

   Figura 2: creare la cartella “Plugin”.

   

5. Nel /Origine// cartella, apri il file .build.cs file.

6. Per aggiungere il plugin Samsung IAP alle dipendenze del progetto, nel file PublicDependencyModuleNames.AddRange() sezione, aggiungere SamsungIAP alla lista:

   PublicDependencyModuleNames.AddRange(new string[] { "Core", "CoreUObject", "Engine", "InputCore", "EnhancedInput", "SamsungIAP" });
   

7. Per abilitare il plugin all’interno di Unreal Engine, riavvia Unreal Engine. Vai a Modifica > Plugin > Installati > Servizio e compila la casella di controllo accanto a Plug-in IAP Samsung.

8. Riavvia Unreal Engine per assicurarti che il plugin sia abilitato e pronto per l’uso nel tuo progetto.

   

   

   Figura 3: Abilita il plug-in Samsung IAP in Unreal Engine

   

Registrazione del gioco e degli elementi IAP

Prima che le funzionalità Samsung IAP possano essere integrate nel tuo gioco, il gioco e i suoi articoli IAP devono essere registrati nel Portale venditori del Samsung Galaxy Store:

1. In Unreal Engine, vai a Modifica > Impostazioni progetto > Piattaforme > Android e assicurati di aver definito il file Nome del pacchetto Android per il progetto e quello Inserisci i dati di gioco nel file .apk è abilitato.

2. Per creare il file .APK, nella barra degli strumenti di Unreal Engine, seleziona Piattaforme > Android > Progetto pacchetto.

3. Registra la tua applicazione di gioco nel Portale venditori del Samsung Galaxy Store, inserendo le informazioni richieste.

4. Nel Binario scheda del Portale venditori, carica il file APK del tuo gioco.

5. Per consentire di testare le funzionalità IAP durante lo sviluppo del gioco, crea un beta test chiuso. Nel Binario scheda, selezionare Aggiungi il beta-test e registra i tuoi tester e il canale di feedback per il beta test chiuso. Per ulteriori informazioni, vedere Test beta.

6. Nel Acquisto in app scheda, crea i tuoi articoli IAP e attivali. A scopo dimostrativo, il gioco in questo tutorial ha due oggetti consumabili: “buySuperSpeed” e “buySuperJump”.

7. Per salvare i dettagli del gioco e degli articoli IAP, seleziona Salva.

Per ulteriori informazioni sulla registrazione di applicazioni e articoli in-app, consulta Registrare un’app e articoli in-app nel Portale venditori.

Integrazione degli acquisti in-app

Ora che l’applicazione del gioco e i relativi elementi IAP sono stati registrati, puoi iniziare a implementare le funzionalità Samsung IAP nel tuo codice.

Passaggio 1: includi il file di intestazione

Per accedere alle funzioni Samsung IAP nel tuo progetto, devi aggiungere il file di intestazione al codice del progetto:

1. In Unreal Engine, seleziona Strumenti > Aggiorna progetto Visual Studio.

2. Per aprire e modificare il codice del progetto in Visual Studio, selezionare Strumenti > Apri Visual Studio.

3. Apri il file di codice C++ in cui desideri implementare le funzioni IAP.

4. Includi il file di intestazione del plug-in Samsung IAP nel tuo codice.

   #include "IAP.h"
   

Passaggio 2: impostare la modalità operativa IAP

Il plugin Samsung IAP ha tre modalità operative:

• IAP_MODE_TEST: per sviluppo e test.

• IAP_MODE_PRODUCTION: per versioni beta pubbliche e di produzione.

• IAP_MODE_TEST_FAILURE: per testare i casi di errore. In questa modalità, tutte le richieste restituiscono risposte di errore.

Impostare la modalità operativa utilizzando setOperationMode(<IAP MODE>) funzione. Poiché il gioco è in fase di sviluppo, utilizza “IAP_MODE_TEST”. IL #if PLATFORM_ANDROID La direttiva garantisce la compatibilità multipiattaforma compilando ed eseguendo il blocco di codice solo per la piattaforma Android, evitando errori che possono essere causati durante la compilazione per altre piattaforme.

#if PLATFORM_ANDROID
   samsung::IAP::setOperationMode(IAP_MODE_TEST);
#endif

Passaggio 3: crea e imposta una classe ascoltatore

La libreria Samsung IAP ha quattro funzioni API principali:

• getProductDetails() recupera un elenco di prodotti e i loro dettagli.

• getOwnedList() recupera un elenco degli elementi di proprietà dell’utente.

• startPayment() avvia un acquisto.

• consumePurchasedItems() consuma un oggetto acquistato.

Ognuna di queste funzioni richiede una funzione listener o callback che gestisce i dati restituiti dalla funzione di libreria IAP:

• onGetProducts() è l’ascoltatore per getProductDetails().

• onGetOwnedProducts() è l’ascoltatore per getOwnedList().

• onPayment() è l’ascoltatore per startPayment().

• onConsumePurchasedItems() è l’ascoltatore per consumePurchasedItems().

Crea una classe listener scheletro con queste funzioni di callback.

Negli esempi seguenti, una classe C++ denominata SamsungIAPListener è stato creato in Unreal Engine, generando il file SamsungIAPListener.cpp E SamsungIAPListener.h file nella directory di origine del progetto.

Nel SamsungIAPListener.h file, definire la classe:

#pragma once

#include "CoreMinimal.h"
#include "IAP.h"

class SamsungIAPListener : public samsung::IAPListener {
public:
   void onGetProducts(int result, const FString& msg, const std::vector<samsung::ProductVo>& data);
   void onGetOwnedProducts(int result, const FString& msg, const std::vector<samsung::OwnedProductVo>& data);
   void onPayment(int result, const FString& msg, const samsung::PurchaseVo& data);
   void onConsumePurchasedItems(int result, const FString& msg, const std::vector<samsung::ConsumeVo>& data);
};

Nel SamsungIAPListener.cpp file, crea il codice scheletro per le funzioni di callback:

#include "SamsungIAPListener.h"

using namespace std;
using namespace samsung;

#if PLATFORM_ANDROID
   void SamsungIAPListener::onGetProducts(int result, const FString& msg, const vector<ProductVo>& data) {

   }
   void SamsungIAPListener::onGetOwnedProducts(int result, const FString& msg, const vector<OwnedProductVo>& data) {

   }
   void SamsungIAPListener::onPayment(int result, const FString& msg, const PurchaseVo& data) {

   }
   void SamsungIAPListener::onConsumePurchasedItems(int result, const FString& msg, const vector<ConsumeVo>& data) {

   }

#endif

Nel file di codice principale, per impostare il file SamsungIAPListener classe listener appena creata come classe listener IAP per il progetto, utilizza il file setListener() funzione.

#include "SamsungIAPListener.h"

#if PLATFORM_ANDROID
   samsung::IAP::setOperationMode(IAP_MODE_TEST);
   samsung::IAP::setListener(new SamsungIAPListener);

#endif

Passaggio 4: recupera gli articoli acquistabili

Per recuperare l’elenco degli elementi IAP disponibili, utilizzare il file getProductDetails() funzione:

samsung::IAP::getProductDetails("");

La libreria IAP restituisce l’elenco degli elementi disponibili nei parametri del file onGetProducts() funzione di richiamata. IL dati variable contiene l’elenco da cui è possibile estrarre le variabili membro e gestirle in Unreal Engine secondo necessità.

Ad esempio, puoi utilizzare il file onGetProducts() funzione di richiamata per visualizzare l’elenco degli articoli disponibili e i relativi prezzi nel gioco:

void SamsungIAPListener::onGetProducts(int result, const FString& msg, const vector<ProductVo>& data) {
   for (auto& i : data) {
      printMessage(FString::Printf(TEXT("%s Price = %s"), *i.mItemName, *i.mItemPriceString));
   }
}

Figura 4: elenco degli elementi disponibili recuperati

Puoi anche recuperare i dettagli di un articolo specifico inserendo il relativo ID articolo nel parametro stringa del file getProductDetails() funzione. Per esempio, getProductDetails("buySuperJump") recupera solo i dettagli per il acquistareSuperJump articolo.

Passaggio 5: recupera gli oggetti posseduti

Per garantire che gli articoli IAP acquistati in precedenza dall’utente siano disponibili nel gioco, all’avvio del gioco, recuperare l’elenco degli articoli di sua proprietà utilizzando il pulsante getOwnedList() funzione:

samsung::IAP::getOwnedList(PRODUCT_TYPE_ALL);

IL onGetOwnedProducts() la funzione di callback riceve l’elenco degli elementi posseduti. Puoi usarlo per eseguire attività come ripristinare le funzionalità degli oggetti acquistati nel gioco e controllare e consumare eventuali oggetti consumabili nell’account dell’utente che non sono stati ancora consumati. È importante consumare gli oggetti consumabili il prima possibile, perché non possono essere riacquistati finché non vengono consumati.

void SamsungIAPListener::onGetOwnedProducts(int result, const FString& msg, const vector<OwnedProductVo>& data) {
   if (data.size() == 0) {
      printMessage(FString::Printf(TEXT("No previously owned items")));
   }
   else {
      for (auto& i : data) {
         samsung::IAP::consumePurchasedItems(*i.mPurchaseId);
         printMessage(FString::Printf(TEXT("Consuming Owned Item: %s"), *i.mItemName));
      }
   }
}

Passaggio 6: acquistare articoli

Avvia l’acquisto di un articolo con startPayment() funzione. In questo esempio, l’utente desidera acquistare l’articolo con l’ID articolo “buySuperJump:”

samsung::IAP::startPayment("buySuperJump", "pass_through_value", true);

Quando viene richiamata la funzione, lo schermo passa alla modalità verticale e visualizza l’interfaccia utente del pagamento. L’utente seleziona il metodo di pagamento e conferma il pagamento. Quando Galaxy Store elabora correttamente il pagamento, l’articolo viene aggiunto all’elenco degli articoli di proprietà dell’utente. Per verificare se l’articolo è stato aggiunto all’elenco degli articoli di proprietà dell’utente, puoi utilizzare il file getOwnedList() funzione.

Figura 5: interfaccia utente di Samsung IAP Checkout

Ricorda che gli oggetti consumabili rimangono nell’elenco degli oggetti di proprietà dell’utente e non possono essere riacquistati finché l’oggetto non viene consumato. Idealmente, applica l’effetto di gioco dell’oggetto e consumalo non appena viene acquistato. Dal momento che il risultato del startPayment() la funzione viene restituita a onPayment() funzione di richiamata, è possibile estendere questa funzione di richiamata per eseguire attività con l’articolo dopo aver completato il pagamento.

Nel nostro gioco di esempio, la variabile saltoAltezza è impostato su 500. Quando l’utente acquista l’oggetto “buySuperJump”, l’altezza del salto viene raddoppiata. Questo effetto di gioco può essere implementato all’interno del onPayment() funzione di richiamata.

void SamsungIAPListener::onPayment(int result, const FString& msg, const PurchaseVo& data) {
   FString sJump = TEXT("buySuperJump");
   if(sJump.Equals(*data.mItemId)){
      jumpHeight = 1000;
      superJumpsAvailable++;
      samsung::IAP::consumePurchasedItems(*data.mPurchaseId);
      printMessage(FString::Printf(TEXT("Super Jump Purchased")));
   }
}

Passaggio 7: consuma gli oggetti acquistati

Per consumare un articolo acquistato in precedenza, devi prima recuperare il suo ID di acquisto. L’ID acquisto è reperibile all’interno del file dati variabile nella funzione di callback per il startPayment() E getOwnedList() funzioni. Puoi implementare il consumo dell’elemento direttamente dalla funzione di callback con il comando consumePurchasedItems() funzione, allo stesso modo di quanto precedentemente dimostrato.

samsung::IAP::consumePurchasedItems(*data.mPurchaseId);

Quando un oggetto viene consumato tramite il consumePurchasedItems() funzione, il onConsumePurchasedItems() viene attivata la funzione di callback. In questa funzione di richiamata, assicurati che il risultato dell’acquisto sia stato archiviato localmente prima che l’articolo IAP venga consumato e rimosso dall’elenco degli articoli di proprietà dell’utente.

void SamsungIAPListener::onConsumePurchasedItems(int result, const FString& msg, const vector<ConsumeVo>& data) {
   for (auto& i : data) {
      printMessage(FString::Printf(TEXT("Item Successfully Consumed")));
   }
}

Risultati e sintesi

Con la funzionalità Samsung IAP completamente integrata nel nostro gioco Unreal Engine di esempio, possiamo testare la funzionalità IAP all’interno del gioco.

L’acquisto dell’oggetto “buySuperJump” attiva una catena di funzioni della libreria IAP che acquisisce l’oggetto e lo consuma per implementare il suo effetto di gioco:

1. startPayment() la funzione avvia il processo di pagamento.

2. onPayment() la funzione di callback reagisce al pagamento andato a buon fine:

   UN. Modifica l’altezza di salto dell’utente nel gioco in 1000.

   B. Visualizza il messaggio “Super Jump acquistato”.

   C. Chiama il consumePurchasedItems() funzione.

3. consumePurchasedItems() la funzione consuma l’oggetto acquistato, rimuovendolo dagli articoli di proprietà dell’utente.

4. onConsumePurchasedItems() la funzione di callback reagisce al consumo dell’oggetto, visualizzando il messaggio “Articolo consumato con successo”.

Figura 6: oggetto “buySuperJump” acquistato e consumato con successo

Questa dimostrazione ha dimostrato quanto sia facile integrare Samsung IAP in un gioco Unreal Engine 5. Con solo poche funzioni di libreria, puoi implementare qualsiasi funzionalità Samsung IAP che desideri nei giochi realizzati con Unreal Engine.

Per saperne di più su come funziona Samsung IAP, consulta il nostro articolo precedente Integrazione dei servizi Samsung IAP nelle app Android. Se hai domande o hai bisogno di aiuto con le informazioni contenute in questo articolo, puoi condividere le tue domande sul Samsung Developers Forum.