Integra la Libreria Fatturazione Google Play nella tua app

Nota: prima di leggere questo argomento, assicurati di aver letto la documentazione del Centro assistenza Play Console, che descrive i concetti fondamentali relativi agli acquisti, nonché come creare e configurare i prodotti in vendita. Inoltre, assicurati di aver configurato in anticipo la configurazione di Google Play seguendo i passaggi descritti in Preparazione.

Questo argomento descrive come integrare la Libreria Fatturazione Google Play nella tua app per iniziare a vendere prodotti.

Durata di un acquisto

Di seguito è riportato un flusso di acquisto tipico per un acquisto una tantum o un abbonamento.

1. Mostra all'utente cosa può acquistare.
2. Avvia la procedura di acquisto per consentire all'utente di accettare l'acquisto.
3. Verifica l'acquisto sul tuo server.
4. Fornire contenuti all'utente.
5. Conferma l'invio dei contenuti. Per i prodotti di consumo, consuma l'acquisto in modo che l'utente possa acquistare di nuovo l'articolo.

Gli abbonamenti si rinnovano automaticamente finché non vengono annullati. Un abbonamento può essere in uno dei seguenti stati:

• Attivo: l'utente è in regola e ha accesso all'abbonamento.
• Annullato: l'utente ha annullato l'abbonamento, ma ha ancora accesso fino alla scadenza.
• In periodo di tolleranza: l'utente ha riscontrato un problema di pagamento, ma ha ancora accesso mentre Google riprova a utilizzare il metodo di pagamento.
• In attesa: l'utente ha riscontrato un problema di pagamento e non ha più accesso mentre Google sta riprovando a utilizzare il metodo di pagamento.
• In pausa: l'utente ha messo in pausa il proprio accesso e non ha accesso finché non lo riprende.
• Scaduto: l'utente ha annullato l'abbonamento e ha perso l'accesso. L'utente viene considerato churned alla scadenza.

Inizializzare una connessione a Google Play

Il primo passaggio per l'integrazione con il sistema di fatturazione di Google Play consiste nell'aggiungere la Libreria Fatturazione Google Play alla tua app e nell'inizializzare una connessione.

Aggiungi la dipendenza della Libreria Fatturazione Google Play

Nota: se hai seguito la guida Preparazione, hai già aggiunto le dipendenze necessarie e puoi passare alla sezione successiva.

Aggiungi la dipendenza della Libreria Fatturazione Google Play al file build.gradle della tua app come mostrato:

Groovy

dependencies {
    def billing_version = "7.0.0"

    implementation "com.android.billingclient:billing:$billing_version"
}

Kotlin

dependencies {
    val billing_version = "7.0.0"

    implementation("com.android.billingclient:billing:$billing_version")
}

Se utilizzi Kotlin, il modulo KTX della Libreria Fatturazione Google Play contiene estensioni Kotlin e il supporto delle coroutine che ti consentono di scrivere Kotlin idiomatico quando utilizzi la Libreria Fatturazione Google Play. Per includere queste estensioni nel progetto, aggiungi la seguente dipendenza al file build.gradle dell'app, come mostrato:

Groovy

dependencies {
    def billing_version = "7.0.0"

    implementation "com.android.billingclient:billing-ktx:$billing_version"
}

Kotlin

dependencies {
    val billing_version = "7.0.0"

    implementation("com.android.billingclient:billing-ktx:$billing_version")
}

Inizializzare un BillingClient

Dopo aver aggiunto una dipendenza alla Libreria Fatturazione Google Play, devi inizializzare un'istanza BillingClient. BillingClient è l'interfaccia principale per la comunicazione tra la Libreria Fatturazione Google Play e il resto dell'app. BillingClient fornisce metodi di utilità, sia sincroni che asincroni, per molte operazioni di fatturazione comuni. Prendi nota di quanto segue:

• Ti consigliamo di avere una connessione BillingClient attiva aperta alla volta per evitare più callback PurchasesUpdatedListener per un singolo evento.
• Ti consigliamo di avviare una connessione per BillingClient quando l'app viene lanciata o viene messa in primo piano per assicurarti che elabori gli acquisti in modo tempestivo. Questo può essere ottenuto utilizzando ActivityLifecycleCallbacks registrato da registerActivityLifecycleCallbacks e ascoltando onActivityResumed per inizializzare una connessione quando rilevi per la prima volta la ripresa di un'attività. Per ulteriori dettagli sul motivo per cui è consigliabile seguire questa best practice, consulta la sezione sull'elaborazione degli acquisti. Ricordati inoltre di terminare la connessione quando l'app è chiusa.

Per creare un BillingClient, utilizza newBuilder. Puoi passare qualsiasi contesto a newBuilder(), che lo utilizza per ottenere un contesto dell'applicazione.BillingClient Ciò significa che non devi preoccuparti di perdite di memoria. Per ricevere aggiornamenti sugli acquisti, devi anche chiamare setListener, passando un riferimento a un PurchasesUpdatedListener. Questo ascoltatore riceve aggiornamenti per tutti gli acquisti effettuati nella tua app.

Kotlin

private val purchasesUpdatedListener =
   PurchasesUpdatedListener { billingResult, purchases ->
       // To be implemented in a later section.
   }

private var billingClient = BillingClient.newBuilder(context)
   .setListener(purchasesUpdatedListener)
   // Configure other settings.
   .build()

Java

private PurchasesUpdatedListener purchasesUpdatedListener = new PurchasesUpdatedListener() {
    @Override
    public void onPurchasesUpdated(BillingResult billingResult, List<Purchase> purchases) {
        // To be implemented in a later section.
    }
};

private BillingClient billingClient = BillingClient.newBuilder(context)
    .setListener(purchasesUpdatedListener)
    // Configure other settings.
    .build();

Nota: la Libreria Fatturazione Google Play restituisce errori sotto forma di BillingResult. Un BillingResult contiene un BillingResponseCode, che classifica i possibili errori relativi alla fatturazione che la tua app può riscontrare. Ad esempio, se ricevi un codice di errore SERVICE_DISCONNECTED, la tua app dovrebbe inizializzare di nuovo la connessione con Google Play. Inoltre, un messaggio BillingResult contiene un messaggio di debug, utile durante lo sviluppo per diagnosticare gli errori.

Collegarti a Google Play

Dopo aver creato un BillingClient, devi stabilire una connessione con Google Play.

Per collegarti a Google Play, chiama startConnection. Il processo di connessione è asincrono e devi implementare un BillingClientStateListener per ricevere un callback una volta completata la configurazione del client e quando è pronto per effettuare ulteriori richieste.

Devi anche implementare la logica di ripetizione per gestire le connessioni perse a Google Play. Per implementare la logica di ripetizione, sostituisci il metodo di callback onBillingServiceDisconnected() e assicurati che BillingClient chiami il metodo startConnection() per riconnettersi a Google Play prima di effettuare ulteriori richieste.

L'esempio seguente mostra come avviare una connessione e verificare che sia pronta per l'uso:

Kotlin

billingClient.startConnection(object : BillingClientStateListener {
    override fun onBillingSetupFinished(billingResult: BillingResult) {
        if (billingResult.responseCode ==  BillingResponseCode.OK) {
            // The BillingClient is ready. You can query purchases here.
        }
    }
    override fun onBillingServiceDisconnected() {
        // Try to restart the connection on the next request to
        // Google Play by calling the startConnection() method.
    }
})

Java

billingClient.startConnection(new BillingClientStateListener() {
    @Override
    public void onBillingSetupFinished(BillingResult billingResult) {
        if (billingResult.getResponseCode() ==  BillingResponseCode.OK) {
            // The BillingClient is ready. You can query purchases here.
        }
    }
    @Override
    public void onBillingServiceDisconnected() {
        // Try to restart the connection on the next request to
        // Google Play by calling the startConnection() method.
    }
});

Nota: ti consigliamo vivamente di implementare la tua logica di ripetizione della connessione e di eseguire l'override del metodo onBillingServiceDisconnected(). Assicurati di mantenere la connessione BillingClient durante l'esecuzione di qualsiasi metodo.

Mostrare i prodotti disponibili per l'acquisto

Dopo aver stabilito una connessione a Google Play, puoi eseguire query per i prodotti disponibili e mostrarli agli utenti.

La query per i dettagli del prodotto è un passaggio importante prima di mostrare i prodotti agli utenti, in quanto restituisce informazioni sui prodotti localizzate. Per gli abbonamenti, assicurati che la visualizzazione del prodotto rispetti tutte le norme di Play.

Per eseguire una query sui dettagli dei prodotti in-app, chiama queryProductDetailsAsync.

Per gestire il risultato dell'operazione asincrona, devi anche specificare un ascoltatore che implementi l'interfaccia ProductDetailsResponseListener. Puoi quindi sostituire onProductDetailsResponse, che invia una notifica all'ascoltatore al termine della query, come mostrato nell'esempio seguente:

Kotlin

val queryProductDetailsParams =
    QueryProductDetailsParams.newBuilder()
        .setProductList(
            ImmutableList.of(
                Product.newBuilder()
                    .setProductId("product_id_example")
                    .setProductType(ProductType.SUBS)
                    .build()))
        .build()

billingClient.queryProductDetailsAsync(queryProductDetailsParams) {
    billingResult,
    productDetailsList ->
      // check billingResult
      // process returned productDetailsList
}

Java

QueryProductDetailsParams queryProductDetailsParams =
    QueryProductDetailsParams.newBuilder()
        .setProductList(
            ImmutableList.of(
                Product.newBuilder()
                    .setProductId("product_id_example")
                    .setProductType(ProductType.SUBS)
                    .build()))
        .build();

billingClient.queryProductDetailsAsync(
    queryProductDetailsParams,
    new ProductDetailsResponseListener() {
        public void onProductDetailsResponse(BillingResult billingResult,
                List<ProductDetails> productDetailsList) {
            // check billingResult
            // process returned productDetailsList
        }
    }
)

Quando esegui una query per i dettagli del prodotto, passa un'istanza di QueryProductDetailsParams che specifica un elenco di stringhe ID prodotto create in Google Play Console insieme a un ProductType. ProductType può essere ProductType.INAPP per i prodotti a pagamento singolo o ProductType.SUBS per gli abbonamenti.

Esegui query con le estensioni Kotlin

Se utilizzi le estensioni Kotlin, puoi eseguire query sui dettagli dei prodotti in-app chiamando la funzione di estensione queryProductDetails().

queryProductDetails() sfrutta le coroutine Kotlin in modo da non dover definire un ascoltatore separato. La funzione viene invece sospesa fino al completamento della query, dopodiché puoi elaborare il risultato:

suspend fun processPurchases() {
    val productList = listOf(
        QueryProductDetailsParams.Product.newBuilder()
            .setProductId("product_id_example")
            .setProductType(BillingClient.ProductType.SUBS)
            .build()
    )
    val params = QueryProductDetailsParams.newBuilder()
    params.setProductList(productList)

    // leverage queryProductDetails Kotlin extension function
    val productDetailsResult = withContext(Dispatchers.IO) {
        billingClient.queryProductDetails(params.build())
    }

    // Process the result.
}

In rari casi, alcuni dispositivi non sono in grado di supportare ProductDetails e queryProductDetailsAsync(), in genere a causa di versioni obsolete di Google Play Services. Per garantire un'assistenza adeguata per questo scenario, scopri come utilizzare le funzionalità di compatibilità con le versioni precedenti nella guida alla migrazione a Libreria Fatturazione Play 5.

Elabora il risultato

La Libreria Fatturazione Google Play memorizza i risultati della query in un List di oggetti ProductDetails. Puoi quindi chiamare una serie di metodi su ogni oggetto ProductDetails nell'elenco per visualizzare informazioni pertinenti su un prodotto in-app, ad esempio il prezzo o la descrizione. Per visualizzare le informazioni dettagliate sul prodotto disponibili, consulta l'elenco dei metodi nella classe ProductDetails.

Prima di mettere in vendita un articolo, controlla che l'utente non lo possieda già. Se l'utente ha un articolo consumabile ancora nella sua raccolta di articoli, deve consumarlo prima di poterlo acquistare di nuovo.

Prima di offrire un abbonamento, verifica che l'utente non abbia già un abbonamento. Tieni inoltre presente quanto segue:

• queryProductDetailsAsync() restituisce i dettagli del prodotto dell'abbonamento e un massimo di 50 offerte per abbonamento.
• queryProductDetailsAsync() restituisce solo le offerte per le quali l'utente è idoneo. Se l'utente tenta di acquistare un'offerta per la quale non è idoneo (ad esempio, se l'app mostra un elenco obsoleto di offerte idonee), Google Play lo informa che non è idoneo e l'utente può scegliere di acquistare il piano base.

Nota: alcuni dispositivi Android potrebbero avere una versione precedente dell'app Google Play Store che non supporta determinati tipi di prodotti, come gli abbonamenti. Prima che la tua app entri nel flusso di fatturazione, puoi chiamare isFeatureSupported() per determinare se il dispositivo supporta i prodotti che vuoi vendere. Per un elenco di tipi di prodotti che possono essere supportati, consulta BillingClient.FeatureType.

Avvia il flusso di acquisto

Per avviare una richiesta di acquisto dalla tua app, chiama il metodo launchBillingFlow() dal thread principale dell'app. Questo metodo prende un riferimento a un oggetto BillingFlowParams contenente l'oggetto ProductDetails pertinente ottenuto dalla chiamata queryProductDetailsAsync. Per creare un oggetto BillingFlowParams, utilizza la classe BillingFlowParams.Builder.

Nota: il metodo setOfferToken non deve essere chiamato per i prodotti a pagamento singolo quando si avvia il flusso di acquisto.

Kotlin

// An activity reference from which the billing flow will be launched.
val activity : Activity = ...;

val productDetailsParamsList = listOf(
    BillingFlowParams.ProductDetailsParams.newBuilder()
        // retrieve a value for "productDetails" by calling queryProductDetailsAsync()
        .setProductDetails(productDetails)
        // For One-time products, "setOfferToken" method shouldn't be called.
        // For subscriptions, to get an offer token, call ProductDetails.subscriptionOfferDetails()
        // for a list of offers that are available to the user
        .setOfferToken(selectedOfferToken)
        .build()
)

val billingFlowParams = BillingFlowParams.newBuilder()
    .setProductDetailsParamsList(productDetailsParamsList)
    .build()

// Launch the billing flow
val billingResult = billingClient.launchBillingFlow(activity, billingFlowParams)

Java

// An activity reference from which the billing flow will be launched.
Activity activity = ...;

ImmutableList<ProductDetailsParams> productDetailsParamsList =
    ImmutableList.of(
        ProductDetailsParams.newBuilder()
             // retrieve a value for "productDetails" by calling queryProductDetailsAsync()
            .setProductDetails(productDetails)
            // For one-time products, "setOfferToken" method shouldn't be called.
            // For subscriptions, to get an offer token, call
            // ProductDetails.subscriptionOfferDetails() for a list of offers
            // that are available to the user.
            .setOfferToken(selectedOfferToken)
            .build()
    );

BillingFlowParams billingFlowParams = BillingFlowParams.newBuilder()
    .setProductDetailsParamsList(productDetailsParamsList)
    .build();

// Launch the billing flow
BillingResult billingResult = billingClient.launchBillingFlow(activity, billingFlowParams);

Il metodo launchBillingFlow() restituisce uno dei diversi codici di risposta elencati in BillingClient.BillingResponseCode. Assicurati di controllare questo risultato per verificare che non siano stati rilevati errori durante il lancio del flusso di acquisto. Un valore BillingResponseCode di OK indica un lancio riuscito.

Se la chiamata a launchBillingFlow() va a buon fine, il sistema mostra la schermata di acquisto di Google Play. La figura 1 mostra una schermata di acquisto di un abbonamento:

Figura 1. Nella schermata di acquisto di Google Play viene mostrato un abbonamento disponibile per l'acquisto.

Google Play chiama onPurchasesUpdated() per inviare il risultato dell'operazione di acquisto a un listener che implementa l'interfaccia PurchasesUpdatedListener. L'ascoltatore viene specificato utilizzando il metodo setListener() quando hai inizializzato il client.

Devi implementare onPurchasesUpdated() per gestire i possibili codici di risposta. L'esempio seguente mostra come eseguire l'override di onPurchasesUpdated():

Kotlin

override fun onPurchasesUpdated(billingResult: BillingResult, purchases: List<Purchase>?) {
   if (billingResult.responseCode == BillingResponseCode.OK && purchases != null) {
       for (purchase in purchases) {
           // Process the purchase as described in the next section.
       }
   } else if (billingResult.responseCode == BillingResponseCode.USER_CANCELED) {
       // Handle an error caused by a user canceling the purchase flow.
   } else {
       // Handle any other error codes.
   }
}

Java

@Override
void onPurchasesUpdated(BillingResult billingResult, List<Purchase> purchases) {
    if (billingResult.getResponseCode() == BillingResponseCode.OK
        && purchases != null) {
        for (Purchase purchase : purchases) {
            // Process the purchase as described in the next section.
        }
    } else if (billingResult.getResponseCode() == BillingResponseCode.USER_CANCELED) {
        // Handle an error caused by a user canceling the purchase flow.
    } else {
        // Handle any other error codes.
    }
}

Un acquisto riuscito genera una schermata di conferma dell'acquisto su Google Play simile alla figura 2.

Figura 2. Schermata di conferma dell'acquisto su Google Play.

Un acquisto riuscito genera anche un token di acquisto, ovvero un identificatore univoco che rappresenta l'utente e l'ID prodotto del prodotto in-app acquistato. Le tue app possono memorizzare il token di acquisto localmente, anche se consigliamo vivamente di passare il token al tuo server di backend sicuro, dove puoi verificare l'acquisto e proteggerti dalle attività fraudolente. Questa procedura è descritta ulteriormente in Rilevare ed elaborare gli acquisti.

L'utente riceve anche una ricevuta della transazione via email contenente un ID ordine o un ID transazione univoco. Gli utenti ricevono un'email con un ID ordine univoco per ogni acquisto di prodotto una tantum, nonché per l'acquisto iniziale dell'abbonamento e i successivi rinnovi automatici ricorrenti. Puoi utilizzare l'ID ordine per gestire i rimborsi in Google Play Console.

Indicare un prezzo personalizzato

Se la tua app può essere distribuita agli utenti nell'Unione Europea, utilizza il metodo setIsOfferPersonalized() quando chiami launchBillingFlow per comunicare agli utenti che il prezzo di un articolo è stato personalizzato utilizzando il processo decisionale automatico.

Figura 3. La schermata di acquisto di Google Play che indica che il prezzo è stato personalizzato per l'utente.

Devi consultare l'articolo 6 (1) (ea) CRD della direttiva sui diritti dei consumatori 2011/83/UE per stabilire se il prezzo che offri agli utenti è personalizzato.

setIsOfferPersonalized() accetta un input booleano. Quando true, l'interfaccia utente di Google Play include l'informativa. Quando false, l'UI omette l'informativa. Il valore predefinito è false.

Per ulteriori informazioni, consulta il Centro assistenza per i consumatori.

Allega identificatori utente

Quando avvii il flusso di acquisto, la tua app può associare qualsiasi identificatore utente di cui disponi all'utente che effettua l'acquisto utilizzando obfuscatedAccountId o obfuscatedProfileId. Un esempio di identificatore potrebbe essere una versione offuscata dell'accesso dell'utente nel tuo sistema. L'impostazione di questi parametri può aiutare Google a rilevare attività fraudolente. Inoltre, può aiutarti ad assicurarti che gli acquisti vengano attribuiti all'utente giusto, come spiegato nella sezione Concedere i diritti agli utenti.

Rileva ed elabora gli acquisti

Il rilevamento e l'elaborazione di un acquisto descritti in questa sezione sono applicabili a tutti i tipi di acquisti, inclusi quelli al di fuori dell'app, come i riscatti di promozioni.

La tua app rileva i nuovi acquisti e gli acquisti in attesa completati in uno dei seguenti modi:

1. Quando onPurchasesUpdated viene chiamato in seguito alla chiamata da parte della tua app di launchBillingFlow (come descritto nella sezione precedente) o se la tua app è in esecuzione con una connessione alla Libreria Fatturazione attiva quando viene effettuato un acquisto al di fuori della tua app o viene completato un acquisto in attesa. Ad esempio, un membro del gruppo Famiglia approva un acquisto in attesa su un altro dispositivo.
2. Quando la tua app chiama queryPurchasesAsync per eseguire query sugli acquisti dell'utente.

Per il punto 1, onPurchasesUpdated verrà chiamato automaticamente per gli acquisti nuovi o completati, purché l'app sia in esecuzione e disponga di una connessione alla libreria di fatturazione di Google Play attiva. Se l'applicazione non è in esecuzione o se l'app non ha un collegamento attivo alla Libreria Fatturazione Google Play, onPurchasesUpdated non verrà invocato. Ricorda che è consigliabile che la tua app cerchi di mantenere una connessione attiva finché è in primo piano per assicurarsi che riceva aggiornamenti tempestivi sugli acquisti.

Per il punto 2, devi chiamare BillingClient.queryPurchasesAsync() per assicurarti che la tua app elabori tutti gli acquisti. Ti consigliamo di eseguire questa operazione quando la tua app stabilisce una connessione con la Libreria Fatturazione Google Play (operazione consigliata quando l'app viene lanciata o viene attivata in primo piano come discusso in Eseguire l'inizializzazione di un BillingClient. Questo può essere ottenuto chiamando queryPurchasesAsync quando si riceve un risultato positivo per onServiceConnected. Seguire questo consiglio è fondamentale per gestire eventi e situazioni come:

• Problemi di rete durante l'acquisto: un utente può effettuare un acquisto corretto e ricevere una conferma da Google, ma il suo dispositivo perde la connettività di rete prima che il dispositivo e la tua app ricevano la notifica dell'acquisto tramite il PurchasesUpdatedListener.
• Più dispositivi: un utente potrebbe acquistare un articolo su un dispositivo e poi aspettarsi di visualizzarlo quando cambia dispositivo.
• Gestione degli acquisti effettuati al di fuori della tua app: alcuni acquisti, come i redemption di promozioni, possono essere effettuati al di fuori della tua app.
• Gestione delle transizioni dello stato di acquisto: un utente potrebbe completare il pagamento di un acquisto in stato PENDING mentre la tua applicazione non è in esecuzione e aspettarsi di ricevere conferma di aver completato l'acquisto quando apre la tua app.

Nota: puoi anche scegliere di ascoltare le notifiche in tempo reale per lo sviluppatore per conoscere in tempo reale i nuovi acquisti e quelli completati in attesa, anche se l'utente non utilizza la tua app quando si verifica l'evento. In questo modo, lo stato del backend rimane sempre sincronizzato. Questo aspetto è descritto in maggiore dettaglio nella sezione sull'integrazione del backend per gli acquisti una tantum e gli abbonamenti.

Quando l'app rileva un acquisto nuovo o completato, deve:

• Verifica l'acquisto.
• Concedi all'utente i contenuti per gli acquisti completati.
• Avvisa l'utente.
• Comunica a Google che la tua app ha elaborato gli acquisti completati.

Questi passaggi sono descritti in dettaglio nelle sezioni seguenti, seguite da una sezione di riepilogo di tutti i passaggi.

Verificare l'acquisto

La tua app deve sempre verificare gli acquisti per assicurarsi che siano legittimi prima di concedere vantaggi a un utente. Per farlo, segui le linee guida descritte in Verificare gli acquisti prima di concedere i diritti. Solo dopo aver verificato l'acquisto, l'app deve continuare a elaborarlo e concedere i diritti all'utente, come descritto nella sezione successiva.

Concedi il diritto all'utente

Una volta verificata l'avvenuta esecuzione di un acquisto, l'app può continuare a concedere il diritto all'utente e inviargli una notifica. Prima di concedere il diritto, assicurati che la tua app controlli che lo stato dell'acquisto sia PURCHASED. Se l'acquisto è in stato PENDING, la tua app deve informare l'utente che deve ancora completare alcune azioni per completare l'acquisto prima che venga concesso il diritto. Concedi il diritto solo quando lo stato dell'acquisto passa da PENDING a SUCCESS. Per ulteriori informazioni, consulta Gestione delle transazioni in sospeso.

Se hai allegato identificatori utente all'acquisto, come descritto nella sezione Allega identificatori utente, puoi recuperarli e utilizzarli per attribuire l'acquisto all'utente corretto nel tuo sistema. Questa tecnica è utile per riconciliare gli acquisti se la tua app potrebbe aver perso il contesto relativo all'utente a cui è destinato un acquisto. Tieni presente che gli acquisti effettuati al di fuori della tua app non avranno questi identificatori impostati. In questo caso, la tua app può concedere il diritto all'utente che ha eseguito l'accesso o chiedere all'utente di selezionare un account preferito.

Avvisare l'utente

Dopo aver concesso il diritto all'utente, l'app deve mostrare una notifica per confermare l'avvenuto acquisto. In questo modo, l'utente non ha dubbi sul fatto che l'acquisto sia andato a buon fine, il che potrebbe portarlo a smettere di utilizzare la tua app, a contattare l'assistenza utenti o a presentare un reclamo sui social media. Tieni presente che la tua app potrebbe rilevare gli aggiornamenti degli acquisti in qualsiasi momento durante il ciclo di vita dell'applicazione. Ad esempio, un genitore approva un acquisto in attesa su un altro dispositivo. In questo caso, l'app potrebbe voler ritardare l'invio della notifica all'utente in un momento opportuno. Ecco alcuni esempi in cui un ritardo sarebbe appropriato:

• Durante la parte di azione di un gioco o delle scene tagliate, la visualizzazione di un messaggio potrebbe distrarre l'utente. In questo caso, devi informare l'utente al termine della parte di azione.
• Durante le parti iniziali del tutorial e della configurazione dell'utente del gioco. Ad esempio, un utente potrebbe aver effettuato un acquisto al di fuori della tua app prima di installarla. Ti consigliamo di informare i nuovi utenti del premio subito dopo l'apertura del gioco o durante la configurazione iniziale dell'utente. Se la tua app richiede all'utente di creare un account o di accedere prima di concedere il diritto, ti consigliamo di comunicare all'utente i passaggi da completare per richiedere il suo acquisto. Questo è fondamentale perché gli acquisti vengono rimborsati dopo 3 giorni se la tua app non li ha elaborati.

Quando si informa l'utente di un acquisto, Google Play consiglia i seguenti meccanismi:

• Mostra una finestra di dialogo in-app.
• Invia il messaggio a una casella di messaggio in-app e indica chiaramente che c'è un nuovo messaggio nella casella di messaggio in-app.
• Utilizza un messaggio di notifica del sistema operativo.

La notifica deve informare l'utente del vantaggio ricevuto. Ad esempio: "Hai acquistato 100 monete d'oro". Inoltre, se l'acquisto è stato risultato di un vantaggio di un programma come Play Pass, la tua app lo comunicherà all'utente. Ad esempio, "Articolo ricevuto! Hai appena ricevuto 100 gemme con Play Pass. Continua." Ogni programma potrebbe avere indicazioni sul testo consigliato da mostrare agli utenti per comunicare i vantaggi.

Comunica a Google l'elaborazione dell'acquisto

Dopo che l'app ha concesso il diritto all'utente e lo ha informato della transazione riuscita, deve notificare a Google che l'acquisto è stato elaborato correttamente. Questo viene fatto confermando l'acquisto ed deve essere eseguito entro tre giorni per assicurarsi che l'acquisto non venga rimborsato automaticamente e il diritto revocato. La procedura per confermare i diversi tipi di acquisti è descritta nelle sezioni seguenti.

Prodotti di consumo

Per i consumi, se la tua app dispone di un backend sicuro, ti consigliamo di utilizzare Purchases.products:consume per consumare gli acquisti in modo affidabile. Assicurati che l'acquisto non sia già stato utilizzato controllando il valore consumptionState del risultato della chiamata a Purchases.products:get. Se la tua app è solo client senza un backend, utilizza consumeAsync() della Libreria Fatturazione Google Play. Entrambi i metodi soddisfano il requisito di conferma e indicano che la tua app ha concesso il diritto all'utente. Questi metodi consentono inoltre alla tua app di rendere disponibile per il riacquisto il prodotto una tantum corrispondente al token di acquisto inserito. Con consumeAsync() devi anche passare un oggetto che implementa l'interfaccia ConsumeResponseListener. Questo oggetto gestisce il risultato dell'operazione di consumo. Puoi override il metodo onConsumeResponse(), chiamato dalla Libreria Fatturazione Google Play al termine dell'operazione.

L'esempio seguente illustra l'utilizzo di un prodotto con la libreria di fatturazione di Google Play utilizzando il token di acquisto associato:

Kotlin

    val consumeParams =
        ConsumeParams.newBuilder()
            .setPurchaseToken(purchase.getPurchaseToken())
            .build()
    val consumeResult = withContext(Dispatchers.IO) {
        client.consumePurchase(consumeParams)
    }

Java

    ConsumeParams consumeParams =
            ConsumeParams.newBuilder()
                .setPurchaseToken(purchase.getPurchaseToken())
                .build();

    ConsumeResponseListener listener = new ConsumeResponseListener() {
        @Override
        public void onConsumeResponse(BillingResult billingResult, String purchaseToken) {
            if (billingResult.getResponseCode() == BillingResponseCode.OK) {
                // Handle the success of the consume operation.
            }
        }
    };

    billingClient.consumeAsync(consumeParams, listener);

Nota: poiché le richieste di consumo possono occasionalmente non andare a buon fine, devi controllare il tuo server di backend sicuro per assicurarti che ogni token di acquisto non sia stato utilizzato in modo che la tua app non conceda il diritto più volte per lo stesso acquisto. In alternativa, l'app può attendere di ricevere una risposta di consumo corretta da Google Play prima di concedere il diritto. Se scegli di trattenere gli acquisti dell'utente finché Google Play non invia una risposta di consumo positiva, devi fare molta attenzione a non perdere traccia degli acquisti per i quali hai inviato una richiesta di consumo.

Prodotti non di consumo

Per confermare gli acquisti non consumabili, se la tua app ha un backend sicuro, consigliamo di utilizzare Purchases.products:acknowledge per confermare in modo affidabile gli acquisti. Assicurati che l'acquisto non sia stato precedentemente confermato controllando acknowledgementState dal risultato della chiamata Purchases.products:get.

Se la tua app è solo client, utilizza BillingClient.acknowledgePurchase() della Libreria Fatturazione Google Play. Prima di confermare un acquisto, la tua app deve verificare se è già stato confermato utilizzando il metodo isAcknowledged() nella Libreria Fatturazione Google Play.

L'esempio seguente mostra come confermare un acquisto utilizzando la Libreria Fatturazione Google Play:

Kotlin

val client: BillingClient = ...
val acknowledgePurchaseResponseListener: AcknowledgePurchaseResponseListener = ...

val acknowledgePurchaseParams = AcknowledgePurchaseParams.newBuilder()
    .setPurchaseToken(purchase.purchaseToken)
val ackPurchaseResult = withContext(Dispatchers.IO) {
     client.acknowledgePurchase(acknowledgePurchaseParams.build())
}

Java

BillingClient client = ...
AcknowledgePurchaseResponseListener acknowledgePurchaseResponseListener = ...

AcknowledgePurchaseParams acknowledgePurchaseParams =
                AcknowledgePurchaseParams.newBuilder()
                    .setPurchaseToken(purchase.getPurchaseToken())
                    .build();
 client.acknowledgePurchase(acknowledgePurchaseParams, acknowledgePurchaseResponseListener);

Iscrizioni

Gli abbonamenti vengono gestiti in modo simile ai prodotti non consumabili. Se possibile, utilizza Purchases.subscriptions.acknowledge dell' API Google Play Developer per confermare in modo affidabile l'acquisto dal tuo backend sicuro. Verifica che l'acquisto non sia stato precedentemente confermato controllando il valore acknowledgementState nella risorsa di acquisto di Purchases.subscriptions:get. In caso contrario, puoi confermare un abbonamento utilizzando BillingClient.acknowledgePurchase() dalla libreria di fatturazione di Google Play dopo aver selezionato isAcknowledged(). Tutti gli acquisti iniziali dell'abbonamento devono essere confermati. I rinnovi dell'abbonamento non richiedono conferma. Per ulteriori informazioni su quando gli abbonamenti devono essere confermati, consulta l'argomento Vendere abbonamenti.

Riepilogo

Il seguente snippet di codice mostra un riepilogo di questi passaggi.

Kotlin

fun handlePurchase(Purchase purchase) {
    // Purchase retrieved from BillingClient#queryPurchasesAsync or your
    // onPurchasesUpdated.
    Purchase purchase = ...;

    // Step 1: Send the purchase to your secure backend to verify the purchase
    // following
    // https://developer.android.com/google/play/billing/security#verify
.
    // Step 2: Update your entitlement storage with the purchase. If purchase is
    // in PENDING state then ensure the entitlement is marked as pending and the
    // user does not receive benefits yet. It is recommended that this step is
    // done on your secure backend and can combine in the API call to your
    // backend in step 1.

    // Step 3: Notify the user using appropriate messaging (delaying
    // notification if needed as discussed above).

    // Step 4: Notify Google the purchase was processed using the steps
    // discussed in the processing purchases section.
}

Java

void handlePurchase(Purchase purchase) {
    // Purchase retrieved from BillingClient#queryPurchasesAsync or your
    // onPurchasesUpdated.
    Purchase purchase = ...;

    // Step 1: Send the purchase to your secure backend to verify the purchase
    // following
    // https://developer.android.com/google/play/billing/security#verify

    // Step 2: Update your entitlement storage with the purchase. If purchase is
    // in PENDING state then ensure the entitlement is marked as pending and the
    // user does not receive benefits yet. It is recommended that this step is
    // done on your secure backend and can combine in the API call to your
    // backend in step 1.

    // Step 3: Notify the user using appropriate messaging (delaying
    // notification if needed as discussed above).

    // Step 4: Notify Google the purchase was processed using the steps
    // discussed in the processing purchases section.
}

Per verificare che la tua app abbia implementato correttamente questi passaggi, puoi seguire la guida ai test.

Gestire le transazioni in attesa

Google Play supporta le transazioni in attesa, ovvero le transazioni che richiedono uno o più passaggi aggiuntivi tra il momento in cui un utente avvia un acquisto e il momento in cui viene elaborato il metodo di pagamento per l'acquisto. L'app non deve concedere il diritto a questi tipi di acquisti finché Google non ti comunica che l'addebito sul metodo di pagamento dell'utente è andato a buon fine.

Ad esempio, un utente può avviare una transazione scegliendo un negozio fisico dove pagherà in un secondo momento in contanti. L'utente riceve un codice sia tramite notifica sia via email. Quando l'utente arriva in negozio, può riscattare il codice con la cassa e pagare in contanti. Google invia una notifica sia a te sia all'utente per informarvi che il pagamento è stato ricevuto. La tua app può quindi concedere il diritto all'utente.

Chiama enablePendingPurchases() durante l'inizializzazione diBillingClient per attivare le transazioni in attesa per la tua app. La tua app deve attivare e supportare le transazioni in attesa per i prodotti a pagamento singolo. Prima di aggiungere il supporto, assicurati di comprendere il ciclo di vita dell'acquisto per le transazioni in attesa.

Nota: per le app che utilizzano la versione 7.0 o successive della Libreria Fatturazione Google Play, puoi attivare le transazioni in attesa per gli acquisti di piani di abbonamento prepagati. Per scoprire come supportare questa funzionalità nella tua app, consulta Gestire le transazioni in attesa per gli abbonamenti.

Quando la tua app riceve un nuovo acquisto tramite PurchasesUpdatedListener o come risultato della chiamata a queryPurchasesAsync, utilizza il metodo getPurchaseState() per determinare se lo stato dell'acquisto è PURCHASED o PENDING. Devi concedere il diritto solo quando lo stato è PURCHASED.

Se la tua app è in esecuzione e hai un collegamento alla Libreria Fatturazione Google Play attivo quando l'utente completa l'acquisto, PurchasesUpdatedListener viene chiamato di nuovo e PurchaseState diventa PURCHASED. A questo punto, la tua app può elaborare l'acquisto utilizzando il metodo standard per il rilevamento e l'elaborazione degli acquisti. L'app deve anche chiamare queryPurchasesAsync() nel metodo onResume() per gestire gli acquisti che sono passati allo stato PURCHASED mentre l'app non era in esecuzione.

Nota: devi confermare un acquisto solo quando lo stato è PURCHASED, ovvero non confermarlo mentre un acquisto è in stato PENDING. I tre giorni Non confermarlo mentre un acquisto è in stato PENDING. Il periodo di tre giorni per la conferma inizia solo quando lo stato dell'acquisto passa da "IN ATTESA" a "ACQUISTATO".

Quando l'acquisto passa da PENDING a PURCHASED, il client real_time_developer_notifications riceve una notifica ONE_TIME_PRODUCT_PURCHASED o SUBSCRIPTION_PURCHASED. Se l'acquisto viene annullato, riceverai una notifica ONE_TIME_PRODUCT_CANCELED o SUBSCRIPTION_PENDING_PURCHASE_CANCELED. Questo può accadere se il cliente non completa il pagamento nei tempi previsti. Tieni presente che puoi sempre utilizzare l'API Google Play Developer per controllare lo stato corrente di un acquisto.

Nota: le transazioni in attesa possono essere testate con le licenze dell'applicazione. Oltre alle due carte di credito di prova, i tester delle licenze hanno accesso a due strumenti di test per le forme di pagamento differite, in cui il pagamento viene completato o annullato automaticamente dopo un paio di minuti. Per la procedura dettagliata su come testare questo scenario, consulta Testare le transazioni in attesa.

Gestire gli acquisti di più quantità

Supportato nelle versioni 4.0 e successive della libreria di fatturazione di Google Play, Google Play consente ai clienti di acquistare più di un prodotto in-app uguale in un'unica transazione specificando una quantità dal carrello degli acquisti. L'app deve gestire gli acquisti di più quantità e concedere il diritto in base alla quantità di acquisto specificata.

Nota: la quantità multipla è pensata per i prodotti in-app di consumo, ovvero i prodotti che possono essere acquistati, consumati e acquistati di nuovo. Non attivare questa funzionalità per gli elementi che possono essere acquistati, consumati e acquistati di nuovo. Non attivare questa funzionalità per i prodotti che non sono pensati per essere acquistati più volte.

Per rispettare gli acquisti con più quantità, la logica di provisioning dell'app deve verificare la quantità di un articolo. Puoi accedere a un campo quantity da una delle seguenti API:

• getQuantity() dalla Libreria Fatturazione Google Play.
• Purchases.products.quantity dall'API Google Play Developer

Dopo aver aggiunto la logica per gestire gli acquisti con più quantità, devi attivare la funzionalità per il prodotto corrispondente nella pagina di gestione dei prodotti in-app in Google Play Console.

Nota: assicurati che la tua app rispetti gli acquisti con più quantità prima di attivare la funzionalità nella console. Prima di poter attivare la funzionalità su un prodotto, potrebbe essere necessario forzare un aggiornamento a una versione dell'app che fornisca assistenza.

Esegui query sulla configurazione di fatturazione dell'utente

getBillingConfigAsync() fornisce il paese utilizzato dall'utente per Google Play.

Nota: non memorizzare i dati restituiti da getBillingConfigAsync(). Questi dati sono progettati per essere utilizzati una sola volta e possono cambiare in qualsiasi momento. Non puoi utilizzare i datigetBillingConfigAsync() per creare o migliorare un profilo utente o per scegliere come target o monitorare i clienti a fini pubblicitari o di marketing.

Puoi eseguire query sulla configurazione di fatturazione dell'utente dopo aver creato un BillingClient. Il seguente snippet di codice descrive come effettuare una chiamata a getBillingConfigAsync(). Gestisci la risposta implementando BillingConfigResponseListener. Questo ascoltatore riceve aggiornamenti per tutte le query di configurazione della fatturazione avviate dalla tua app.

Se BillingResult restituito non contiene errori, puoi controllare il campo countryCode nell'oggetto BillingConfig per ottenere il paese Google Play dell'utente.

Nota: il formato del codice paese si basa su ISO-3166-1 alpha2 (codici paese delle Nazioni Unite). Per ulteriori dettagli, consulta la tabella Contenimento dei territori.

Kotlin

// Use the default GetBillingConfigParams.
val getBillingConfigParams = GetBillingConfigParams.newBuilder().build()
billingClient.getBillingConfigAsync(getBillingConfigParams,
    object : BillingConfigResponseListener {
        override fun onBillingConfigResponse(
            billingResult: BillingResult,
            billingConfig: BillingConfig?
        ) {
            if (billingResult.responseCode == BillingResponseCode.OK
                && billingConfig != null) {
                val countryCode = billingConfig.countryCode
                ...
            } else {
                // TODO: Handle errors
            }
        }
    })

Java

// Use the default GetBillingConfigParams.
GetBillingConfigParams getBillingConfigParams = GetBillingConfigParams.newBuilder().build();
billingClient.getBillingConfigAsync(getBillingConfigParams,
    new BillingConfigResponseListener() {
      public void onBillingConfigResponse(
          BillingResult billingResult, BillingConfig billingConfig) {
        if (billingResult.getResponseCode() == BillingResponseCode.OK
            && billingConfig != null) {
            String countryCode = billingConfig.getCountryCode();
            ...
         } else {
            // TODO: Handle errors
        }
      }
    });

Promemoria di abbandono del carrello nella home page di Google Play Giochi (attivati per impostazione predefinita)

Per gli sviluppatori di giochi che monetizzano tramite acquisti in-app, uno dei modi in cui gli SKU attivi in Google Play Console possono essere venduti al di fuori della tua app è la funzionalità di promemoria di abbandono del carrello, che spinge gli utenti a completare gli acquisti abbandonati in precedenza mentre navigano nel Google Play Store. Questi acquisti vengono effettuati al di fuori della tua app, dalla home page di Google Play Giochi nel Google Play Store.

Questa funzionalità è attiva per impostazione predefinita per aiutare gli utenti a riprendere da dove avevano interrotto e gli sviluppatori a massimizzare le vendite. Tuttavia, puoi disattivare questa funzionalità per la tua app inviando il modulo di disattivazione della funzionalità Promemoria di abbandono del carrello. Per le best practice sulla gestione degli SKU in Google Play Console, consulta Creare un prodotto in-app.

Le seguenti immagini mostrano il promemoria di abbandono del carrello visualizzato sul Google Play Store:

Figura 2. Nella schermata del Google Play Store viene visualizzata una richiesta di acquisto per un acquisto abbandonato in precedenza.

Figura 3. Nella schermata del Google Play Store viene visualizzata una richiesta di acquisto per un acquisto abbandonato in precedenza.