Rileva e pubblica articoli in-app

Questo argomento descrive come rilevare e distribuire i prodotti in-app nel gioco dopo che i giocatori li hanno acquistati con Play Points nell'app Google Play.

Una volta che gli utenti hanno riscattato i loro punti Play per un prodotto in-app nell'app Google Play, gli articoli devono essere consegnati immediatamente nel tuo gioco. Di seguito viene mostrato come un utente acquista articoli con i punti Play.

1. Fai clic su Play Points.	1. Fai clic sulla scheda Usa per visualizzare gli elementi.	2. Seleziona un articolo e fai clic su Usa punti per completare l'acquisto.	3. Ricevi l'articolo.

Nell'esempio, il gioco non è in esecuzione mentre il prodotto viene acquistato. Gli utenti possono anche scambiare punti Play con prodotti quando il gioco non è installato sul loro dispositivo. Per questo motivo, devi progettare il gioco in modo che gestisca la consegna degli articoli in-app al di fuori dello store in-game.

Prima di iniziare

Prima di rilevare e distribuire un prodotto in-app, devi creare il prodotto e le promozioni Play Points.

Requisiti di pubblicazione

Quando distribuisci prodotti in-app nel tuo gioco utilizzando una promozione Play Points, devi rispettare i requisiti di questa sezione.

Tempi di consegna

Quando un giocatore scambia punti Play con un prodotto in-app, devi consegnare l'articolo immediatamente senza richiedere al giocatore di riavviare il gioco. Nei casi in cui i contenuti di gioco devono essere completati in anticipo, ad esempio un tutorial, l'elemento deve essere consegnato immediatamente dopo.

Messaggio di consegna

Quando un utente torna al tuo gioco dopo aver acquistato un prodotto in-app al di fuori del gioco, devi mostrare una conferma che il prodotto è stato concesso correttamente all'interno del gioco. Il messaggio dovrebbe essere visualizzato sotto forma di finestra di dialogo popup o di messaggio in-game. Gli utenti non devono eseguire ulteriori passaggi per ricevere l'articolo.

Ecco il formato del messaggio richiesto:

• Un messaggio chiaro che indica che l'articolo è stato ricevuto.

• Fai riferimento chiaramente al nome dell'articolo e a "Punti Play" per assicurarti che gli utenti possano distinguerlo da altri contenuti che ricevono.

• Il nome dell'articolo deve includere anche la denominazione corretta se sono presenti articoli simili con più denominazioni.

• La finestra di dialogo popup, il messaggio o la notifica in-game devono essere visibili all'utente finché non fa clic su una conferma, ad esempio Continua o Ok. Non deve essere presente un pulsante Annulla, in quanto questo messaggio ha solo lo scopo di notificare agli utenti l'elemento che hanno ricevuto in-game. Se non è presente un pulsante di conferma, il messaggio deve essere visibile agli utenti per almeno 3 secondi prima di scomparire, per assicurarsi che gli utenti sappiano di aver ricevuto il proprio articolo.

Ecco un esempio di messaggio:

"Articolo ricevuto. Hai appena ricevuto 100 Gemme con Play Points. Continua."

Gli utenti dovrebbero vedere un'animazione o una conferma visiva che mostra l'aumento del saldo di valuta in-game. Se l'articolo è un articolo in-app durevole o consumabile, gli utenti devono essere indirizzati al punto in cui l'articolo è stato sbloccato o è disponibile all'interno del gioco.

Rilevare gli articoli ricevuti al di fuori del gioco

Se il tuo gioco utilizza la Libreria Fatturazione Google Play, apporta le seguenti modifiche per rilevare i prodotti in-app ricevuti al di fuori del gioco.

1. Nel callback onResume() del tuo gioco, chiama il metodo queryPurchases() per recuperare un elenco di elementi, in modo da poter determinare quali non sono stati riconosciuti.

2. Se il tuo gioco ha un server, ti consigliamo vivamente di verificare l'acquisto dal tuo server utilizzando l'API Subscriptions and In-App Purchases.

3. Se sono presenti articoli di proprietà ma non riconosciuti, conferma l'acquisto con consumeAsync() per gli articoli di consumo o con acknowledgePurchase() per gli articoli non di consumo.

4. Concedere il diritto all'articolo acquistato all'interno del gioco.

Rilevare gli elementi ricevuti in modalità schermo diviso

Se il tuo gioco supporta la modalità multi-finestra, gli utenti possono utilizzare i punti Play e ricevere l'articolo mentre eseguono contemporaneamente l'app Play Store e il tuo gioco. Questo screenshot mostra un esempio:

Per supportare questo scenario con la libreria Fatturazione Google Play, procedi nel seguente modo:

1. Google Play chiama il metodo onPurchasesUpdated() per comunicare al gioco che è presente un nuovo elemento in attesa.

2. Se il tuo gioco ha un server, ti consigliamo vivamente di verificare l'acquisto dal tuo server utilizzando l'API Subscriptions and In-App Purchases.

3. Conferma l'acquisto con consumeAsync() per gli articoli di consumo o con acknowledgePurchase() per gli articoli non di consumo.

4. Concedere il diritto all'articolo acquistato all'interno del gioco.

Visualizzare una conferma di consegna

Quando gli utenti riscattano punti Play e ricevono un articolo di scambio, si aspettano che il gioco mostri un messaggio in-game o utilizzi un tipo di notifica per informarli che il gioco ha ricevuto ed elaborato correttamente l'articolo. Ecco alcune opzioni di conferma della consegna:

• Mostrare un popup in-game.

• Invia il messaggio a una casella di messaggi in-game e indica chiaramente che è presente un nuovo messaggio nella casella di messaggi in-game.

• Utilizzare un messaggio di notifica del sistema operativo.

È possibile che il gioco si trovi in qualsiasi stato quando viene ricevuto l'articolo promozionale, incluso il caso in cui non sia installato sul dispositivo. Devi rilevare gli articoli promozionali indipendentemente dallo stato in cui si trova il gioco quando l'articolo viene ricevuto. Tuttavia, esistono alcune eccezioni in cui potrebbe essere accettabile non comunicare immediatamente all'utente che l'articolo è stato ricevuto. Ad esempio:

• Durante l'azione di gioco, quando la visualizzazione di un messaggio potrebbe distrarre l'utente. In questo caso, devi informare l'utente al termine dell'azione.

• Durante le cutscene, in cui la visualizzazione di un messaggio potrebbe distrarre l'utente. In questo caso, devi avvisare l'utente al termine della scena di intermezzo.

• Durante il tutorial iniziale e le parti di configurazione dell'utente del gioco. Ti consigliamo di notificare ai nuovi utenti la ricompensa immediatamente dopo l'apertura del gioco o durante la configurazione iniziale dell'utente. Tuttavia, è accettabile attendere che la sequenza di gioco principale sia disponibile per informare l'utente.

Se la tua app ha più personaggi o account a cui l'articolo potrebbe essere applicato, ti consigliamo di chiedere all'utente di selezionare l'account che riceve gli articoli promozionali.

Considera gli utenti quando decidi quando e come informarli degli articoli promozionali. Ogni volta che un utente non riceve immediatamente una notifica, potrebbe confondersi, smettere di giocare, contattare l'assistenza utenti o lamentarsi sui social media.

Aggiornamenti per motori di gioco specifici

Ecco alcune considerazioni da fare per motori di gioco specifici:

• Se il tuo gioco è creato con Unity, ti consigliamo di verificare se l'implementazione IAP che utilizzi supporta già le promozioni Play Points.

• Se il tuo gioco è creato con Cocos2d-x o Unreal Engine (C/C++), molto probabilmente dovrai scrivere il codice JNI che chiama le API Java dal tuo codice C/C++.

Best practice lato server

Questa sezione contiene le best practice lato server da utilizzare per le promozioni Play Points:

• Se chiami Purchases.products: get sul tuo server, verifica se devi gestire separatamente gli articoli di scambio delle ricompense di Play e altri prodotti in-app in base ai valori di productId.

• Se utilizzi Inappproducts: list sul tuo server, verifica se devi separare gli articoli di scambio di premi Play da altri prodotti in-app in base ai valori productId.

• Esamina le seguenti best practice per verificare se devi apportare ulteriori modifiche:

  • Riferimento:
    • Lotta contro frodi e comportamenti illeciti
    • Best practice per gli identificatori univoci
  • Implementa la verifica della firma lato server.
  • Assicurati che i valori di purchaseToken e orderId siano univoci e non siano stati utilizzati in precedenza.

Risoluzione dei problemi

Questa sezione contiene consigli per scenari che possono generare richieste dei clienti.

Più account utente

Se un utente ha più Account Google sul proprio dispositivo e riscatta Play Points sull'account sbagliato, Google non può trasferire gli articoli agli altri account. Allo stesso modo, la tua app non può trasferire l'elemento chiamando il metodo getPurchases(). In questo scenario, valuta la possibilità di fornire manualmente gli articoli in-app all'utente utilizzando le operazioni di assistenza clienti.

Articoli in ritardo o mancanti

Se i giocatori riscontrano ritardi o problemi con gli articoli premio, consulta la guida alla risoluzione dei problemi relativi agli acquisti in-app nella documentazione del Centro assistenza Google Play.