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

Questo documento 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à degli abbonamenti.

Per un elenco completo delle modifiche nella versione 6.0.0, consulta le note di rilascio.

Panoramica

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

Per maggiori informazioni sulle nuove funzionalità introdotte con la Libreria Fatturazione Play 5, consulta l'articolo 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 convertiti automaticamente in questo nuovo paradigma nell'ambito della release di maggio 2022 della Libreria Fatturazione Play 5 e della nuova piattaforma di abbonamenti. Ciò significa che non devi apportare modifiche alla configurazione dei prodotti 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 Utilizzo di abbonamenti meno recenti 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 continuare a funzionare come previsto per questi prodotti. Anche gli acquisti di prodotti a pagamento singolo 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 nel relativo articolo del Centro assistenza Play Console.

Esegui l'upgrade alla Libreria Fatturazione Play 5 o 6

La Libreria Fatturazione Play 5 e 6 include i metodi deprecati querySkuDetailsAsync e BillingFlowParams.Builder.setSkuDetails che accettano 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 il catalogo e il backend invariati e testare l'app mentre utilizza ancora i metodi deprecati. Se non utilizzi queryPurchases, launchPriceChangeFlow o setVrPurchaseFlow, dovrebbe comunque funzionare come previsto. In seguito, puoi eseguire l'iterazione per adottare completamente le nuove funzionalità per gli abbonamenti rilasciate a maggio 2022.

Se hai già adottato queste funzionalità con una migrazione alla Libreria Fatturazione Google Play 5, puoi procedere direttamente alle sezioni Aggiorna la Libreria Fatturazione Google Play e Modifica gli acquisti di abbonamenti di un utente. Se inizi da una versione precedente o non hai ancora adottato completamente le nuove funzionalità, puoi leggere i passaggi completi della migrazione di seguito per scoprire come adottarle.

Passaggi per la migrazione completa

Crea nuovi abbonamenti nel catalogo dei prodotti di backend

Utilizzando Play Console o l'API Play Developer, ora puoi configurare un singolo abbonamento con più piani base, ciascuno con più offerte. Le offerte di abbonamento hanno modelli di prezzi e opzioni di idoneità flessibili. Puoi creare offerte in tutto il ciclo di vita dell'abbonamento utilizzando un'ampia gamma di piani prepagati e con rinnovo automatico.

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

Lascia invariati i prodotti in abbonamento convertiti dopo la release di maggio 2022, in modo che le versioni dell'app che utilizzano metodi deprecati (come querySkuDetailsAsync()) possano continuare a venderli senza influire su queste build.

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

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

  • Nel backend, se modifichi gli abbonamenti convertiti nell'UI di Play Console, non potrai gestirli con l'endpoint inappproducts, se lo chiamavi per questo scopo. Dovresti anche eseguire la migrazione al nuovo endpoint dello stato di acquisto dell'abbonamento (purchases.subscriptionsv2.get) per gestire gli acquisti di questi abbonamenti, poiché il vecchio endpoint dello stato di acquisto (purchases.subscriptions.get) restituisce solo i dati necessari per gestire gli acquisti di piani base e offerte compatibili con le versioni precedenti. Per saperne di più, leggi la sezione Gestisci lo stato di acquisto dell'abbonamento.

Gestisci il catalogo degli abbonamenti di backend con la nuova API

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

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

Questi nuovi endpoint hanno tutte le funzionalità necessarie per sfruttare tutte le nuove funzionalità del tuo catalogo: tag dei piani base e delle 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 con acquisto 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 scoprire di più sulle offerte compatibili con le versioni precedenti nell'articolo del Centro assistenza Play Console.

Aggiorna la Libreria Fatturazione Google Play

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

dependencies {
    def billingVersion = "6.0.0"

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

Il progetto dovrebbe essere creato immediatamente, anche se non hai modificato alcuna chiamata ai metodi, in quanto la Libreria Fatturazione Play 6 è compatibile con le versioni precedenti. Il concetto di SKU è considerato deprecato, ma è ancora presente per rendere il porting delle app un processo più semplice e incrementale.

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

I primi passaggi per lanciare gli acquisti da un'app per 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
  • Passa la chiamata BillingClient.querySkuDetailsAsync() all'utilizzo di BillingClient.queryProductDetailsAsync()

Tieni presente che i risultati della query ora sono 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>, ovvero l'elenco dei dettagli dell'offerta in abbonamento. Per i prodotti con acquisto 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 l'applicazione di 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> che contiene 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 con acquisto una tantum disponibili vengono trasferiti a un oggetto ProductDetails. Puoi accedere ai dettagli dell'offerta di un prodotto con acquisto una tantum con il metodo getOneTimePurchaseOfferDetails().

In rari casi, alcuni dispositivi non sono in grado di supportare ProductDetails e queryProductDetailsAsync(), di solito 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 di queryProductDetailsAsync(). Se la risposta è FEATURE_NOT_SUPPORTED, puoi invece richiedere l'elenco dei prodotti compatibili con le versioni precedenti disponibili con querySkuDetailsAsync(). Per scoprire di più su come utilizzare le funzionalità di compatibilità con le versioni precedenti, consulta la guida alle funzionalità degli abbonamenti di maggio 2022.

Avvia 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, segui questi passaggi:

  • Anziché utilizzare SkuDetails per BillingFlowParams, utilizza ProductDetailsParams.
  • I dettagli dell'offerta, 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, recupera il offerToken dell'offerta selezionata e passalo all'oggetto ProductDetailsParams.

Una volta creato un oggetto BillingFlowParams, il lancio del flusso di fatturazione con BillingClient rimane invariato.

L'esempio seguente mostra l'aspetto della tua app prima e dopo l'applicazione di 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 = ...;

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 the offer token corresponding to the selected
        // offer call productDetails.subscriptionOfferDetails?.get(selectedOfferIndex)?.offerToken
        .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 the offer token corresponding to the selected
            // offer call productDetails.getSubscriptionOfferDetails().get(selectedOfferIndex).getOfferToken()
            .setOfferToken(selectedOfferToken)
            .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 la Libreria Fatturazione Google Play 6 rimane simile alle versioni precedenti.

Per recuperare tutti gli acquisti attivi di proprietà dell'utente ed eseguire query per i nuovi acquisti, segui questi passaggi:

  • Anziché passare un valore BillingClient.SkuType a queryPurchasesAsync(), passa un oggetto QueryPurchasesParams che contiene 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
        }
    }
);

La procedura per gestire gli acquisti esterni all'app e le transazioni in attesa non è cambiata.

Gestisci lo stato di acquisto degli abbonamenti con la nuova API nel tuo backend

Devi eseguire la migrazione del componente di gestione dello stato di acquisto degli abbonamenti nel tuo backend per prepararti a gestire gli acquisti dei nuovi prodotti creati nei passaggi precedenti. Il componente di gestione dello stato di acquisto degli abbonamenti attuale 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 degli acquisti di abbonamenti, che controlla lo stato degli acquisti 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 informazioni dettagliate sulle modifiche rispetto alle versioni precedenti, consulta la guida alle nuove funzionalità degli abbonamenti di maggio 2022.

Quando esegui la migrazione del modulo di gestione dello stato degli acquisti:

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

Modifica gli acquisti di 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, ad esempio upgrade o downgrade. Questo è stato ritirato e sostituito con ReplacementMode nella versione 6.

Gestisci le variazioni di prezzo degli abbonamenti

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

Gestisci gli errori della Libreria Fatturazione Play

In 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 modifiche anche ai codici SERVICE_TIMEOUT e SERVICE_UNAVAILABLE. Per maggiori informazioni, consulta Gestisci i codici di risposta BillingResult.

Gestisci le transazioni in attesa

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 compilato dopo che l'acquisto viene spostato nello stato PURCHASED. Assicurati che l'integrazione preveda un ID ordine solo dopo che una transazione è stata completata. Puoi comunque utilizzare il token di acquisto per i tuoi record. Per maggiori 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.