Integra la Libreria Fatturazione Google Play nella tua app

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, consumare l'acquisto in modo che l'utente possa acquistarlo di nuovo.

Gli abbonamenti si rinnovano automaticamente fino all'annullamento. 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 un 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 riprova 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 all'abbonamento. 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 inizializzare una connessione.

Aggiungi la dipendenza della Libreria Fatturazione Google Play

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

Alla moda

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 di Libreria Fatturazione Google Play contiene il supporto delle estensioni e delle coroutine Kotlin 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:

Alla moda

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. Ti consigliamo vivamente di avere una connessione BillingClient attiva aperta alla volta per evitare più callback PurchasesUpdatedListener per un singolo evento.

Per creare un BillingClient, utilizza newBuilder(). Puoi passare qualsiasi contesto a newBuilder(), che lo utilizza per ottenere un contesto dell'applicazione. 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();

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 ed è 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.
    }
});

Mostra i prodotti disponibili per l'acquisto

Dopo aver stabilito una connessione a Google Play, puoi inviare query ai 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.

Eseguire 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 supporto adeguato per questo scenario, scopri come utilizzare le funzionalità di compatibilità con le versioni precedenti nella guida alla migrazione di 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, come 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, verifica che l'utente non possieda già l'articolo. Se l'utente ha un articolo consumabile ancora nella raccolta di articoli, deve consumarlo prima di poterlo acquistare di nuovo.

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

  • queryProductDetailsAsync() restituisce i dettagli del prodotto in 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.

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.

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 product, "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.

In caso di chiamata riuscita a launchBillingFlow(), il sistema mostra la schermata di acquisto di Google Play. La figura 1 mostra una schermata di acquisto di un abbonamento:

La schermata di acquisto di Google Play mostra un abbonamento disponibile per l&#39;acquisto
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) {
           handlePurchase(purchase)
       }
   } else if (billingResult.responseCode == BillingResponseCode.USER_CANCELED) {
       // Handle an error caused by a user cancelling 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) {
            handlePurchase(purchase);
        }
    } else if (billingResult.getResponseCode() == BillingResponseCode.USER_CANCELED) {
        // Handle an error caused by a user cancelling the purchase flow.
    } else {
        // Handle any other error codes.
    }
}

Un acquisto riuscito genera una schermata di acquisto riuscito su Google Play simile alla Figura 2.

schermata di acquisto riuscito di google play
Figura 2. Schermata di acquisto riuscito di 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 di passare il token al tuo server di backend sicuro, dove puoi verificare l'acquisto e proteggerti dalle frodi. Questa procedura è descritta ulteriormente nella sezione seguente.

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.

Indica un prezzo personalizzato

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

La schermata di acquisto di Google Play che indica che il prezzo è stato personalizzato per l&#39;utente.
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'UI di 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.

Elaborazione degli acquisti

Una volta che l'utente completa un acquisto, la tua app deve elaborarlo. Nella maggior parte dei casi, la tua app riceve una notifica relativa agli acquisti tramite il tuo PurchasesUpdatedListener. Tuttavia, in alcuni casi la tua app viene informata degli acquisti chiamando il numero BillingClient.queryPurchasesAsync(), come descritto nella sezione Recupero degli acquisti.

Inoltre, se disponi di un client Notifiche in tempo reale per lo sviluppatore nel tuo backend sicuro, puoi registrare nuovi acquisti ricevendo un avviso subscriptionNotification o oneTimeProductNotification che ti avvisa di un nuovo acquisto. Dopo aver ricevuto queste notifiche, chiama l'API Google Play Developer per ottenere lo stato completo e aggiornare lo stato del tuo backend.

La tua app deve elaborare un acquisto nel seguente modo:

  1. Verifica l'acquisto.
  2. Fornisci i contenuti all'utente e conferma la consegna. Se vuoi, contrassegna l'articolo come consumato in modo che l'utente possa acquistarlo nuovamente.

Per verificare un acquisto, controlla innanzitutto che lo stato dell'acquisto sia PURCHASED. Se l'acquisto è PENDING, devi elaborarlo come descritto nella sezione Gestire le transazioni in attesa. Per gli acquisti ricevuti da onPurchasesUpdated() o queryPurchasesAsync(), devi verificare ulteriormente l'acquisto per garantirne la legittimità prima che l'app conceda il diritto. Per scoprire come verificare correttamente un acquisto, consulta la pagina Verificare gli acquisti prima di concedere diritti.

Una volta verificato l'acquisto, la tua app è pronta per concedere il diritto all'utente. L'account utente associato all'acquisto può essere identificato con il valore ProductPurchase.obfuscatedExternalAccountId restituito da Purchases.products:get per gli acquisti di prodotti in-app e il valore SubscriptionPurchase.obfuscatedExternalAccountId restituito da Purchases.subscriptions:get per gli abbonamenti lato server oppure con il valore obfuscatedAccountId di Purchase.getAccountIdentifiers() lato client, se impostato con setObfuscatedAccountId al momento dell'acquisto.

Dopo aver concesso il diritto, l'app deve confermare l'acquisto. In questo modo, a Google Play viene comunicato che hai concesso i diritti per l'acquisto.

La procedura per concedere il diritto e confermare l'acquisto dipende dal fatto che l'acquisto sia un materiale di consumo, non consumabile o un abbonamento.

Prodotti di consumo

Per i materiali di consumo, se la tua app ha un backend sicuro, ti consigliamo di usare Purchases.products:consume per consumare gli acquisti in modo affidabile. Assicurati che l'acquisto non sia già stato utilizzato controllando consumptionState dal 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 eseguire l'override del metodo onConsumeResponse(), chiamato dalla Libreria Fatturazione Google Play al termine dell'operazione.

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

Kotlin

suspend fun handlePurchase(purchase: Purchase) {
    // Purchase retrieved from BillingClient#queryPurchasesAsync or your PurchasesUpdatedListener.
    val purchase : Purchase = ...;

    // Verify the purchase.
    // Ensure entitlement was not already granted for this purchaseToken.
    // Grant entitlement to the user.

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

Java

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

    // Verify the purchase.
    // Ensure entitlement was not already granted for this purchaseToken.
    // Grant entitlement to the user.

    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);
}

Prodotti non di consumo

Per confermare gli acquisti non consumabili, se la tua app dispone di un backend sicuro, consigliamo di utilizzare Purchases.products:acknowledge per confermare in modo affidabile gli acquisti. Assicurati che l'acquisto non sia stato confermato in precedenza selezionando acknowledgementState dopo la chiamata a Purchases.products:get.

Se la tua app è solo client, utilizza BillingClient.acknowledgePurchase() della Libreria Fatturazione Google Play nell'app. Prima di confermare un acquisto, l'app deve controllare 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 = ...

suspend fun handlePurchase() {
    if (purchase.purchaseState === PurchaseState.PURCHASED) {
        if (!purchase.isAcknowledged) {
            val acknowledgePurchaseParams = AcknowledgePurchaseParams.newBuilder()
                    .setPurchaseToken(purchase.purchaseToken)
            val ackPurchaseResult = withContext(Dispatchers.IO) {
               client.acknowledgePurchase(acknowledgePurchaseParams.build())
            }
        }
     }
}

Java

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

void handlePurchase(Purchase purchase) {
    if (purchase.getPurchaseState() == PurchaseState.PURCHASED) {
        if (!purchase.isAcknowledged()) {
            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 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.

Recupero degli acquisti

L'ascolto degli aggiornamenti di acquisto tramite un PurchasesUpdatedListener non è sufficiente per garantire che la tua app elabori tutti gli acquisti. È possibile che la tua app non sia a conoscenza di tutti gli acquisti effettuati da un utente. Di seguito sono riportati alcuni scenari in cui la tua app potrebbe perdere traccia o non essere a conoscenza degli acquisti:

  • Problemi di rete durante l'acquisto: un utente effettua un acquisto corretto e riceve la conferma da Google, ma il suo dispositivo perde la connettività di rete prima di ricevere la notifica dell'acquisto tramite il PurchasesUpdatedListener.
  • Più dispositivi: un utente acquista un articolo su un dispositivo e si aspetta 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.

Per gestire queste situazioni, assicurati che la tua app chiami BillingClient.queryPurchasesAsync() nel tuo metodo onResume() per garantire che tutti gli acquisti vengano elaborati correttamente come descritto nella sezione relativa all'elaborazione degli acquisti.

L'esempio seguente mostra come recuperare gli acquisti di abbonamenti di un utente. Tieni presente che queryPurchasesAsync() restituisce solo gli abbonamenti attivi e gli acquisti una tantum non consumati.

Kotlin

val params = QueryPurchasesParams.newBuilder()
               .setProductType(ProductType.SUBS)

// uses queryPurchasesAsync Kotlin extension function
val purchasesResult = billingClient.queryPurchasesAsync(params.build())

// check purchasesResult.billingResult
// process returned purchasesResult.purchasesList, e.g. display the plans user owns

Java

billingClient.queryPurchasesAsync(
    QueryPurchasesParams.newBuilder()
      .setProductType(ProductType.SUBS)
      .build(),
    new PurchasesResponseListener() {
      public void onQueryPurchasesResponse(BillingResult billingResult, List<Purchase> purchases) {
        // check billingResult
        // process returned purchase list, e.g. display the plans user owns

      }
    }
);

Gestire gli acquisti effettuati al di fuori della tua app

Alcuni acquisti possono avvenire al di fuori della tua app, ad esempio l'utilizzo delle promozioni o i promemoria di abbandono del carrello per gli acquisti in-app su Google Play Giochi (IAP). Quando un utente effettua un acquisto al di fuori della tua app, si aspetta che l'app mostri un messaggio in-app o utilizzi un qualche tipo di meccanismo di notifica per comunicargli che l'app ha ricevuto ed elaborato correttamente l'acquisto. Ecco alcuni meccanismi accettabili:

  • Mostra un popup 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.

Tieni presente che è possibile che la tua app sia in qualsiasi stato quando riconosce l'acquisto. È persino possibile che l'app non sia stata nemmeno installata al momento dell'acquisto. Gli utenti si aspettano di ricevere il loro acquisto quando riprendono l'app, indipendentemente dallo stato in cui si trova.

Devi rilevare gli acquisti indipendentemente dallo stato dell'app al momento dell'acquisto. Tuttavia, esistono alcune eccezioni in cui potrebbe essere accettabile non informare immediatamente l'utente della ricezione dell'articolo. Ad esempio:

  • Durante la parte di azione di un gioco, in cui la visualizzazione di un messaggio potrebbe distrarre l'utente. In questo caso, devi informare l'utente al termine della parte di azione.
  • Durante le scene tagliate, in cui la visualizzazione di un messaggio potrebbe distrarre l'utente. In questo caso, devi informare l'utente al termine della scena.
  • Durante il tutorial iniziale e le parti del gioco per la configurazione dell'utente. Ti consigliamo di informare i nuovi utenti del premio subito dopo l'apertura del gioco o durante la configurazione iniziale dell'utente. Tuttavia, è accettabile attendere fino a quando la sequenza del gioco principale non è disponibile per inviare una notifica all'utente.

Quando decidi quando e come informare gli utenti degli acquisti effettuati al di fuori della tua app, tieni sempre presente l'utente. Ogni volta che un utente non riceve immediatamente una notifica, potrebbe confondersi e smettere di utilizzare la tua app, contattare l'assistenza utenti o presentare un reclamo sui social media.

Promemoria relativi all'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à è abilitata per impostazione predefinita per aiutare gli utenti a riprendere da dove avevano lasciato e per aiutare 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:

nella schermata del Google Play Store viene visualizzata una richiesta di acquisto per un acquisto abbandonato in precedenza
Figura 2. La schermata del Google Play Store mostra una richiesta di acquisto per un acquisto precedentemente abbandonato.

nella schermata del Google Play Store viene visualizzata una richiesta di acquisto per un acquisto abbandonato in precedenza
Figura 3. La schermata del Google Play Store mostra una richiesta di acquisto per un acquisto precedentemente abbandonato.

Gestione delle 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 tramite notifica e email. Quando l'utente arriva in negozio, può utilizzare il codice con la cassa e pagare in contanti. Google invia quindi 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 di BillingClient 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 l'assistenza, assicurati di comprendere il ciclo di vita dell'acquisto per le transazioni in attesa.

Quando la tua app riceve un nuovo acquisto tramite PurchasesUpdatedListener o come risultato dell'uso della chiamata 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 quando l'utente completa l'acquisto, il tuo PurchasesUpdatedListener viene richiamato e il PurchaseState è PURCHASED. A questo punto, la tua app può elaborare l'acquisto utilizzando il metodo standard per elaborare gli acquisti. L'app deve anche chiamare queryPurchasesAsync() nel metodo onResume() dell'app per gestire gli acquisti che sono passati allo stato PURCHASED mentre l'app non era in esecuzione.

Quando l'acquisto passa da PENDING a PURCHASED, il tuo client di notifiche in tempo reale per lo sviluppatore 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 attuale di un acquisto.

Gestione degli acquisti di più quantità

Supportato nelle versioni 4.0 e successive della Libreria Fatturazione Google Play, Google Play consente ai clienti di acquistare più di uno stesso prodotto in-app in una singola transazione specificando una quantità presente nel carrello degli acquisti. La tua app deve gestire gli acquisti di più quantità e concedere il diritto in base alla quantità di acquisto specificata.

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:

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.

Esegui una query sulla configurazione di fatturazione dell'utente

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

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

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

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
        }
      }
    });