Eseguire la migrazione alla Libreria Fatturazione Google Play 9 dalle versioni 7 o 8

Questo documento descrive come eseguire la migrazione dalla Libreria Fatturazione Google Play (PBL) 7 o 8 alla PBL 9 e come eseguire l'integrazione con le nuove funzionalità.

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

Panoramica

PBL 9 contiene miglioramenti alle API esistenti, oltre alla rimozione delle API precedentemente ritirate. Questa versione della libreria introduce anche un contesto di errore più completo tramite nuovi codici di risposta secondari.

Compatibilità con le versioni precedenti per l'upgrade di PBL

Per eseguire la migrazione alla Libreria Fatturazione Play 9, devi aggiornare o rimuovere alcuni dei riferimenti API esistenti dalla tua app, come descritto nelle note di rilascio e più avanti in questa guida alla migrazione.

Esegui l'upgrade dalla versione 7 o 8 alla versione 9 della Libreria Fatturazione Play

Per eseguire l'upgrade da PBL 7 o 8 a PBL 9, segui questi passaggi:

  1. Aggiorna la versione della dipendenza della Libreria Fatturazione Play nel file build.gradle della tua app.

    dependencies {
  def billing_version = "9.1.0"
  implementation "com.android.billingclient:billing:$billing_version"
}

    Se utilizzi Kotlin, il modulo KTX della Libreria Fatturazione Google Play contiene estensioni Kotlin e il supporto delle coroutine che ti consentono di scrivere codice 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:

    dependencies {
  val billing_version = "9.1.0"
  implementation("com.android.billingclient:billing-ktx:$billing_version")
}

  2. (Applicabile solo per l'upgrade dalla versione 7 alla versione 9 della Libreria Fatturazione Play). Aggiorna l'implementazione del metodo queryProductDetailsAsync.

    È stata apportata una modifica alla firma del metodo ProductDetailsResponseListener.onProductDetailsResponse, che richiede modifiche alla tua app per l'implementazione di queryProductDetailsAsync. Per maggiori informazioni, consulta la sezione Mostrare la disponibilità dei prodotti.

  3. Gestisci le API rimosse.

    La tabella seguente elenca le API rimosse e le API alternative corrispondenti che devi utilizzare nella tua app.

    Esegui l'upgrade da

    PBL 9 non supporta più le API elencate nella tabella seguente. Se la tua implementazione utilizza una di queste API rimosse, consulta la tabella per le API alternative corrispondenti.

    Rimozione dell'API precedentemente deprecata API alternativa da utilizzare
    API queryPurchaseHistoryAsync Consulta cronologia acquisti. Se utilizzavi queryPurchaseHistoryAsync per determinare l'idoneità alle prove senza costi, ora devi utilizzare ProductDetails.getSubscriptionOfferDetails() per determinare le offerte per cui un utente è idoneo.
    BillingClient.SkuType BillingClient.ProductType. Le costanti del tipo di prodotto INAPP e SUBS rimangono funzionalmente simili alle costanti del tipo di SKU ritirate.
    SkuDetails ProductDetails. Questo è il nuovo modello di dati che supporta i prodotti a pagamento singolo.
    SkuDetailsParams Utilizza QueryProductDetailsParams con queryProductDetailsAsync.
    SkuDetailsResponseListener Utilizza ProductDetailsResponseListener con queryProductDetailsAsync.
    QueryPurchaseHistoryParams
    • Utilizza queryPurchasesAsync per gli acquisti attivi o in attesa.
    • Monitora gli acquisti consumati sui tuoi server di backend.
    • Utilizza l'API Voided Purchases lato server per gli acquisti annullati o nulli.
    getSkuDetailsList e setSkuDetailsList Utilizza BillingFlowParams.Builder.setProductDetailsParamsList
    querySkuDetailsAsync queryProductDetailsAsync
    enablePendingPurchases() (API senza parametri) enablePendingPurchases(PendingPurchasesParams params)
    Tieni presente che il metodo enablePendingPurchases() deprecato è funzionalmente equivalente a enablePendingPurchases(PendingPurchasesParams.newBuilder().enableOneTimeProducts().build()).
    queryPurchasesAsync(String skuType, PurchasesResponseListener listener) queryPurchasesAsync

    Esegui l'upgrade da

    La tabella seguente elenca le API rimosse in PBL 9 e le API alternative corrispondenti che devi utilizzare nella tua app.

    Rimozione dell'API precedentemente deprecata API alternativa da utilizzare
    BillingClient.SkuType BillingClient.ProductType. Le costanti del tipo di prodotto INAPP e SUBS rimangono funzionalmente simili alle costanti del tipo di SKU ritirate.
    SkuDetails ProductDetails. Questo è il nuovo modello di dati che supporta i prodotti a pagamento singolo.
    SkuDetailsParams Utilizza QueryProductDetailsParams con queryProductDetailsAsync.
    SkuDetailsResponseListener Utilizza ProductDetailsResponseListener con queryProductDetailsAsync.
    QueryPurchaseHistoryParams
    getSkuDetailsList e setSkuDetailsList Utilizza BillingFlowParams.Builder.setProductDetailsParamsList

  4. (Consigliato) Attiva la riconnessione automatica del servizio.

    La Libreria Fatturazione Play può tentare di ristabilire automaticamente la connessione al servizio se viene effettuata una chiamata API mentre il servizio è disconnesso. Per saperne di più, consulta Abilita la riconnessione automatica del servizio.

  5. Gestisci i nuovi codici di risposta secondari.

    Il BillingResult restituito da launchBillingFlow() ora includerà un campo del codice di risposta secondaria. Questo campo verrà compilato solo in alcuni casi per fornire un motivo più specifico dell'errore. Il campo della risposta secondaria può avere i seguenti valori:

    • PAYMENT_DECLINED_DUE_TO_INSUFFICIENT_FUNDS: restituito quando i fondi dell'utente sono inferiori al prezzo dell'articolo che sta tentando di acquistare.
    • USER_INELIGIBLE: viene restituito quando l'utente non soddisfa i requisiti di idoneità configurati per un'offerta di abbonamento.
    • NO_APPLICABLE_SUB_RESPONSE_CODE: il valore predefinito, restituito quando non è applicabile nessun altro codice di risposta secondario.

    Passaggio di migrazione: aggiorna la gestione dei risultati di PurchasesUpdatedListener o equivalente per riconoscere e rispondere a questi codici di sottorisposta specifici per offrire un'esperienza utente migliore. Ad esempio, richiedendo di correggere i metodi di pagamento o mostrando un messaggio di errore specifico.

  6. Consapevolezza della riclassificazione dei codici di errore.

    Nei casi in cui l'app Play Store è bloccata dal sistema (ad esempio, nella modalità per bambini personalizzata dall'OEM), il codice di risposta di PBL è cambiato da ERROR a BILLING_UNAVAILABLE.

    Passaggio di migrazione: assicurati che la logica di gestione degli errori tenga conto di questa modifica e non si basi sulla ricezione di un errore generico in questi scenari specifici.

  7. Gestisci l'annullabilità di DeveloperProvidedBillingDetails.getLinkUri().

    Se utilizzi DeveloperProvidedBillingDetails nell'ambito di un'integrazione di pagamenti esterni, getLinkUri() ora è @Nullable.

    Passaggio di migrazione: per gestire questa modifica in modo sicuro, assicurati che il codice di integrazione gestisca i valori null e stringa vuota ("") dal metodo DeveloperProvidedBillingDetails.getLinkUri() prima di analizzare o lanciare gli intent del browser. Ad esempio:

    Kotlin

    Java

    String linkUri = details.getLinkUri();
if (!android.text.TextUtils.isEmpty(linkUri)) {
  Intent intent = new Intent(Intent.ACTION_VIEW, Uri.parse(linkUri));
  context.startActivity(intent);
}

  8. Modifiche facoltative.