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

Questo argomento descrive come eseguire la migrazione dalla versione 4 o 5 della Libreria Fatturazione Google Play a 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 la release note.

Panoramica

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

Per maggiori informazioni sulle nuove funzionalità introdotte con la Libreria Fatturazione Play 5, leggi l'articolo Modifiche recenti agli abbonamenti in Google Play Google Cloud.

Upgrade della Libreria Fatturazione Play compatibile con le versioni precedenti

Tutti i prodotti in abbonamento esistenti sono stati automaticamente convertiti in questo nuovo come parte della release di maggio 2022 della versione 5 di Libreria Fatturazione Play e del nuovo piattaforma di abbonamento. Ciò significa che non devi effettuare alcun abbonamento modifiche alla configurazione del prodotto per avere un catalogo compatibile con le nuove di Libreria Fatturazione Play. Per ulteriori informazioni sulle modalità di sottoscrizione Gli SKU sono stati convertiti in abbonamenti compatibili con le versioni precedenti. Consulta la sezione Informazioni sull'uso con gli abbonamenti precedenti nella Guida di Play Console .

Le versioni precedenti dell'app continuano a funzionare

Se hai un catalogo in abbonamento compatibile con le versioni precedenti, della tua app dovrebbe continuare a funzionare come previsto per questi prodotti. Prodotto a pagamento singolo Inoltre, gli acquisti 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 precedenti compatibili. Puoi trovare informazioni sulle offerte compatibili con le versioni precedenti nella sezione Google Play Store pertinente Centro assistenza Console .

Eseguire l'upgrade alla versione 5 o 6 della Libreria Fatturazione Play

Le versioni 5 e 6 di Libreria Fatturazione Play includono i metodi ritirati querySkuDetailsAsync e BillingFlowParams.Builder.setSkuDetails che richiedono SkuDetails come fatturazione il parametro di flusso. Ciò significa che puoi passare gradualmente alla Libreria Fatturazione Play 6 pianificando diverse fasi della migrazione.

Come primo passaggio per la migrazione, puoi semplicemente aggiornare la libreria versione, lascia invariati il catalogo e il backend e testa la tua app mentre continua a utilizzare i metodi deprecati. Se non utilizzi queryPurchases, launchPriceChangeFlow o setVrPurchaseFlow, dovrebbe funzionano ancora come previsto. In seguito, potrete eseguire l'iterazione per adottare completamente il nuovo di funzionalità di abbonamento rilasciate a maggio 2022.

Se in precedenza hai adottato queste funzionalità con una Libreria Fatturazione Google Play 5, puoi passare direttamente alle sezioni con l'etichetta Libreria Fatturazione Play e Modificare l'abbonamento di un utente acquisti. Se inizi da una versione precedente o non hanno ancora adottato del tutto le nuove funzionalità, potete leggere l'articolo sulla migrazione passaggi successivi per scoprire come adottarli.

Passaggi completi della migrazione

Creare nuovi abbonamenti nel catalogo dei prodotti di backend

Ora puoi usare Play Developer Console o l'API Play Developer 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 per tutto il ciclo di vita dell'abbonamento utilizzando una con rinnovo automatico e piani prepagati.

Ti consigliamo di creare nuovi prodotti seguendo la struttura delle entità nella nuova per l'integrazione di Libreria Fatturazione Play 6 prima del giorno eseguire la migrazione dell'app. Puoi raggruppare i prodotti duplicati nel tuo vecchio catalogo rappresentare gli stessi vantaggi relativi ai diritti per un singolo abbonamento e utilizzo configurazioni di piano base e offerta per rappresentare tutte le opzioni che vuoi offrire. Per ulteriori informazioni su questo consiglio, consulta la sezione Utilizzo di sezione Abbonamenti meno recenti della Guida di Play Console .

Ti consigliamo di non modificare i prodotti in abbonamento convertiti dopo il Release di maggio 2022; è consigliabile lasciarli così come vengono venduti con le versioni la tua app utilizzando metodi deprecati (ad esempio querySkuDetailsAsync()) senza introdurre modifiche che potrebbero influire sulle build meno recenti.

La procedura di conversione ha creato i prodotti in abbonamento presenti nel tuo catalogo prima di maggio 2022 in sola lettura per evitare modifiche accidentali che potrebbero comportare problemi con l'integrazione esistente. Apportare modifiche a questi abbonamenti possibile, ma ci sarebbero implicazioni che potrebbero influire sul tuo frontend integrazioni di backend:

• Sul frontend, le versioni dell'app che utilizzano querySkuDetailsAsync() per ottenere dettagli del prodotto in abbonamento possono vendere solo piani base compatibili con le versioni precedenti e le offerte possono esistere solo un piano base e un'offerta compatibili con le versioni precedenti Di conseguenza, se aggiungi nuovi piani o offerte agli abbonamenti convertiti, le nuove offerte o i nuovi piani base aggiuntivi non potranno essere venduti su questi vecchi piani o versioni successive della tua app.

• Nel backend, se modifichi gli abbonamenti convertiti nel UI di Play Console, non potrai gestirla con inappproducts endpoint, se stai chiamando l'endpoint a questo scopo. Dovresti inoltre eseguire la migrazione al nuovo endpoint dello stato di acquisto dell'abbonamento (purchases.subscriptionsv2.get) per gestire gli acquisti per questi abbonamenti, poiché l'endpoint precedente dello stato di acquisto (purchases.subscriptions.get) restituisce solo I dati necessari per gestire offerte e piani base compatibili con le versioni precedenti acquisti. Leggi la sezione Gestire lo stato dell'acquisto dell'abbonamento. per ulteriori informazioni.

Gestisci il catalogo degli abbonamenti backend con la nuova API

Se gestisci automaticamente il catalogo dei prodotti in abbonamento con API Google Play Developer, devi usare il nuovo prodotto in abbonamento di definizione degli endpoint per creare e gestire abbonamenti, piani base e offerte. Leggi le funzionalità di abbonamento di maggio 2022 guida 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 per gli abbonamenti a Fatturazione Google Play, sostituisci inappproducts con la nuova API Subscription Publishing per gestire e pubblicare del tuo catalogo in abbonamento. Ci sono tre nuovi endpoint:

• Monetization.subscriptions per gestire i prodotti in abbonamento.
• Monetization.basePlans per gestire i piani base per gli abbonamenti.
• Monetization.offers per gestire le offerte per i piani base.

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

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

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. Qui puoi trovare informazioni sulle offerte compatibili con le versioni precedenti.

Aggiorna Libreria Fatturazione Google Play

Dopo aver creato il nuovo catalogo dei prodotti in abbonamento, puoi eseguire la migrazione dell'app alla Libreria Fatturazione Google. 5. Sostituisci quello esistente Dipendenza di Libreria Fatturazione Play con la versione aggiornata a il file build.gradle dell'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 metodi: Libreria Fatturazione Play 6 è compatibile con le versioni precedenti. Il concetto di SKU è considerata deprecata, ma ancora presente per semplificare la portabilità delle app processo incrementale.

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

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

• Inizializza il client di fatturazione
• Stabilire una connessione a Google Play

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 utilizzare 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 valore List<ProductDetails.SubscriptionOfferDetails>, ovvero dei dettagli dell'offerta di abbonamento. Per i prodotti acquistati una volta sola: ProductDetails contiene un ProductDetails.OneTimePurchaseOfferDetails. Questi può essere utilizzato per decidere quali offerte mostrare agli utenti.

L'esempio seguente mostra l'aspetto che potrebbe avere la tua app prima e dopo apportando queste modifiche:

Prima

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
}

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

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
}

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 l'abbonamento i prodotti ora contengono anche un List<ProductDetails.SubscriptionOfferDetails> contenente tutte le offerte a disposizione dell'utente.

Poiché le versioni precedenti della Libreria Fatturazione Play non supportano le nuove (abbonamenti, piani base, offerte e così via), il nuovo sistema converte ogni SKU di abbonamento in un singolo SKU di abbonamento compatibile piano base e offerta. Anche i prodotti disponibili una tantum sono trasferito a un oggetto ProductDetails. I dettagli dell'offerta di un prodotto è accessibile con getOneTimePurchaseOfferDetails().

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

Lanciare il flusso di acquisto delle offerte

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

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

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

Dopo aver creato un oggetto BillingFlowParams, avvia il flusso di fatturazione con BillingClient rimane lo stesso.

L'esempio seguente mostra l'aspetto che potrebbe avere la tua app prima e dopo apportando queste modifiche:

Prima

// 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)

// 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

// 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)

// 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 Libreria Fatturazione Google Play 6 rimane simile alle versioni precedenti.

Per recuperare tutti gli acquisti attivi di proprietà dell'utente ed eseguire query per nuovi acquisti, procedi nel seguente modo:

• Invece di trasmettere un valore BillingClient.SkuType a queryPurchasesAsync(), passa un oggetto QueryPurchasesParams che contiene un valore BillingClient.ProductType.

L'esempio seguente mostra l'aspetto che potrebbe avere la tua app prima e dopo aver apportato queste modifiche:

Prima

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

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

Dopo

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

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 al di fuori delle app e le transazioni in attesa non sono cambiate.

Gestisci lo stato di acquisto dell'abbonamento 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 essere pronto a gestire gli acquisti dei nuovi prodotti creati nei passaggi precedenti. Gestione attuale dello stato di acquisto dei tuoi abbonamenti dovrebbe funzionare come di consueto per i prodotti in abbonamento convertiti che definiti 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 tuo modulo di gestione dello stato di acquisto degli abbonamenti, che controlla l'acquisto e gestisce i diritti di abbonamento di Fatturazione Play nel tuo backend. La versione precedente dell'API non restituisce tutti i dettagli necessari per gestire acquisti nella nuova piattaforma. Per maggiori dettagli sulle modifiche rispetto alle versioni precedenti, consulta la guida alle nuove funzionalità di abbonamento di maggio 2022.

In genere chiamerai l'API Subscription Purchases ogni volta che ricevi un SubscriptionNotification Notifica in tempo reale per lo sviluppatore per estrarre il le ultime informazioni sullo stato dell'abbonamento. Devi sostituire chiamate a purchases.subscriptions.get con la nuova versione di l'API Subscription Purchases, purchases.subscriptionsv2.get. C'è una nuova risorsa chiamata SubscriptionPurchaseV2 che fornisca una quantità sufficiente informazioni per gestire il diritto di acquisto per gli abbonamenti nel nuovo modello.

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

Modificare gli acquisti di abbonamenti effettuati da un utente

In Libreria Fatturazione Play 5 e versioni precedenti, ProrationMode è stato utilizzato per applicare modifiche agli acquisti di abbonamenti di un utente, ad esempio gli upgrade o downgrade. È stato deprecato e sostituito con ReplacementMode nella versione 6.

Gestire le variazioni di prezzo degli abbonamenti

L'API launchPriceConfirmationFlow deprecata in precedenza è stata rimossa in Libreria Fatturazione Play 6. Per conoscere le alternative, consulta le variazioni di prezzo .

Gestire gli errori della 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 Google Play System. Sono state apportate modifiche anche ai codici SERVICE_TIMEOUT e SERVICE_UNAVAILABLE. Per ulteriori informazioni, consulta Gestire la risposta di BillingResult codici.

Gestire le transazioni in sospeso

A partire dalla versione 6.0.0, la Libreria Fatturazione Play non crea un ordine ID per gli acquisti in attesa. Per questi acquisti, l'ID ordine viene compilato dopo l'acquisto viene spostato PURCHASED stato. Assicurati che l'integrazione richieda un ID ordine solo dopo un completamente completata. Puoi comunque utilizzare il token di acquisto per record. Per maggiori informazioni sulla gestione degli acquisti in attesa, visita la pagina La guida all'integrazione della Libreria Fatturazione e la guida alla gestione del ciclo di vita degli acquisti.