Esegui la migrazione alla Libreria Fatturazione Google Play 6 dalla versione 4 o 5

Questo argomento descrive come eseguire la migrazione dalla Libreria Fatturazione Google Play 4 o 5 alla Libreria Fatturazione Google Play 6 e come utilizzare le nuove funzionalità di abbonamento.

Per un elenco completo delle modifiche apportate alla versione 6.0.0, consulta le note sulla versione.

Panoramica

Libreria Fatturazione Google Play 6 si basa sulle nuove funzionalità di abbonamento introdotte nella versione 5 e aggiunge alcuni miglioramenti. Queste funzionalità ti consentono di vendere abbonamenti in più modi, riducendo i costi operativi e eliminando la necessità di creare e gestire un numero sempre crescente di SKU.

Per ulteriori informazioni sulle nuove funzionalità introdotte con la Libreria Fatturazione Play 5, consulta la pagina Modifiche recenti agli abbonamenti in Play Console.

Upgrade della Libreria Fatturazione Play compatibile con le versioni precedenti

Tutti i prodotti in abbonamento esistenti sono stati automaticamente convertiti in questo nuovo paradigma nell'ambito della release di maggio 2022 di Libreria Fatturazione Play 5 e della nuova piattaforma di abbonamento. Ciò significa che non devi apportare modifiche alla configurazione del prodotto in abbonamento per avere un catalogo compatibile con le nuove versioni della Libreria Fatturazione Play. Per maggiori informazioni su come gli SKU degli abbonamenti sono stati convertiti in abbonamenti compatibili con le versioni precedenti, consulta la sezione Utilizzare gli abbonamenti precedenti nell'articolo del Centro assistenza Play Console.

Le versioni precedenti dell'app continuano a funzionare

Se hai un catalogo di abbonamenti compatibile con le versioni precedenti, tutte le versioni esistenti della tua app dovrebbero comunque funzionare come previsto per questi prodotti. Anche gli acquisti una tantum dei prodotti dovrebbero continuare a funzionare senza problemi nelle versioni precedenti.

Le versioni della tua app che utilizzano metodi deprecati (ad esempio querySkuDetailsAsync()) non potranno vendere piani base o offerte non compatibili con le versioni precedenti. Puoi leggere informazioni sulle offerte compatibili con le versioni precedenti nell'articolo del Centro assistenza Play Console pertinente.

Esegui l'upgrade alla Libreria Fatturazione Play 5 o 6

Libreria Fatturazione Play 5 e 6 includono i metodi deprecati querySkuDetailsAsync e BillingFlowParams.Builder.setSkuDetails che utilizzano SkuDetails come parametro del flusso di fatturazione. Ciò significa che puoi passare gradualmente alla Libreria Fatturazione Play 6 pianificando diverse fasi di migrazione.

Come primo passaggio della migrazione, puoi semplicemente aggiornare la versione della libreria, lasciare invariati il catalogo e il backend e testare l'app mentre continua a utilizzare i metodi deprecati. Se non utilizzi queryPurchases, launchPriceChangeFlow o setVrPurchaseFlow, dovrebbe comunque funzionare come previsto. In seguito, potrai eseguire l'iterazione per adottare completamente le nuove funzionalità di abbonamento rilasciate a maggio 2022.

Se in precedenza hai adottato queste funzionalità con una migrazione di Libreria Fatturazione Google Play5, puoi passare direttamente alle sezioni Aggiornare Libreria Fatturazione Google Play e Cambiare gli acquisti di abbonamenti di un utente. Se stai iniziando da una versione precedente o non hai ancora adottato completamente le nuove funzionalità, puoi leggere la procedura completa di migrazione per scoprire come adottarle.

Passaggi di migrazione completi

Crea nuovi abbonamenti nel catalogo dei prodotti di backend

Utilizzando la Play Developer Console o l'API Play Developer, ora puoi configurare un singolo abbonamento con più piani base, ciascuno con più offerte. Le offerte di abbonamento prevedono modelli di prezzo flessibili e opzioni di idoneità. Puoi creare offerte durante l'intero ciclo di vita dell'abbonamento utilizzando una serie di piani prepagati e con rinnovo automatico.

Ti consigliamo di creare nuovi prodotti che seguono la struttura delle entità nella nuova piattaforma di abbonamento per l'integrazione di Libreria Fatturazione Play 6 prima di eseguire la migrazione dell'app. Puoi consolidare i prodotti duplicati nel vecchio catalogo che rappresentano gli stessi vantaggi dei diritti in un unico abbonamento e utilizzare configurazioni di piani base e offerte per rappresentare tutte le opzioni che vuoi offrire. Per maggiori informazioni su questo consiglio, consulta la sezione Usare gli abbonamenti meno recenti dell'articolo del Centro assistenza Play Console.

Ti consigliamo di non modificare i prodotti in abbonamento convertiti dopo la release di maggio 2022. Dovresti lasciarli così come devono essere venduti insieme alle versioni della tua app utilizzando metodi deprecati (ad esempio querySkuDetailsAsync()), senza apportare modifiche che potrebbero influire su queste build meno recenti.

Il processo di conversione ha reso i prodotti in abbonamento presenti nel tuo catalogo prima di maggio 2022 in sola lettura per evitare modifiche accidentali che potrebbero causare problemi con l'integrazione esistente. È possibile apportare modifiche a questi abbonamenti, ma ci sarebbero implicazioni che potrebbero influire sulle integrazioni di frontend e backend:

  • Sul frontend, le versioni dell'app che utilizzano querySkuDetailsAsync() per ottenere i dettagli dei prodotti in abbonamento possono vendere solo offerte e piani base compatibili con le versioni precedenti. Inoltre, può esistere un'unica combinazione di offerte e piani base compatibili con le versioni precedenti. Pertanto, se aggiungi nuovi piani o offerte agli abbonamenti convertiti, i nuovi piani base o offerte aggiuntivi non potranno essere venduti su queste versioni precedenti della tua app.

  • Nel backend, se modifichi gli abbonamenti convertiti nell'interfaccia utente di Play Console, non potrai gestirli con l'endpoint inappproducts se chiamavi l'endpoint per questo scopo. Devi inoltre eseguire la migrazione al nuovo endpoint dello stato dell'acquisto degli abbonamenti (purchases.subscriptionsv2.get) per gestire gli acquisti per questi abbonamenti, poiché il precedente endpoint dello stato dell'acquisto (purchases.subscriptions.get) restituisce solo i dati necessari per gestire gli acquisti di offerte e piani base compatibili con le versioni precedenti. Per ulteriori informazioni, leggi la sezione relativa alla gestione dello stato di acquisto dell'abbonamento.

Gestisci il catalogo degli abbonamenti al backend con la nuova API

Se gestisci automaticamente il catalogo dei prodotti in abbonamento con l'API Google Play Developer, devi utilizzare gli endpoint di definizione dei nuovi prodotti in abbonamento per creare e gestire abbonamenti, piani base e offerte. Leggi la guida alle funzionalità di abbonamento di maggio 2022 per scoprire di più sulle modifiche all'API del catalogo dei prodotti per questa release.

Per eseguire la migrazione di un modulo di gestione automatica del catalogo dei prodotti per gli abbonamenti a Fatturazione Google Play, sostituisci l'API inappproducts con la nuova API Subscription Publishing per gestire e pubblicare il catalogo degli abbonamenti. Ci sono tre nuovi endpoint:

Questi nuovi endpoint dispongono di tutte le funzionalità necessarie per sfruttare tutte le nuove funzionalità del tuo catalogo: tag di piani base e offerte, targeting per regione, piani prepagati e altro ancora.

Devi comunque utilizzare l'API inappproducts per gestire il catalogo dei prodotti in-app per i prodotti acquistati una tantum.

Le versioni della tua app che utilizzano metodi deprecati (ad esempio, querySkuDetailsAsync()) non potranno vendere piani base o offerte non compatibili con le versioni precedenti. Puoi leggere informazioni sulle offerte compatibili con le versioni precedenti qui.

Aggiorna Libreria Fatturazione Google Play

Dopo aver creato il nuovo catalogo dei prodotti in abbonamento, puoi eseguire la migrazione della tua app alla Libreria Fatturazione Google 5. Sostituisci la dipendenza esistente di Libreria Fatturazione Play con la versione aggiornata del file build.gradle della tua app.

dependencies {
    def billingVersion = "6.0.0"

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

La creazione del progetto dovrebbe avvenire immediatamente, anche se non hai modificato alcuna chiamata ai metodi, la Libreria Fatturazione Play 6 è compatibile con le versioni precedenti. Il concetto di SKU è considerato deprecato, ma è ancora attivo per rendere il trasferimento delle app un processo più semplice e incrementale.

Inizializza il client di fatturazione e stabilisci una connessione a Google Play

I primi passaggi per avviare gli acquisti da un'app Android rimangono gli stessi:

Mostra i prodotti disponibili per l'acquisto

Per ottenere tutte le offerte che un utente è idoneo ad acquistare:

  • Sostituisci SkuDetailsParams con QueryProductDetailsParams
  • Cambia la chiamata BillingClient.querySkuDetailsAsync() per usare BillingClient.queryProductDetailsAsync()

Tieni presente che i risultati della query sono ora ProductDetails anziché SkuDetails. Ogni elemento ProductDetails contiene le informazioni sul prodotto (ID, titolo, tipo e così via). Per i prodotti in abbonamento, ProductDetails contiene un List<ProductDetails.SubscriptionOfferDetails>, che è l'elenco dei dettagli delle offerte di abbonamento. Per i prodotti acquistati una tantum, ProductDetails contiene un ProductDetails.OneTimePurchaseOfferDetails. Questi possono essere utilizzati per decidere quali offerte mostrare agli utenti.

L'esempio seguente mostra l'aspetto della tua app prima e dopo aver apportato queste modifiche:

Prima

Kotlin

val skuList = ArrayList<String>()

skuList.add("up_basic_sub")

val params = SkuDetailsParams.newBuilder()

params.setSkusList(skuList).setType(BillingClient.SkuType.SUBS).build()

billingClient.querySkuDetailsAsync(params) {
    billingResult,
    skuDetailsList ->
    // Process the result
}

Java

List<String> skuList = new ArrayList<>();

skuList.add("up_basic_sub");

SkuDetailsParams.Builder params = SkuDetailsParams.newBuilder();

params.setSkusList(skuList).setType(SkuType.SUBS).build();

billingClient.querySkuDetailsAsync(params,
    new SkuDetailsResponseListener() {
        @Override
        public void onSkuDetailsResponse(BillingResult billingResult,
                List<SkuDetails> skuDetailsList) {
            // Process the result.
        }
    }
);

Dopo

Kotlin

val productList =
    listOf(
        QueryProductDetailsParams.Product.newBuilder()
            .setProductId("up_basic_sub")
            .setProductType(BillingClient.ProductType.SUBS)
            .build()
    )

val params = QueryProductDetailsParams.newBuilder().setProductList(productList).build()

billingClient.queryProductDetailsAsync(params) {
    billingResult,
    productDetailsList ->
    // Process the result
}

Java

ImmutableList<Product> productList = ImmutableList.of(Product.newBuilder()
                                            .setProductId("up_basic_sub")
                                            .setProductType(ProductType.SUBS)
                                            .build());

QueryProductDetailsParams params = QueryProductDetailsParams.newBuilder()
    .setProductList(productList)
    .build();

billingClient.queryProductDetailsAsync(
        params,
        new ProductDetailsResponseListener() {
                public void onProductDetailsResponse(BillingResult billingResult, List<ProductDetails> productDetailsList) {
                    // Process the result
                }
        }
);

Il callback per queryProductDetailsAsync restituisce un List<ProductDetails>. Ogni elemento ProductDetails contiene le informazioni sul prodotto (ID, titolo, tipo e così via). La differenza principale è che i prodotti in abbonamento ora contengono anche un List<ProductDetails.SubscriptionOfferDetails> contenente tutte le offerte disponibili per l'utente.

Poiché le versioni precedenti della Libreria Fatturazione Play non supportano i nuovi oggetti (abbonamenti, piani base, offerte e così via), il nuovo sistema traduce ogni SKU di abbonamento in un unico piano base e un'unica offerta compatibili con le versioni precedenti. Anche i prodotti disponibili per gli acquisti una tantum vengono trasferiti a un oggetto ProductDetails. Puoi accedere ai dettagli dell'offerta di un prodotto una tantum con il metodo getOneTimePurchaseOfferDetails().

Raramente alcuni dispositivi non sono in grado di supportare ProductDetails e queryProductDetailsAsync(), generalmente a causa di versioni obsolete di Google Play Services. Per garantire un supporto adeguato per questo scenario, chiama isFeatureSupported() per la funzionalità PRODUCT_DETAILS prima di chiamare queryProductDetailsAsync. Se la risposta è OK, il dispositivo supporta la funzionalità e puoi procedere con la chiamata a queryProductDetailsAsync(). Se la risposta è FEATURE_NOT_SUPPORTED, puoi richiedere l'elenco dei prodotti compatibili con le versioni precedenti disponibile con querySkuDetailsAsync(). Per scoprire di più su come utilizzare le funzionalità di compatibilità con le versioni precedenti, consulta la guida alle funzionalità dell'abbonamento a maggio 2022.

Lancia il flusso di acquisto dell'offerta

L'avvio di un flusso di acquisto per un'offerta è molto simile all'avvio di un flusso per uno SKU. Per avviare una richiesta di acquisto utilizzando la versione 6:

  • Anziché usare SkuDetails per BillingFlowParams, usa ProductDetailsParams.
  • I dettagli delle offerte, come l'ID offerta, l'ID piano base e altro ancora, possono essere ottenuti utilizzando l'oggetto SubscriptionOfferDetails.

Per acquistare un prodotto con l'offerta selezionata dall'utente, ricevi offerToken dell'offerta selezionata e trasmettilo all'oggetto ProductDetailsParams.

Una volta creato un oggetto BillingFlowParams, l'avvio del flusso di fatturazione con BillingClient rimane invariato.

L'esempio seguente mostra l'aspetto della tua app prima e dopo aver apportato queste modifiche:

Prima

Kotlin

// An activity reference from which the billing flow will be launched.
val activity : Activity = ...
// Retrieve a value for "skuDetails" by calling querySkuDetailsAsync().
val billingFlowParams = BillingFlowParams.newBuilder()
                            .setSkuDetails(skuDetails)
                            .build()

val billingResult = billingClient.launchBillingFlow(activity, billingFlowParams)

Java

// An activity reference from which the billing flow will be launched.
Activity activity = ...;
// Retrieve a value for "skuDetails" by calling querySkuDetailsAsync().
BillingFlowParams billingFlowParams = BillingFlowParams.newBuilder()
        .setSkuDetails(skuDetails)
        .build();

BillingResult billingResult = billingClient.launchBillingFlow(activity, billingFlowParams)

Dopo

Kotlin

// An activity reference from which the billing flow will be launched.
val activity : Activity = ...
// Retrieve a value for "productDetails" by calling queryProductDetailsAsync()
// Get the offerToken of the selected offer
val offerToken = productDetails.subscriptionOfferDetails?.get(selectedOfferIndex)?.offerToken

val productDetailsParamsList =
    listOf(
        BillingFlowParams.ProductDetailsParams.newBuilder()
            .setProductDetails(productDetails)
            .setOfferToken(offerToken)
            .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 = ...;

// Retrieve a value for "productDetails" by calling queryProductDetailsAsync()
// Get the offerToken of the selected offer
String offerToken = productDetails
                     .getSubscriptionOfferDetails()
                     .get(selectedOfferIndex)
                     .getOfferToken();
// Set the parameters for the offer that will be presented
// in the billing flow creating separate productDetailsParamsList variable
ImmutableList<ProductDetailsParams> productDetailsParamsList =
        ImmutableList.of(
                 ProductDetailsParams.newBuilder()
                     .setProductDetails(productDetails)
                     .setOfferToken(offerToken)
                     .build()
        );

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

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

Elabora gli acquisti

L'elaborazione degli acquisti con Libreria Fatturazione Google Play 6 rimane simile alle versioni precedenti.

Per estrarre tutti gli acquisti attivi di proprietà dell'utente ed eseguire query per i nuovi acquisti, procedi come segue:

  • Anziché passare un valore BillingClient.SkuType a queryPurchasesAsync(), passa un oggetto QueryPurchasesParams contenente un valore BillingClient.ProductType.

L'esempio seguente mostra l'aspetto della tua app prima e dopo aver apportato queste modifiche:

Prima

Kotlin

billingClient.queryPurchasesAsync(BillingClient.SkuType.SUBS) {
    billingResult,
    purchaseList -> {
        // Process the result
    }
}

Java


billingClient.queryPurchasesAsync(
    BillingClient.SkuType.SUBS,
    new PurchasesResponseListener() {
        public void onQueryPurchasesResponse(
                BillingResult billingResult,
                List<Purchase> purchases) {
            // process the result
        }
    }
);

Dopo

Kotlin

billingClient.queryPurchasesAsync(
    QueryPurchasesParams.newBuilder()
        .setProductType(BillingClient.ProductType.SUBS)
        .build()
) { billingResult, purchaseList ->
    // Process the result
}

Java

billingClient.queryPurchasesAsync(
    QueryPurchasesParams.newBuilder().setProductType(ProductType.SUBS).build(),
    new PurchasesResponseListener() {
        public void onQueryPurchasesResponse(
                BillingResult billingResult,
                List<Purchase> purchases) {
            // Process the result
        }
    }
);

I passaggi per gestire gli acquisti all'esterno dell'app e le transazioni in sospeso non sono cambiati.

Gestisci lo stato dell'acquisto dell'abbonamento con la nuova API nel tuo backend

Devi eseguire la migrazione del componente per la gestione dello stato di acquisto degli abbonamenti nel backend per poter gestire gli acquisti dei nuovi prodotti creati nei passaggi precedenti. Il tuo attuale componente per la gestione dello stato di acquisto degli abbonamenti dovrebbe funzionare come di consueto per i prodotti in abbonamento convertiti che hai definito prima del lancio di maggio 2022 e dovrebbe essere sufficiente per gestire gli acquisti di offerte compatibili con le versioni precedenti, ma non supporta nessuna delle nuove funzionalità.

Devi implementare la nuova API Subscription Purchases per il modulo di gestione dello stato di acquisto degli abbonamenti, che controlla lo stato di acquisto e gestisce i diritti di abbonamento a Fatturazione Play nel tuo backend. La versione precedente dell'API non restituisce tutti i dettagli necessari per gestire gli acquisti nella nuova piattaforma. Per maggiori dettagli sulle modifiche rispetto alle versioni precedenti, consulta la guida alle nuove funzionalità di abbonamento a maggio 2022.

In genere, chiamerai l'API Subscription Purchases ogni volta che ricevi una SubscriptionNotification notifica in tempo reale per lo sviluppatore per ottenere le informazioni più recenti sullo stato dell'abbonamento. Devi sostituire le chiamate a purchases.subscriptions.get con la nuova versione dell'API Subscription Purchases, purchases.subscriptionsv2.get. È disponibile una nuova risorsa chiamata SubscriptionPurchaseV2 che fornisce informazioni sufficienti per gestire il diritto di acquisto per gli abbonamenti nel nuovo modello.

Questo nuovo endpoint restituisce lo stato per tutti i prodotti in abbonamento e per tutti i tuoi acquisti, indipendentemente dalla versione dell'app in cui sono stati venduti e da quando è stato definito il prodotto (prima o dopo la release di maggio 2022), quindi dopo la migrazione avrai bisogno solo di questa versione del modulo di gestione dello stato di acquisto dell'abbonamento.

Modificare gli acquisti degli abbonamenti di un utente

Nella Libreria Fatturazione Play 5 e versioni precedenti, ProrationMode veniva utilizzato per applicare modifiche agli acquisti di abbonamenti di un utente, come upgrade o downgrade. Questo elemento è stato deprecato e sostituito con ReplacementMode nella versione 6.

Gestire le modifiche ai prezzi degli abbonamenti

L'API launchPriceConfirmationFlow precedentemente deprecata è stata rimossa in Libreria Fatturazione Play 6. Per conoscere le alternative, consulta la guida alle modifiche ai prezzi.

Gestire gli errori di Libreria Fatturazione Play

Nella Libreria Fatturazione Play 6 è stato aggiunto un nuovo codice NETWORK_ERROR per indicare problemi con la connessione di rete tra il dispositivo dell'utente e il sistema Google Play. Sono state apportate anche modifiche ai codici SERVICE_TIMEOUT e SERVICE_UNAVAILABLE. Per ulteriori informazioni, consulta Gestire i codici di risposta di BillingResult.

Gestire le transazioni in sospeso

A partire dalla versione 6.0.0, la Libreria Fatturazione Play non crea un ID ordine per gli acquisti in attesa. Per questi acquisti, l'ID ordine viene completato dopo che l'acquisto viene spostato nello stato PURCHASED. Assicurati che l'integrazione preveda un ID ordine solo dopo il completamento di una transazione. Puoi continuare a utilizzare il token di acquisto per la tua documentazione. Per ulteriori informazioni sulla gestione degli acquisti in attesa, consulta la guida all'integrazione della Libreria Fatturazione Play e la guida alla gestione del ciclo di vita degli acquisti.