Massimizzare l'integrazione di Fatturazione Google Play

1. Panoramica

Ottimizza i tuoi flussi di entrate e lancia la tua app in tutta sicurezza con questo codelab di integrazione della Libreria Fatturazione Google Play di Google Play. Questo codelab strutturato ti guida nella configurazione, nel test e nell'implementazione dell'elaborazione affidabile degli acquisti, consentendoti di supportare i tuoi obiettivi di monetizzazione e offrire un'esperienza utente più fluida.

Ti aiuteremo a configurare le notifiche in tempo reale per lo sviluppatore (RTDN) e Play Billing Lab per gli abbonamenti e i prodotti a pagamento singolo per le tue app e i tuoi giochi. Scoprirai come ridurre l'abbandono degli abbonati, proteggerti da frodi e abusi, testare i casi limite, simulare, riprodurre e risolvere potenziali problemi, nonché sperimentare offerte e variazioni di prezzo senza influire sugli utenti.

Al termine, sarai pronto a implementare strategie di riconquista, risolvere rapidamente le sfide di integrazione, migliorare il ROI, offrire un'esperienza premium e implementare la tua app e gli aggiornamenti con sicurezza.

Prerequisiti

• Familiarità con l'integrazione di base della Libreria Fatturazione Play
• Familiarità con lo sviluppo di app per Android (Java)

Obiettivi didattici

• Come gestire correttamente i cicli di vita degli acquisti per ottimizzare la crescita con tecniche per migliorare le conversioni degli acquisti e la fidelizzazione dei clienti
• Come configurare le notifiche in tempo reale per lo sviluppatore (RTDN) utilizzando Google Cloud Pub/Sub, che può essere utilizzato per implementare campagne di riconquista e altre strategie di gestione del ciclo di vita
• Come configurare un destinatario sul server di backend per gestire in modo sicuro le notifiche con monitoraggio e diritti accurati per ridurre i rimborsi involontari o i rischi di frode e abuso
• Come testare l'integrazione e simulare gli errori utilizzando Play Billing Lab per migliorare l'esperienza utente e ridurre i costi di sviluppo

Che cosa ti serve

• Accesso all'account sviluppatore Play per la tua app in Google Play Console
• Accesso al tuo progetto Google Cloud Platform con l'API Google Play Developer attivata
• Un server di backend per gestire account e diritti per la tua app per Android
• Tester delle licenze registrati per la tua app in Play Console
• Play Billing Lab installato sul dispositivo di test

2. Strategie di monetizzazione per abbonamenti e acquisti una tantum

Quando vendi prodotti digitali tramite la tua app, una strategia di monetizzazione efficace deve considerare l'intera esperienza utente, sia per gli acquisti singoli che per gli abbonamenti. Un'esperienza ottimale può aumentare la propensione all'acquisto e ridurre il churn.

Un flusso di acquisto comune per un acquisto una tantum o un abbonamento prevede più fasi:

1. L'utente sfoglia gli articoli da acquistare.
2. Avvia il flusso di acquisto in modo che l'utente possa completare l'acquisto e il pagamento.
3. Notificare al server l'acquisto completato
4. Verifica l'acquisto sul tuo server.
5. Fornire contenuti all'utente.
6. Conferma la ricezione dei contenuti. Per i prodotti di consumo, consuma l'acquisto al momento opportuno in modo che l'utente possa acquistare nuovamente l'articolo.

L'integrazione in-app ti consente di avviare i flussi di acquisto e gestire questa esperienza utente, ma è fondamentale mantenere aggiornato il backend sui diritti che gli utenti acquistano. Ciò è importante per monitorare gli acquisti e gestire altri aspetti dell'esperienza utente, come i diritti cross-platform.

Le notifiche in tempo reale per gli sviluppatori (RTDN) sono un ottimo modo per riconoscere le diverse fasi del ciclo di vita dell'acquisto e possono essere utilizzate efficacemente sia come strumento di monitoraggio del rendimento in tempo reale sia come strumento per attivare strategie di recupero degli abbonati.

Ad esempio, supponiamo che l'utente abbia appena acquistato un nuovo articolo o abbia appena mancato il pagamento, quindi l'abbonamento è entrato nel periodo di tolleranza. Con la notifica in tempo reale corretta, puoi riconoscere, quasi in tempo reale, che lo stato dell'utente è cambiato e agire di conseguenza, ad esempio aumentando il coinvolgimento dell'utente con l'articolo appena acquistato o inviando email di promemoria per aggiornare i dati di pagamento e continuare l'abbonamento.

Truecaller ha recuperato circa il 40% degli abbonati grazie all'implementazione di RTDN. Scopri come

Le notifiche in tempo reale sono anche un ottimo modo per aggiungere controlli lato server aggiuntivi per aiutarti a gestire gli acquisti anche quando il client dell'utente presenta problemi. Supponiamo che un utente abbia effettuato un acquisto e abbia ricevuto la conferma da Google, ma il suo dispositivo perda la connettività di rete prima che il dispositivo e la tua app ricevano la notifica dell'acquisto tramite il listener degli acquisti. Con le notifiche in tempo reale, riceverai una notifica indipendente tramite il tuo server, che ti consentirà di riconoscere l'acquisto e concedere il diritto all'utente indipendentemente dal problema del client, garantendo un processo di acquisto affidabile.

Puoi scoprire di più su tutti i tipi di RTDN attualmente supportati qui. Ogni tipo di notifica in tempo reale indica uno stato di acquisto distinto. È fondamentale implementare meccanismi di gestione corrispondenti per garantire l'elaborazione corretta in base alle esigenze dei tuoi casi d'uso. Questo codelab ti guiderà attraverso un esempio che gestisce il messaggio RTDN nel tuo server di backend sicuro, inclusi la ricezione del messaggio, la convalida dell'acquisto e la concessione del diritto all'utente corretto, quando un utente completa correttamente un acquisto nella tua app. Successivamente, ti mostreremo come configurare le RTDN per la tua app.

3. Configurare le notifiche in tempo reale per lo sviluppatore (RTDN)

Le notifiche in tempo reale per lo sviluppatore (RTDN) sfruttano Google Cloud Pub/Sub per consentirti di reagire immediatamente alle modifiche dello stato dell'acquisto. Cloud Pub/Sub è un servizio di messaggistica in tempo reale completamente gestito che puoi utilizzare per inviare e ricevere messaggi tra applicazioni indipendenti. Google Play utilizza Cloud Pub/Sub per pubblicare notifiche push sugli argomenti a cui ti iscrivi.

Per attivare le RTDN, devi prima configurare Cloud Pub/Sub utilizzando il tuo progetto Google Cloud Platform (GCP) e poi attivare le notifiche per la tua app. Se non hai familiarità con GCP e Cloud Pub/Sub, consulta la guida rapida.

Crea un argomento

Per iniziare a ricevere le notifiche, devi creare un argomento in cui Google Play deve pubblicare le notifiche. Per creare un argomento, segui le istruzioni riportate in Creare l'argomento.

Crea un abbonamento Pub/Sub

Per ricevere i messaggi pubblicati in un argomento, devi creare un abbonamento Pub/Sub per quell'argomento. Per creare una sottoscrizione Pub/Sub:

1. Leggi la guida per gli abbonati a Cloud Pub/Sub per acquisire familiarità con la configurazione dell'abbonamento come push o pull. In questo codelab, lavoreremo con un abbonamento pull che richiede che il server di backend sicuro avvii richieste al server Cloud Pub/Sub per recuperare i messaggi.

Consulta Pull o push delivery per decidere se un abbonamento push o pull è più adatto alla tua app.

2. Segui le istruzioni riportate nell'articolo Aggiungere un abbonamento per creare un abbonamento.

Concedere i diritti di pubblicazione sull'argomento

Cloud Pub/Sub richiede che tu conceda a Google Play i privilegi per pubblicare notifiche nel tuo argomento.

1. Apri la console Google Cloud.
2. Seleziona il tuo progetto, poi cerca "Pub/Sub" nella barra di ricerca e vai alla pagina di configurazione di Pub/Sub.
3. Trova l'argomento e apri l'impostazione delle autorizzazioni.
4. Fai clic su AGGIUNGI ENTITÀ per aggiungere il service account [e-mail] e concedergli il ruolo di Publisher Pub/Sub.
5. Fai clic su Salva per completare la configurazione dell'argomento.

Attivare le RTDN per la tua app

Scopri come configurare le notifiche in tempo reale per lo sviluppatore (RTDN) per migliorare significativamente l'integrazione di Fatturazione Play. Puoi migliorare l'affidabilità degli acquisti con messaggi personalizzati e prevenire frodi e abusi per migliorare il ROI complessivo.

Le notifiche in tempo reale forniscono aggiornamenti immediati da server a server direttamente da Google Play per eventi chiave, come rinnovi di abbonamenti, nuovi acquisti e problemi di pagamento. Aiutano i sistemi di backend a sincronizzarsi automaticamente con lo stato effettivo dei diritti degli utenti, superando i limiti lato client e consentendoti di reagire in modo immediato e appropriato.

Come attivare le notifiche in tempo reale per lo sviluppatore per la tua app:

1. Apri Google Play Console.
2. Selezionare l'app.
3. Vai a Monetizza con Google Play > Configurazione della monetizzazione.
4. Scorri fino alla sezione Notifiche in tempo reale per lo sviluppatore.
5. Seleziona Attiva notifiche in tempo reale.
6. Nel campo Nome argomento, inserisci il nome completo dell'argomento Cloud Pub/Sub che hai configurato in precedenza. Il nome dell'argomento deve essere nel formato projects/{project_id}/topics/{topic_name}, dove project_id è l'identificatore univoco del tuo progetto e topic_name è il nome dell'argomento creato in precedenza.
7. Fai clic su Invia messaggio di prova per inviare un messaggio di prova. L'esecuzione di una pubblicazione di test consente di assicurarsi che tutto sia configurato correttamente. Se la pubblicazione di test ha esito positivo, viene visualizzato un messaggio che indica che è andata a buon fine. Se hai allegato un abbonamento a questo argomento, dovresti ricevere il messaggio di test. Per un abbonamento pull, vai all'abbonamento in Cloud Console, fai clic su Visualizza messaggi e procedi con il pull dei messaggi. Devi confermare la ricezione di ogni messaggio estratto per evitare la consegna ripetuta da parte di Cloud Pub/Sub. Per un abbonamento push, controlla se il messaggio di test viene recapitato all'endpoint push. Un codice di risposta riuscito fungerà da messaggio di conferma. Se la pubblicazione non riesce, viene visualizzato un errore. Assicurati che il nome dell'argomento sia corretto e che il service account [e-mail] abbia accesso Pub/Sub Publisher all'argomento.
8. Scegli i tipi di notifiche che vuoi ricevere.

• Ricevi notifiche relative agli abbonamenti e a tutti gli acquisti annullati: ricevi notifiche in tempo reale per lo sviluppatore relative ad abbonamenti e acquisti annullati. Non riceverai notifiche per gli acquisti di prodotti a pagamento singolo.
• Ricevi tutte le notifiche per gli abbonamenti e i prodotti a pagamento singolo: ricevi notifiche per tutti gli eventi relativi ad abbonamenti e acquisti annullati. Riceverai anche eventi di acquisto di prodotti singoli, come ONE_TIME_PRODUCT_PURCHASED e ONE_TIME_PRODUCT_CANCELED. Per scoprire di più su questi eventi di acquisto, consulta Ciclo di vita dell'acquisto una tantum.

9. Fai clic su Salva modifiche.

Ora hai completato le notifiche per gli sviluppatori in tempo reale per la tua app, fornendoti gli strumenti per affrontare sfide comuni, come l'abbandono degli utenti tramite messaggi di recupero o frodi e abusi. Nella sezione successiva, creeremo un sottoscrittore nel server di backend sicuro per utilizzare i messaggi inviati all'argomento Cloud Pub/Sub.

4. Ricevere notifiche

È fondamentale mantenere aggiornato il server di backend sullo stato degli acquisti per offrire la migliore esperienza utente nella tua app. Ad esempio, quando un utente completa correttamente un acquisto con un pagamento nell'app, deve ricevere i contenuti sul proprio account il prima possibile.

Ciò richiede che il completamento dell'acquisto venga rilevato ed elaborato in modo tempestivo. Libreria Fatturazione Play offre diversi modi per rilevare gli acquisti nella tua app. Una volta rilevato un acquisto completato, la tua app deve inviare una notifica al server di backend per verificare l'acquisto, concedere i contenuti all'utente corretto e quindi comunicare a Google che l'acquisto è stato elaborato. Tuttavia, potrebbe succedere che la tua app non abbia rilevato l'acquisto in modo tempestivo per vari motivi. Ad esempio, un utente può effettuare un acquisto e ricevere la conferma da Google, ma il suo dispositivo perde la connettività di rete prima che il dispositivo e la tua app ricevano la notifica tramite l'interfaccia della libreria Fatturazione Play. RTDN fornisce controlli lato server aggiuntivi per aiutarti a gestire gli acquisti anche quando il client dell'utente presenta problemi. RTDN garantisce notifiche indipendenti al tuo server in caso di modifiche dello stato di acquisto, consentendoti di riconoscere le modifiche dello stato di acquisto quasi immediatamente tramite un secondo percorso indipendentemente dai potenziali problemi del cliente, garantendo una procedura di acquisto più affidabile.

In questa sezione creerai un sottoscrittore per utilizzare i messaggi inviati all'argomento Cloud Pub/Sub utilizzando le librerie client Cloud Pub/Sub. Queste librerie sono disponibili in diverse lingue. Nelle sezioni seguenti, aggiungeremo l'abbonato per verificare l'acquisto, concedere il diritto all'utente corretto e riconoscere/consumare l'acquisto sul server. Per questo codelab, utilizziamo Java.

Ogni pubblicazione effettuata in un argomento Cloud Pub/Sub contiene un singolo campo di dati con codifica base64.

{
 "message": {
   "attributes": {
     "key": "value"
   },
   "data": "eyAidmVyc2lvbiI6IHN0cmluZywgInBhY2thZ2VOYW1lIjogc3RyaW5nLCAiZXZlbnRUaW1lTWlsbGlzIjogbG9uZywgIm9uZVRpbWVQcm9kdWN0Tm90aWZpY2F0aW9uIjogT25lVGltZVByb2R1Y3ROb3RpZmljYXRpb24sICJzdWJzY3JpcHRpb25Ob3RpZmljYXRpb24iOiBTdWJzY3JpcHRpb25Ob3RpZmljYXRpb24sICJ0ZXN0Tm90aWZpY2F0aW9uIjogVGVzdE5vdGlmaWNhdGlvbiB9",
   "messageId": "136969346945"
 },
 "subscription": "projects/myproject/subscriptions/mysubscription"
}

Dopo aver decodificato il campo dati codificato in base64, DeveloperNotification contiene i seguenti campi:

{
 "version": string,
 "packageName": string,
 "eventTimeMillis": long,
 "oneTimeProductNotification": OneTimeProductNotification,
 "subscriptionNotification": SubscriptionNotification,
 "voidedPurchaseNotification": VoidedPurchaseNotification,
 "testNotification": TestNotification
}

Per maggiori informazioni, consulta la Guida di riferimento delle notifiche in tempo reale per lo sviluppatore.

Di seguito è riportato il codice di esempio di un NotificationReceiver per il server di backend sicuro per elaborare i messaggi Pub/Sub. Per eseguire l'autenticazione in Security Command Center, configura le credenziali predefinite dell'applicazione. Consulta Configurare l'autenticazione per un ambiente di sviluppo locale.

import com.google.cloud.pubsub.v1.AckReplyConsumer;
import com.google.cloud.pubsub.v1.MessageReceiver;
import com.google.cloud.pubsub.v1.Subscriber;
import com.google.pubsub.v1.ProjectSubscriptionName;
import com.google.pubsub.v1.PubsubMessage;
import java.util.Base64;
import org.json.JSONObject;

/** Real-time developer notifications receiver. */
public class NotificationReceiver {

 private NotificationReceiver() {}

 /*
  * Receive notification messages from the subscription.
  *
  * @param projectId The project ID of your Google Cloud Project.
  * @param subscriptionId The subscription ID of the subscriber to the pub/sub topic.
  */
 public static void receiveNotificationMessages(String projectId, String subscriptionId) {
   ProjectSubscriptionName subscriptionName =
       ProjectSubscriptionName.of(projectId, subscriptionId);

   try {
     Subscriber subscriber =
         Subscriber.newBuilder(subscriptionName, new NotificationMessageReceiver()).build();
     // Start the subscriber.
     subscriber.startAsync().awaitRunning();

     subscriber.awaitTerminated();
   } catch (IllegalStateException e) {
     System.out.println("Subscriber stopped: " + e);
   }
 }

 static class NotificationMessageReceiver implements MessageReceiver {

   @Override
   public void receiveMessage(PubsubMessage message, AckReplyConsumer consumer) {
     // Decode the data into a String from the message data field.
     String jsonString = new String(Base64.getDecoder().decode(message.getData().toStringUtf8()));
     // Parse the String into a JSON object.
     JSONObject messageJson = new JSONObject(jsonString);

     // Fetch the value for certain fields.
     String version = messageJson.getString("version");
     String packageName = messageJson.getString("packageName");
     System.out.println("version: " + version);
     System.out.println("packageName: " + packageName);

     // Validate the purchase and grant the entitlement as needed.
     // More details in the following sections.
     // ......

     // Acknowledge the message to avoid repeated delivery.
     consumer.ack();
   }
 }
}

Ora hai un ricevitore di notifiche che utilizza i messaggi inviati all'argomento Cloud Pub/Sub nel server di backend sicuro. Nelle sezioni seguenti, esamineremo le best practice per l'elaborazione dei messaggi RTDN nel server di backend.

5. Allegare gli identificatori utente al flusso di acquisto nella tua app

Quando il server riceve il messaggio RTDN sull'aggiornamento dello stato dell'acquisto, deve sapere quale utente ha effettuato l'acquisto per elaborarlo, ad esempio per inviare i contenuti all'utente corretto. Puoi farlo allegando gli identificatori utente che hai per l'utente che effettua l'acquisto utilizzando obfuscatedAccountId quando avvii il flusso di acquisto nella tua app. Un identificatore di esempio potrebbe essere una versione offuscata dell'accesso dell'utente nel tuo sistema. L'impostazione di questo parametro può aiutare Google a rilevare le frodi. Inoltre, può aiutarti a garantire che gli acquisti vengano attribuiti all'utente giusto, come descritto in Concessione di diritti agli utenti.

Di seguito sono riportati i codici di esempio per allegare l'identificatore utente all'avvio del flusso di acquisto nell'app impostando obfuscatedAccountId.

// An activity reference from which the billing flow will be launched.
Activity activity = ...;
// A user identifier, e.g. an obfuscated user id in your system.
String obfuscatedAccountId = ...;

ImmutableList<ProductDetailsParams> productDetailsParamsList =
    ImmutableList.of(
        ProductDetailsParams.newBuilder()
            // retrieve a value for "productDetails" by calling queryProductDetailsAsync()
            .setProductDetails(productDetails)
            // set the offer token to specify the offer to purchase when applicable, e.g., subscription products
            // .setOfferToken(offerToken)
            .build()
    );

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

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

Come vedrai nella sezione successiva, l'identificatore utente impostato nel flusso di acquisto verrà incluso nell'acquisto e potrà essere utilizzato per concedere i diritti all'utente corretto.

6. Verificare gli acquisti prima di concedere i diritti

In questa sezione esamineremo le best practice per verificare gli acquisti prima di concedere i diritti nel server di backend sicuro.

Dopo che un utente ha effettuato l'acquisto di un prodotto singolo, il sottoscrittore Pub/Sub nel tuo server di backend sicuro riceverà un messaggio Pub/Sub. Nel server di backend devi:

1. Analizza purchaseToken dal messaggio Pub/Sub. Devi conservare un registro di tutti i valori di purchaseToken per tutti gli acquisti.
2. Verifica che il valore di purchaseToken per l'acquisto corrente non corrisponda ad alcun valore di purchaseToken precedente. purchaseToken è univoco a livello globale, quindi puoi utilizzare questo valore in modo sicuro come chiave primaria nel tuo database.
3. Utilizza l'endpoint purchases.products:get nell'API Google Play Developer per verificare con Google che l'acquisto sia legittimo.

Utilizza l'endpoint purchases.subscriptionsv2:get nell'API Google Play Developer per gli abbonamenti.

4. Se l'acquisto è legittimo e non è stato utilizzato in passato, puoi concedere in sicurezza il diritto all'articolo in-app o all'abbonamento.
5. Devi concedere i diritti solo quando lo stato dell'acquisto è PURCHASED e assicurarti di gestire correttamente gli acquisti PENDING. Per ulteriori informazioni, consulta la sezione Gestione delle transazioni in sospeso.

Il seguente esempio di codice crea un client API per l'API Google Play Developer. Lo utilizzeremo per effettuare le chiamate API in un secondo momento.

import com.google.api.client.auth.oauth2.Credential;
import com.google.api.client.googleapis.auth.oauth2.GoogleCredential;
import com.google.api.client.googleapis.javanet.GoogleNetHttpTransport;
import com.google.api.client.http.HttpTransport;
import com.google.api.client.json.JsonFactory;
import com.google.api.client.json.gson.GsonFactory;
import com.google.api.services.androidpublisher.AndroidPublisher;
import com.google.api.services.androidpublisher.AndroidPublisherScopes;
import java.io.IOException;
import java.security.GeneralSecurityException;
import java.util.Collections;

/** Helper class to initialize the publisher APIs client library. */
public class AndroidPublisherHelper {
 /* Your application name */
 private static final String APPLICATION_NAME = "YourApplicationName";

 /* Load credentials from a JSON key file. Replace with the actual path to your downloaded service
  * account key file.
  */
 private static final String RESOURCES_CLIENT_SECRETS_JSON =
     "/path/to/your/service_account_key.json";

 /** Global instance of the JSON factory. */
 private static final JsonFactory JSON_FACTORY = GsonFactory.getDefaultInstance();

 /* The API client */
 private static final AndroidPublisher ANDROID_PUBLISHER = init();

 /**
  * Performs all necessary setup steps for running requests against the API.
  *
  * @return the {@link AndroidPublisher} service
  */
 private static AndroidPublisher init(){
   try {
     // Authorization.
     Credential credential =
         GoogleCredential.fromStream(
                 AndroidPublisherHelper.class.getResourceAsStream(RESOURCES_CLIENT_SECRETS_JSON))
             .createScoped(Collections.singleton(AndroidPublisherScopes.ANDROIDPUBLISHER));

     HttpTransport httpTransport = GoogleNetHttpTransport.newTrustedTransport();

     // Set up and return API client.
     return new AndroidPublisher.Builder(httpTransport, JSON_FACTORY, credential)
         .setApplicationName(ApplicationConfig.APPLICATION_NAME)
         .build();
   } catch (GeneralSecurityException | IOException ex) {
     throw new RuntimeException("fail to initialize the publisher APIs client library", ex);
   }
 }
}

Poi, aggiungiamo la logica per effettuare la chiamata API e modificare il ricevitore creato in precedenza per convalidare l'acquisto e concedere il diritto all'utente corretto.

In AndroidPublisherHelper, aggiungi il seguente metodo per recuperare ProductPurchase dall'endpoint Purchases.products:get nell'API Google Play Developer.

 /* Fetch the ProductPurchase for the one-time product purchase from
  * Purchases.products.get endpoint in the Google Play Developer API
  */
 public static ProductPurchase executeProductPurchasesGet(
     String packageName, String sku, String purchaseToken) {
   try {
     ProductPurchase productPurchase =
         ANDROID_PUBLISHER.purchases().products().get(packageName, sku, purchaseToken).execute();
     return productPurchase;
   } catch (IOException ex) {
     log.error("Exception was thrown while getting a product purchase", ex);
     // It is recommended to apply some retry mechanism, such as exponential backoff, to fetch the purchase in case of transient failures.
     return null;
   }
 }

In NotificationMessageReceiver, convalida l'acquisto e concedi il diritto all'utente corretto nel tuo sistema in base ai dati inclusi nella notifica. Devi continuare a monitorare purchaseToken nel tuo server per evitare l'elaborazione duplicata.

Consulta il riferimento alle notifiche in tempo reale per lo sviluppatore per tutti i tipi di notifiche che puoi ricevere da Google Play e gestirle nel tuo server in base ai requisiti della tua attività.

 @Override
 public void receiveMessage(PubsubMessage message, AckReplyConsumer consumer) {
   // Decode the data into a String from the message data field.
   String jsonString = new String(Base64.getDecoder().decode(message.getData().toStringUtf8()));
   // Parse the String into a JSON object.
   JSONObject messageJson = new JSONObject(jsonString);

   // Fetch the value for certain fields.
   String version = messageJson.getString("version");
   String packageName = messageJson.getString("packageName");

   // Process notification data based on your business requirements.
   // Process oneTimeProductNotification in the message.
   JSONObject oneTimeProductNotificationJson =
       messageJson.getJSONObject("oneTimeProductNotification");
   if (oneTimeProductNotificationJson != null) {
     String purchaseToken = oneTimeProductNotificationJson.getString("purchaseToken");
     String sku = oneTimeProductNotificationJson.getString("sku");
     int notificationType = oneTimeProductNotificationJson.getInt("notificationType");

     if (notificationType == 1) {
       // ONE_TIME_PRODUCT_PURCHASED - A one-time product was successfully purchased by a user.
       // Verify that the purchaseToken value does not match any previous purchaseToken values in
       // your backend system to avoid duplicate processing.
       ......
       // Fetch the ProductPurchase from Purchases.products.get endpoint
       ProductPurchase productPurchase =
         AndroidPublisherHelper.executeProductPurchasesGet(packageName, sku, purchaseToken);
       if (productPurchase != null && productPurchase.getPurchaseState() == 0) {
         // The purchase is valid and in PURCHASED state.

         // The account Id set in the App when launching the billing flow.
         String obfuscatedExternalAccountId = productPurchase.getObfuscatedExternalAccountId();
         // Grant the entitlement to the correct account for obfuscatedExternalAccountId in your
         // system.
       ......
       }
     }
     // Process subscriptionNotification in the message.
     JSONObject subscriptionNotificationJson = messageJson.getJSONObject("subscriptionNotification");
     if (subscriptionNotificationJson != null) {
       ......
     }
     // Process other notification data in the message as needed.
     ......
   }

   // Acknowledge the message to avoid repeated delivery.
   consumer.ack();
 }

7. Comunicare a Google che l'acquisto è stato elaborato

Dopo aver concesso i diritti, devi comunicare a Google che l'acquisto è stato elaborato chiamando gli endpoint purchases.products:consume o purchases.products:acknowledge nell'API Play Developer dal tuo server di backend sicuro per consumare un prodotto consumabile o confermare un prodotto non consumabile.

Utilizza l'endpoint purchases.subscriptions:acknowledge nell'API Google Play Developer per confermare gli abbonamenti.

In AndroidPublisherHelper, aggiungi i seguenti metodi per chiamare purchases.products:consume o purchases.products:acknowledge nell'API Google Play Developer.

 /* Consume the one-time product purchase by calling
  * Purchases.products.consume endpoint in the Google Play Developer API
  */
 public static void executeProductPurchasesConsume(
     String packageName, String sku, String purchaseToken) {
   try {
     ANDROID_PUBLISHER
       .purchases().products().consume(packageName, sku, purchaseToken).execute();
   } catch (IOException ex) {
     log.error("Exception was thrown while consuming a product purchase", ex);
     // It is recommended to apply some retry mechanism, such as exponential backoff, to ensure the purchase is correctly consumed in case of transient failures.
   }
 }

 /* Acknowledge the one-time product purchase by calling
  * Purchases.products.acknowledge endpoint in the Google Play Developer API
  */
 public static void executeProductPurchasesAcknowledge(
     String packageName, String sku, String purchaseToken) {
   try {
     ANDROID_PUBLISHER
       .purchases().products().acknowledge(packageName, sku, purchaseToken, new ProductPurchasesAcknowledgeRequest()).execute();
   } catch (IOException ex) {
     log.error("Exception was thrown while acknowledging a product purchase", ex);
     // It is recommended to apply some retry mechanism, such as exponential backoff, to ensure the purchase is correctly acknowledged in case of transient failures.
   }
 }

In NotificationMessageReceiver, utilizza l'acquisto del prodotto di consumo o conferma l'acquisto del prodotto non di consumo dopo aver concesso il diritto nel server di backend.

 @Override
 public void receiveMessage(PubsubMessage message, AckReplyConsumer consumer) {
   ......
       String obfuscatedExternalAccountId = productPurchase.getObfuscatedExternalAccountId();
       // Grant the entitlement to the correct account for obfuscatedExternalAccountId in your
       // system.
       ......
       // If the product is a consumable product, consume the purchase.
       AndroidPublisherHelper.executeProductPurchasesConsume(packageName, sku, purchaseToken);
       // Or if the product is a non-consumable product, acknowledge the purchase.
       // AndroidPublisherHelper.executeProductPurchasesAcknowledge(packageName, sku, purchaseToken);
  ......

 }

La conferma è obbligatoria, in quanto comunica a Google Play che all'utente sono stati concessi i diritti per l'acquisto. Devi confermare l'acquisto immediatamente dopo aver concesso i diritti.

Ottimo lavoro. Hai eseguito l'integrazione con le notifiche in tempo reale per lo sviluppatore, consentendo l'elaborazione affidabile degli acquisti, come dimostrato in questo codelab. Ora, per assicurarci che tutto funzioni perfettamente, esploriamo Play Billing Lab, uno strumento intuitivo progettato per aiutarti a testare l'integrazione della Fatturazione Play.

8. Testare con Play Billing Lab

Per eseguire il lancio in tutta sicurezza, devi testare l'integrazione durante lo sviluppo. Play Billing Lab è un'app Android senza costi che aiuta gli sviluppatori a testare la loro integrazione con il sistema di fatturazione di Google Play, fornendo un modo semplice e conveniente per testare le funzionalità di Fatturazione Play, integrare più velocemente e lanciare con maggiore sicurezza.

Play Billing Lab offre varie funzionalità di test per aiutarti a testare diversi scenari, tra cui:

• Modifica il paese di Play in Play Billing Lab e applica le impostazioni al test. Ciò consente di testare esperienze utente personalizzate in diversi paesi/regioni, indipendentemente da dove si trova fisicamente il tester.
• Testare ripetutamente le prove o le offerte di lancio con lo stesso account
• Testare le variazioni di prezzo degli abbonamenti senza influire sugli altri abbonati attivi
• Simula il codice di risposta della Libreria Fatturazione Play per eseguire test in vari scenari di errore
• Accelerare i rinnovi degli abbonamenti per velocizzare i test
• Esegui test con metodi di pagamento reali per ignorare determinati indicatori di rischio del flusso di acquisto

Aggiungiamo continuamente nuove funzionalità di test all'app Play Billing Lab. Puoi scaricare e installare Play Billing Lab dal Play Store o consultare Testare l'integrazione per saperne di più sui test con Play Billing Lab.

Utilizzare Play Billing Lab per testare BillingResponseCode

Testare tutti i flussi di BillingResponseCode durante l'integrazione dell'app con la libreria Fatturazione Play è una sfida comune, perché non hai molto controllo sulla comunicazione tra il Play Store e il backend di Google Play. La funzionalità Simulatore di risposte nell'app Play Billing Lab ti consente di configurare le risposte con codici di errore per la Libreria Fatturazione Play per testare vari scenari di errore complessi.

Ad esempio, hai implementato la logica nella tua app per utilizzare l'acquisto dopo che l'app ha rilevato l'acquisto riuscito. Vuoi testare lo scenario in cui la tua app non è riuscita a utilizzare l'acquisto a causa di un errore di rete e il ricevitore RTDN nel tuo server di backend rileva il messaggio e gestisce correttamente l'acquisto. Puoi utilizzare Response Simulator per simulare lo scenario per i test. Di seguito sono riportati i passaggi per eseguire il test con il simulatore di risposte di Play Billing Lab.

Test con il simulatore di risposte

Quando esegui i test con il simulatore di risposte, la tua app comunica con Play Billing Lab per ottenere il codice di risposta che hai configurato nel simulatore di risposte di Play Billing Lab.

Abilitare i test di override della fatturazione per la Libreria Fatturazione Play

Per attivare la comunicazione tra il simulatore di risposte e la tua app, devi prima attivare il test degli override di fatturazione per la libreria Fatturazione Play all'interno della tua app. Per farlo, aggiungi i seguenti tag di metadati al file AndroidManifest.xml della tua app.

<manifest ... >
  <application ... >
    ...
     <meta-data
      android:name="com.google.android.play.largest_release_audience.NONPRODUCTION"
      android:value="" />
    <meta-data
      android:name="com.google.android.play.billingclient.enableBillingOverridesTesting"
      android:value="true" />
  </application>
</manifest>

Crea la tua app con il file AndroidManifest.xml aggiornato. Ora la tua app è pronta per il simulatore di risposte di Play Billing Lab.

Anche se l'aggiunta del solo tag enableBillingOverridesTesting e l'impostazione su true è sufficiente per attivare il test degli override di fatturazione per la tua app, ti consigliamo di aggiungere anche il tag NONPRODUCTION. Il tag NONPRODUCTION impedisce il deployment accidentale dell'app nell'ambiente di produzione con il test degli override di fatturazione abilitato.

Quando esegui il deployment dell'app nell'ambiente di produzione dopo il test, devi utilizzare un file AndroidManifest.xml separato che non includa questi tag di metadati oppure assicurarti di averli rimossi dal file AndroidManifest.xml.

Simula gli errori della Libreria Fatturazione Play

Per eseguire il test con errori simulati della Libreria Fatturazione Play, configura prima il codice di risposta nell'app Play Billing Lab, poi esegui il test nella tua app.

Configurare un codice di risposta

1. Accedi all'app Play Billing Lab con un account tester delle licenze per la tua app. L'immagine seguente mostra la dashboard di Play Billing Lab,inclusa la scheda Simulatore di risposte.

2. Fai clic su Gestisci nella scheda Simulatore di risposte per accedere alla schermata del simulatore.
3. Quando richiesto, consenti le notifiche da Play Billing Lab per visualizzare lo stato della connessione della tua app.
4. Attiva l'opzione Simula risposta della Libreria Fatturazione Play, se non è già attiva.

5. Seleziona un codice di risposta per le API Play Billing Library che vuoi testare. Per simulare l'errore per l'acquisto di consumo, seleziona un codice di errore per l'API consumeAsync. Le selezioni vengono salvate automaticamente. Ora il simulatore di risposte è pronto a inviare i codici di risposta selezionati alla tua app.

Testa la tua app

Ora puoi testare la tua app per verificare se tutto funziona come previsto nello scenario di errore configurato. Apri l'app e attiva il metodo API Play Billing Library. Se la tua app effettua la chiamata consumeAsync per utilizzare l'acquisto, riceverà il codice di errore appena configurato. Puoi verificare se la tua app funziona correttamente in base al codice di errore e se il server di backend elabora correttamente l'acquisto.

Al termine del test, disattiva l'opzione Simula risposta Libreria Fatturazione Play per interrompere la simulazione della risposta.

Scopri di più sui test con Play Billing Lab o visita il Centro assistenza per saperne di più su come testare la fatturazione in-app con i tester delle licenze.

9. Complimenti!

Hai completato questo codelab e ora sei in grado di ottimizzare strategicamente la monetizzazione della tua app per migliorare l'esperienza utente e aumentare la soddisfazione degli utenti, le conversioni di acquisto e l'abbandono degli abbonati.

Sfruttando le notifiche in tempo reale per lo sviluppatore e l'app complementare Play Billing Lab, puoi gestire in modo proattivo gli eventi del ciclo di vita degli acquisti sia per gli acquisti una tantum che per gli abbonamenti.

Con questi strumenti, puoi implementare in modo efficace strategie di riconquista coinvolgenti, risolvere rapidamente le sfide di integrazione e, in definitiva, migliorare l'esperienza utente e i flussi di entrate per lanciare la tua app o il tuo gioco con sicurezza.

Completando questo codelab, ora possiedi le competenze per gestire l'intero percorso di acquisto e testare rigorosamente la tua implementazione con Play Billing Lab, garantendo un'esperienza utente senza interruzioni e massimizzando il tuo potenziale di monetizzazione su Google Play.