Linee guida per l'integrazione in-app per i pagamenti esterni

Questo documento descrive come integrare le API Play Billing Library per offrire pagamenti esterni nelle app idonee. Per saperne di più su questo programma, consulta i requisiti del programma.

Configurazione della Libreria Fatturazione Play

Aggiungi la dipendenza Libreria Fatturazione Play alla tua app per Android. Per utilizzare le API per i pagamenti esterni, devi utilizzare la versione 8.3 o successive. Se devi eseguire la migrazione da una versione precedente, segui le istruzioni riportate nella guida alla migrazione per eseguire l'upgrade prima di iniziare l'integrazione.

Inizializzare il client di fatturazione

I primi passaggi della procedura di integrazione sono uguali a quelli descritti nella guida all'integrazione di Fatturazione Google Play, con alcune modifiche durante l'inizializzazione di BillingClient:

L'esempio seguente mostra l'inizializzazione di un BillingClient con queste modifiche:

Kotlin

val purchasesUpdatedListener =
    PurchasesUpdatedListener { billingResult, purchases ->
        // Handle new Google Play purchase.
    }

val developerProvidedBillingListener =
    DeveloperProvidedBillingListener { details ->
        // Handle user selection for developer provided billing option.
    }

val billingClient = BillingClient.newBuilder(context)
    .setListener(purchasesUpdatedListener)
    .enablePendingPurchases()
    .enableBillingProgram(
        EnableBillingProgramParams.newBuilder()
            .setBillingProgram(BillingProgram.EXTERNAL_PAYMENTS)
            .setDeveloperProvidedBillingListener(developerProvidedBillingListener)
            .build())
    .build()

Java

private PurchasesUpdatedListener purchasesUpdatedListener = new PurchasesUpdatedListener() {
    @Override
    public void onPurchasesUpdated(BillingResult billingResult, List<Purchase> purchases) {
        // Handle new Google Play purchase.
    }
};

private DeveloperProvidedBillingListener developerProvidedBillingListener =
    new DeveloperProvidedBillingListener() {
        @Override
        public void onUserSelectedDeveloperBilling(
            DeveloperProvidedBillingDetails details) {
            // Handle user selection for developer provided billing option.
        }
    };

private BillingClient billingClient = BillingClient.newBuilder(context)
    .setListener(purchasesUpdatedListener)
    .enablePendingPurchases()
    .enableBillingProgram(
        EnableBillingProgramParams.newBuilder()
            .setBillingProgram(BillingProgram.EXTERNAL_PAYMENTS)
            .setDeveloperProvidedBillingListener(developerProvidedBillingListener)
            .build())
    .build();

Connessione a Google Play

Dopo aver inizializzato BillingClient, connettiti a Google Play come descritto in Connessione a Google Play.

Verificare l'idoneità dell'utente

Dopo aver effettuato la connessione a Google Play, puoi verificare se l'utente è idoneo per il programma per pagamenti esterni chiamando il metodo isBillingProgramAvailableAsync(). Questo metodo restituisce BillingResponseCode.OK se l'utente è idoneo. L'esempio seguente mostra come verificare l'idoneità:

Kotlin

billingClient.isBillingProgramAvailableAsync(
  BillingProgram.EXTERNAL_PAYMENTS,
  object : BillingProgramAvailabilityListener {
    override fun onBillingProgramAvailabilityResponse(
      billingProgram: Int, billingResult: BillingResult) {
        if (billingResult.responseCode != BillingResponseCode.OK) {
            // Handle failures such as retrying due to network errors,
            // handling external payments unavailable, etc.
            return
        }

        // External payments are available. Can proceed with generating an
        // external transaction token.
})

Java

billingClient.isBillingProgramAvailableAsync(
  BillingProgram.EXTERNAL_PAYMENTS,
  new BillingProgramAvailabilityListener() {
    @Override
    public void onBillingProgramAvailabilityResponse(
      int billingProgram, BillingResult billingResult) {
        if (billingResult.getResponseCode() != BillingResponseCode.OK) {
            // Handle failures such as retrying due to network errors,
            // handling external payments unavailable, etc.
            return;
        }

        // External payments are available. Can proceed with generating an external transaction token.
      }

    });

Per informazioni dettagliate su come deve rispondere la tua app ad altri codici di risposta, consulta la sezione Gestione delle risposte. Se utilizzi le estensioni Kotlin, puoi utilizzare le coroutine Kotlin per non dover definire un listener separato.

Mostrare i prodotti disponibili

Puoi mostrare i prodotti disponibili all'utente esattamente come faresti con un'integrazione del sistema di fatturazione di Google Play. Quando l'utente ha visualizzato i prodotti disponibili per l'acquisto e ne seleziona uno, avvia il flusso di pagamenti esterni come descritto nella sezione Avvio del flusso di pagamenti esterni.

Prepara un token di transazione esterno

Per segnalare una transazione esterna a Google Play, devi disporre di un token di transazione esterna generato dalla libreria Play Billing. Un nuovo token di transazione esterno deve essere generato ogni volta che l'utente visita un sito web o un'app esterni tramite l'API per i pagamenti esterni. Per farlo, occorre chiamare l'API createBillingProgramReportingDetailsAsync. Il token deve essere generato immediatamente prima della chiamata a launchBillingFlow.

Kotlin

val params =
    BillingProgramReportingDetailsParams.newBuilder()
        .setBillingProgram(BillingProgram.EXTERNAL_PAYMENTS)
        .build()

billingClient.createBillingProgramReportingDetailsAsync(
  params,
  object : BillingProgramReportingDetailsListener {
    override fun onCreateBillingProgramReportingDetailsResponse(
      billingResult: BillingResult,
      billingProgramReportingDetails: BillingProgramReportingDetails?) {
        if (billingResult.responseCode != BillingResponseCode.OK) {
            // Handle failures such as retrying due to network errors.
            return
        }
        val externalTransactionToken =
            billingProgramReportingDetails?.externalTransactionToken
        // Persist the external transaction token locally. Pass it to
        // the external website using DeveloperBillingOptionParams when
        // launchBillingFlow is called.
    }
})

Java

BillingProgramReportingDetailsParams params =
    BillingProgramReportingDetailsParams.newBuilder()
        .setBillingProgram(BillingProgram.EXTERNAL_PAYMENTS)
        .build();

billingClient.createBillingProgramReportingDetailsAsync(
  params,
  new BillingProgramReportingDetailsListener() {
    @Override
    public void onCreateBillingProgramReportingDetailsResponse(
      BillingResult billingResult,
      @Nullable BillingProgramReportingDetails
        billingProgramReportingDetails) {
        if (billingResult.getResponseCode() != BillingResponseCode.OK) {
            // Handle failures such as retrying due to network errors.
            return;
        }

        String transactionToken =
          billingProgramReportingDetails.getExternalTransactionToken();

        // Persist the external transaction token locally. Pass it to
        // the external website using DeveloperBillingOptionParams when
        // launchBillingFlow is called.
      }
});

Se utilizzi le estensioni Kotlin, puoi utilizzare le coroutine Kotlin in modo da non dover definire un listener separato.

Avvio del flusso di pagamenti esterni

Avvia il flusso di pagamenti esterni chiamando launchBillingFlow() in modo simile all'avvio di un flusso di acquisto con un'integrazione del sistema di fatturazione di Google Play, ma con un parametro aggiuntivo DeveloperBillingOptionParams fornito per indicare che la tua app vuole attivare il flusso di pagamenti esterni per questo acquisto.

DeveloperBillingOptionParams deve contenere quanto segue:

Quando la tua app chiama launchBillingFlow() con DeveloperBillingOptionParams fornito, il sistema di fatturazione di Google Play esegue il seguente controllo:

  • Il sistema controlla se il paese in Google Play impostato dall'utente è un paese che supporta i pagamenti esterni (ovvero un paese supportato). Se il paese impostato dall'utente in Google Play è supportato, Google Play verifica se i pagamenti esterni sono attivati in base alla configurazione di BillingClient e se è fornito DeveloperBillingOptionParams.
    • Se sono stati attivati i pagamenti esterni, il flusso di acquisto mostra l'esperienza utente della scelta dell'utente.
    • Se i pagamenti esterni non sono attivati, il flusso di acquisto mostra l'esperienza utente standard del sistema di fatturazione di Google Play, senza scelta dell'utente.
  • Se il paese impostato dall'utente in Google Play non è un paese supportato, il flusso di acquisto mostra l'esperienza utente standard del sistema di fatturazione di Google Play, senza scelta dell'utente.

Il paese dell'utente in Play è un paese supportato

Il paese dell'utente in Play non è un paese supportato

Pagamenti esterni attivati (configurazione di BillingClient e launchBillingFlow)

L'utente vede la UX di scelta dell'utente

L'utente vede la UX standard del sistema di fatturazione di Google Play

Pagamenti esterni non abilitati (non abilitati durante la configurazione di BillingClient o DeveloperBillingOptionParams non fornito a launchBillingFlow)

L'utente vede la UX standard del sistema di fatturazione di Google Play

L'utente vede la UX standard del sistema di fatturazione di Google Play

Il seguente snippet mostra come costruire DeveloperBillingOptionParams:

Kotlin

val developerBillingOptionParams =
    DeveloperBillingOptionParams.newBuilder()
        .setBillingProgram(BillingProgram.EXTERNAL_PAYMENTS)
        .setLinkUri("https://www.example.com/external/purchase")
        .setLaunchMode(
            DeveloperBillingOptionParams.LaunchMode.LAUNCH_IN_EXTERNAL_BROWSER_OR_APP)
        .build()

Java

DeveloperBillingOptionParams developerBillingOptionParams =
    DeveloperBillingOptionParams.newBuilder()
        .setBillingProgram(BillingProgram.EXTERNAL_PAYMENTS)
        .setLinkUri("https://www.example.com/external/purchase")
        .setLaunchMode(
            DeveloperBillingOptionParams.LaunchMode.LAUNCH_IN_EXTERNAL_BROWSER_OR_APP)
        .build();

Gestire la selezione effettuata dall'utente

Il modo in cui gestisci il resto del flusso di acquisto varia a seconda del fatto che l'utente abbia selezionato il sistema di fatturazione di Google Play o il pagamento sul tuo sito web.

Quando l'utente sceglie di pagare sul tuo sito web o su un'app di pagamento

Se l'utente sceglie di pagare sul tuo sito web, Google Play chiama DeveloperProvidedBillingListener per comunicare all'app che l'utente ha scelto di pagare sul tuo sito web o in un'app di pagamento. In particolare, viene chiamato il metodo onUserSelectedDeveloperBilling().

Se la tua app imposta launchMode su LAUNCH_IN_EXTERNAL_BROWSER_OR_APP, Google Play avvierà il link. Se launchMode è impostato su CALLER_WILL_LAUNCH_LINK, è responsabilità della tua app avviare il link. Quando colleghi gli utenti a un'app di pagamento, è tua responsabilità verificare che l'utente abbia già installato l'app di pagamento sul proprio dispositivo.

Utilizza questo token per registrare qualsiasi transazione risultante da questa scelta come spiegato nella guida all'integrazione del backend.

Se l'utente seleziona il sistema di fatturazione di Google Play

Se l'utente sceglie il sistema di fatturazione di Google Play, continua con l'acquisto tramite Google Play.

  • Per maggiori informazioni su come gestire i nuovi acquisti in-app tramite il sistema di fatturazione di Google Play, consulta la sezione Elaborazione degli acquisti nella guida all'integrazione della libreria.
  • Per ulteriori indicazioni sugli acquisti di abbonamenti, consulta la sezione Nuovi abbonamenti nella guida alla gestione degli abbonamenti.

Gestire le modifiche agli abbonamenti

Per gli sviluppatori che utilizzano pagamenti esterni, gli acquisti devono essere elaborati tramite il sistema di fatturazione di Google Play o registrati con externalTransactionId, a seconda della scelta dell'utente. Le modifiche agli abbonamenti esistenti elaborati tramite il sito web dello sviluppatore possono essere apportate tramite lo stesso sistema di fatturazione fino alla scadenza.

Questa sezione descrive come gestire alcuni scenari comuni di modifica all'abbonamento.

Flussi di upgrade e downgrade

Le modifiche ai piani di abbonamento, inclusi i flussi di upgrade e downgrade, devono essere gestite in modo diverso a seconda del fatto che l'abbonamento sia stato acquistato originariamente tramite il sistema di fatturazione di Google Play o tramite il sito web dello sviluppatore.

I componenti aggiuntivi che dipendono da un abbonamento esistente, condividono lo stesso metodo di pagamento e gli addebiti ricorrenti di allineamento vengono gestiti come upgrade. Per gli altri componenti aggiuntivi, gli utenti devono poter scegliere il sistema di fatturazione che vogliono utilizzare. Avvia una nuova esperienza di acquisto utilizzando launchBillingFlow(), come descritto in Avviare il flusso di pagamenti esterni.

Abbonamenti acquistati tramite il sito web dello sviluppatore o un'app di pagamento

Per gli abbonamenti originariamente acquistati tramite il sito web dello sviluppatore o un'app di pagamento dopo la scelta dell'utente, gli utenti che richiedono un upgrade o un downgrade devono procedere tramite il sito web dello sviluppatore o un'app di pagamento senza dover ripetere l'esperienza di scelta dell'utente.

Per farlo, chiama launchBillingFlow() quando l'utente richiede un upgrade o un downgrade. Anziché specificare altri parametri nell'oggetto SubscriptionUpdateParams, utilizza setOriginalExternalTransactionId(), fornendo l'ID transazione esterno dell'acquisto originale.

DeveloperBillingOptionParams deve essere fornito anche in questa chiamata. In questo modo, non viene visualizzata la schermata di scelta dell'utente, dato che la scelta dell'utente per l'acquisto originale viene mantenuta per gli upgrade e i downgrade. Devi generare un nuovo token di transazione esterno per questa transazione come descritto qui.

Una volta completato l'upgrade o il downgrade utilizzando il sito web dello sviluppatore o un'app di pagamento, devi registrare una nuova transazione utilizzando il token di transazione esterno ottenuto tramite la chiamata precedente per il nuovo acquisto dell'abbonamento.

Abbonamenti acquistati tramite il sistema di fatturazione di Google Play

Allo stesso modo, gli utenti che hanno acquistato l'abbonamento attuale tramite il sistema di fatturazione di Google Play dopo la scelta dell'utente devono seguire il flusso di fatturazione standard di Google Play. DeveloperBillingOptionParams non deve essere impostato nella chiamata a launchBillingFlow.

Annullamenti e ripristini degli abbonamenti

Gli utenti devono poter annullare l'abbonamento in qualsiasi momento. Quando un utente annulla un abbonamento, la cessazione del diritto può essere rinviata fino al termine del periodo pagato. Ad esempio, se un utente annulla un abbonamento mensile a metà mese, potrebbe continuare ad accedere al servizio per le restanti due settimane circa fino alla rimozione dell'accesso. Durante questo periodo, l'abbonamento è ancora tecnicamente attivo, quindi l'utente può utilizzare il servizio.

Non è raro che gli utenti decidano di cancellare l'annullamento durante questo periodo attivo. In questa guida, questa cancellazione è chiamata ripristino. Le sezioni seguenti descrivono come gestire gli scenari di ripristino nell'integrazione dell'API per i pagamenti esterni.

Abbonamenti acquistati tramite il sito web dello sviluppatore

Se hai un ID transazione esterno per un abbonamento annullato, non è necessario chiamare launchBillingFlow() per ripristinare l'abbonamento, quindi non deve essere utilizzato per questo tipo di attivazione. Se un utente ripristina il proprio abbonamento mentre è ancora nel periodo attivo di un abbonamento annullato, in quel momento non si verifica alcuna transazione; puoi continuare a registrare i rinnovi quando scade il ciclo corrente e inizia il ciclo di rinnovo successivo. Sono inclusi i casi in cui l'utente riceve un credito o un prezzo di rinnovo speciale nell'ambito del ripristino (ad esempio, una promozione per incoraggiare l'utente a continuare con l'abbonamento).

Abbonamenti acquistati tramite il sistema di fatturazione di Google Play

In genere, gli utenti possono ripristinare gli abbonamenti nel sistema di fatturazione di Google Play. Per gli abbonamenti annullati originariamente acquistati sul sistema di fatturazione di Google Play, l'utente può scegliere di annullare l'annullamento mentre l'abbonamento è attivo tramite la funzionalità Riabbonati di Google Play. In questo caso, ricevi una notifica in tempo reale per lo sviluppatore SUBSCRIPTION_RESTARTED nel backend e non viene emesso un nuovo token di acquisto. Il token originale viene utilizzato per continuare l'abbonamento. Per scoprire come gestire il ripristino nel sistema di fatturazione di Google Play, consulta la sezione Ripristini nella guida alla gestione degli abbonamenti.

Puoi anche attivare un ripristino nel sistema di fatturazione di Google Play dall'app chiamando launchBillingFlow(). Per una spiegazione su come fare, consulta la sezione Prima della scadenza dell'abbonamento - in-app. Nel caso di utenti che avevano completato il flusso di scelta dell'utente per l'acquisto originale (che è stato annullato ma è ancora attivo), il sistema rileva automaticamente la loro scelta e visualizza l'interfaccia utente per il ripristino di questi acquisti. Viene chiesto loro di confermare il riacquisto dell'abbonamento tramite Google Play, ma non devono ripetere il flusso di scelta dell'utente. In questo caso, viene emesso un nuovo token di acquisto per l'utente. Il backend riceve una notifica in tempo reale per lo sviluppatore SUBSCRIPTION_PURCHASED e il valore linkedPurchaseToken per il nuovo stato dell'acquisto viene impostato come nel caso di un upgrade o downgrade, con il vecchio token di acquisto per l'abbonamento che era stato annullato.

Riabbonamenti

Se un abbonamento scade completamente, a causa di una cancellazione o del rifiuto del pagamento senza recupero (una sospensione dell'account scaduta), l'utente deve riabbonarsi se vuole riattivare il diritto.

Il riabbonamento può essere abilitato anche tramite l'app, elaborandolo in modo simile a una registrazione standard. Gli utenti devono poter scegliere il sistema di fatturazione che vogliono utilizzare. In questo caso, è possibile chiamare launchBillingFlow(), come descritto in Avvio del flusso di pagamenti esterni.

Gestione delle risposte

Quando si verifica un errore, i metodi isBillingProgramAvailableAsync(), createBillingProgramReportingDetailsAsync(), launchBillingFlow() potrebbero fornire un BillingResponseCode diverso da BillingResponseCode.OK. Prendi in considerazione la gestione di questi codici di risposta nel seguente modo:

  • BillingResponseCode.ERROR: si è verificato un errore interno. Non procedere con la transazione o l'apertura del sito web esterno. Riprova chiamando di nuovo l'API.
  • BillingResponseCode.FEATURE_NOT_SUPPORTED: le API per i pagamenti esterni non sono supportate dal Play Store sul dispositivo attuale. Non procedere con la transazione o l'apertura del sito web esterno.
  • BillingResponseCode.DEVELOPER_ERROR: si è verificato un errore con la richiesta. Utilizza il messaggio di debug per identificare e correggere l'errore prima di procedere.
  • BillingResponseCode.USER_CANCELED: non procedere con l'apertura del sito web o dell'app esterni. Chiama di nuovo launchBillingFlow() per visualizzare la finestra di dialogo informativa per l'utente la prossima volta che tenti di indirizzare l'utente all'esterno dell'app.
  • BillingResponseCode.BILLING_UNAVAILABLE: la transazione non è idonea per i pagamenti esterni e pertanto la fatturazione dello sviluppatore non sarà disponibile nell'ambito di questo programma. Ciò è dovuto al fatto che l'utente non si trova in un paese idoneo per questo programma o il tuo account non è stato registrato correttamente al programma. In questo caso, controlla lo stato della registrazione in Play Console.
  • BillingResponseCode.NETWORK_ERROR, BillingResponseCode.SERVICE_DISCONNECTED, BillingResponseCode.SERVICE_UNAVAILABLE: si tratta di errori temporanei che devono essere gestiti con un'apposita strategia di nuovi tentativi. Nel caso di SERVICE_DISCONNECTED, ristabilisci una connessione con Google Play prima di riprovare.

Testare i link per i pagamenti esterni

I tester delle licenze devono essere utilizzati per testare l'integrazione dei pagamenti esterni. Non riceverai fatture per le transazioni avviate dagli account dei tester delle licenze. Per ulteriori informazioni sulla configurazione dei tester delle licenze, consulta Testare la fatturazione in-app con le licenze dell'applicazione.

Passaggi successivi

Una volta completata l'integrazione in-app, puoi integrare il backend.