Guía de integración en la app para la elección de facturación

En esta guía, se describe cómo integrar tu app con las APIs de la Biblioteca de Facturación Play para que puedas ofrecer opciones de facturación a tus usuarios.

Integración con PBL

Puedes integrar la elección de facturación con la PBL en cuatro situaciones. Los casos de uso difieren según quién renderiza la pantalla de elección y dónde se realizará el pago. En la siguiente tabla, se describen los casos de integración:

En la siguiente ilustración, se detalla el flujo de selección de facturación para cada una de estas situaciones:

Situaciones de integración de PBL

Según tu situación de integración, sigue los pasos de esta sección para implementar la posibilidad de elección de facturación en tu app.

Manejo de la situación 1A

Google renderiza la pantalla de elección y la facturación alternativa se controla dentro de tu app. Sigue estos pasos para habilitar la elección de facturación en este caso:

1. Llama a enableBillingProgram con EnableBillingProgramParams cuando compiles tu instancia de BillingClient y, luego, inicia la conexión. Por ejemplo:

   Kotlin

   
   // Build the parameters to enable the Billing Choice program and assign the listener
   // to handle user selection of the developer-provided billing option.
   val params = EnableBillingProgramParams.newBuilder()
       .setBillingProgram(BillingProgram.BILLING_CHOICE)
       .setDeveloperProvidedBillingListener(developerProvidedBillingListener)
       .build()
   
   // Build the parameters to enable support for pending purchases.
   val pendingPurchasesParams = PendingPurchasesParams.newBuilder()
       .enableOneTimeProducts()
       .build()
   
   // Construct the BillingClient instance with the purchases updated listener,
   // pending purchases support, and the billing choice params.
   val billingClient = BillingClient.newBuilder(context)
       .setListener(purchasesUpdatedListener)
       .enablePendingPurchases(pendingPurchasesParams)
       .enableBillingProgram(params)
       .build()
   
   // Establish a connection to Google Play
   val billingResult = suspendCancellableCoroutine { continuation ->
       billingClient.startConnection(object : BillingClientStateListener {
           // Called when the connection setup process completes.
           override fun onBillingSetupFinished(billingResult: BillingResult) {
               // Resume the coroutine and pass back the BillingResult to the caller.
               continuation.resume(billingResult)
           }
   
           // Called if the connection to the Play Store service is dropped.
           // This prevents the await or suspension point from hanging indefinitely.
           override fun onBillingServiceDisconnected() {
               continuation.resume(
                   BillingResult.newBuilder()
                       .setResponseCode(BillingClient.BillingResponseCode.SERVICE_DISCONNECTED)
                       .setDebugMessage("Billing service disconnected during connection setup")
                       .build()
               )
           }
       })
   }
   
   

   Java

   
   EnableBillingProgramParams params = EnableBillingProgramParams.newBuilder()
           .setBillingProgram(BillingProgram.BILLING_CHOICE)
           .setDeveloperProvidedBillingListener(developerProvidedBillingListener)
           .build();
   
   BillingClient billingClient = BillingClient.newBuilder(context)
           .setListener(purchasesUpdatedListener)
           .enablePendingPurchases(
                   PendingPurchasesParams.newBuilder()
                           .enableOneTimeProducts()
                           .build()
           )
           .enableBillingProgram(params)
           .build();
   
   

2. Verifica que la opción de facturación renderizada por Google esté disponible para el usuario.

   Llama a isBillingProgramAvailableAsync para verificar la disponibilidad del programa y, luego, llama a queryProductDetailsAsync para mostrar los productos disponibles. Por ejemplo:

   Kotlin

   
   val (billingResult, billingProgramAvailabilityDetails) = billingClient.isBillingProgramAvailable(BillingProgram.BILLING_CHOICE)
   
   if (billingResult.responseCode == BillingResponseCode.OK) {
       val billingChoiceAvailabilityDetails = billingProgramAvailabilityDetails.billingChoiceAvailabilityDetails
       if (billingChoiceAvailabilityDetails != null &&
           billingChoiceAvailabilityDetails.choiceScreenType == ChoiceScreenType.GOOGLE_RENDERED
       ) {
           // Billing choice is available. Query products and proceed.
   
       } else {
           // Fallback to other available programs.
       }
   } else {
       // Fallback to other available programs.
   }
   
   
   

   Java

   
   // ...
   billingClient.isBillingProgramAvailableAsync(
       BillingProgram.BILLING_CHOICE,
       (billingResult, billingProgramAvailabilityDetails) -> {
           if (billingResult.getResponseCode() == BillingResponseCode.OK) {
               BillingChoiceAvailabilityDetails billingChoiceAvailabilityDetails =
                   billingProgramAvailabilityDetails.getBillingChoiceAvailabilityDetails();
   
               if (billingChoiceAvailabilityDetails != null &&
                   billingChoiceAvailabilityDetails.getChoiceScreenType() == ChoiceScreenType.GOOGLE_RENDERED) {
                   // Billing choice is available. Query products and proceed.
               } else {
                   // Fallback to other available programs.
               }
           } else {
               // Fallback to other available programs.
           }
       }
   );
   
   

   Nota: billingProgramAvailabilityDetails te indica si está disponible la pantalla de elección de facturación renderizada por Google o por el desarrollador.

3. Llama a launchBillingFlow para activar el flujo de compra cuando el usuario haga clic en Comprar. Si la opción de facturación está disponible, pasa DeveloperBillingOptionParams a BillingFlowParams. Por ejemplo:

   Kotlin

   
   val developerBillingOptionParams = DeveloperBillingOptionParams.newBuilder()
       .setBillingProgram(BillingProgram.BILLING_CHOICE)
       .build()
   
   val billingFlowParams = BillingFlowParams.newBuilder()
       .setProductDetailsParamsList(productDetailsParamsList)
       .enableDeveloperBillingOption(developerBillingOptionParams)
       .build()
   
   val billingResult = billingClient.launchBillingFlow(activity, billingFlowParams)
   
   

   Java

   
   DeveloperBillingOptionParams developerBillingOptionParams =
       DeveloperBillingOptionParams.newBuilder()
           .setBillingProgram(BillingProgram.BILLING_CHOICE)
           .build();
   BillingFlowParams billingFlowParams =
       BillingFlowParams.newBuilder()
           .setProductDetailsParamsList(productDetailsParamsList)
           .enableDeveloperBillingOption(developerBillingOptionParams)
           .build();
   
   BillingResult billingResult = billingClient.launchBillingFlow(activity, billingFlowParams);
   
   

   Nota: El control parental se muestra para los usuarios supervisados.

4. Controla la selección del usuario del tipo de facturación de la siguiente manera:

   • Si el usuario selecciona la Facturación Play, el resultado de la facturación se devuelve al PurchasesUpdatedListener registrado en el paso 1.
   • Si el usuario selecciona tu facturación alternativa, el resultado de la facturación se devuelve al DeveloperProvidedBillingListener registrado en el paso 1. El objeto DeveloperProvidedBillingDetails que se devuelve contiene un externalTransactionToken en este caso. El token se usará para generar informes de transacciones.

Situación de la manija 1B

El desarrollador renderiza la pantalla de elección y la facturación alternativa se controla dentro de tu app. Sigue estos pasos para habilitar la elección de facturación en esta situación:

1. Llama a enableBillingProgram sin DeveloperProvidedBillingListener en EnableBillingProgramParams cuando construyas una instancia de BillingClient y, luego, inicia la conexión. Por ejemplo:

   Kotlin

   
   // Build the parameters to enable the Billing Choice program.
   val params = EnableBillingProgramParams.newBuilder()
       .setBillingProgram(BillingProgram.BILLING_CHOICE)
       .build()
   
   // Construct the BillingClient instance with the purchases updated listener,
   // pending purchases support, and the billing choice params.
   val billingClient = BillingClient.newBuilder(context)
       .setListener(purchasesUpdatedListener)
       .enablePendingPurchases()
       .enableBillingProgram(params)
       .build()
   
   // Establish a connection to Google Play
   val billingResult = suspendCancellableCoroutine<BillingResult> { continuation ->
       billingClient.startConnection(object : BillingClientStateListener {
           // Called when the connection setup process completes.
           override fun onBillingSetupFinished(billingResult: BillingResult) {
               // Resume the coroutine and pass back the BillingResult to the caller.
               continuation.resume(billingResult)
           }
   
           // Called if the connection to the Play Store service is dropped.
           // This prevents the await or suspension point from hanging indefinitely.
           override fun onBillingServiceDisconnected() {
               continuation.resume(
                   BillingResult.newBuilder()
                       .setResponseCode(BillingClient.BillingResponseCode.SERVICE_DISCONNECTED)
                       .setDebugMessage("Billing service disconnected during connection setup")
                       .build()
               )
           }
       })
   }
   
   

   Java

   
   EnableBillingProgramParams params = EnableBillingProgramParams.newBuilder()
           .setBillingProgram(BillingProgram.BILLING_CHOICE)
           .build();
   
   BillingClient billingClient = BillingClient.newBuilder(context)
           .setListener(purchasesUpdatedListener)
           .enablePendingPurchases()
           .enableBillingProgram(params)
           .build();
   
   

2. Verifica que la opción de facturación renderizada por el desarrollador esté disponible para el usuario.

   Llama a isBillingProgramAvailableAsync para verificar la disponibilidad del programa y, luego, llama a queryProductDetailsAsync para mostrar los productos disponibles. Por ejemplo:

   Kotlin

   
   val (billingResult, billingProgramAvailabilityDetails) =
       billingClient.isBillingProgramAvailable(BillingProgram.BILLING_CHOICE)
   
   if (billingResult.responseCode == BillingResponseCode.OK) {
       val billingChoiceAvailabilityDetails =
           billingProgramAvailabilityDetails.billingChoiceAvailabilityDetails
   
       if (billingChoiceAvailabilityDetails != null &&
           billingChoiceAvailabilityDetails.choiceScreenType == ChoiceScreenType.DEVELOPER_RENDERED
       ) {
           // Billing choice is available. Query products and proceed.
           // You can inspect details such as:
           // - billingChoiceAvailabilityDetails.choiceScreenType
           // - billingChoiceAvailabilityDetails.isExternalLinkAvailable
       } else {
           // Fallback to other available programs.
       }
   } else {
       // Fallback to other available programs.
   }
   
   

   Java

   
   // ...
   billingClient.isBillingProgramAvailableAsync(
       BillingProgram.BILLING_CHOICE,
       (billingResult, billingProgramAvailabilityDetails) -> {
           if (billingResult.getResponseCode() == BillingResponseCode.OK) {
               BillingChoiceAvailabilityDetails billingChoiceAvailabilityDetails =
                   billingProgramAvailabilityDetails.getBillingChoiceAvailabilityDetails();
   
               if (billingChoiceAvailabilityDetails != null
                       && billingChoiceAvailabilityDetails.getChoiceScreenType() == ChoiceScreenType.DEVELOPER_RENDERED) {
                   // Billing choice is available. Query products and proceed.
                   // You can inspect details such as:
                   // - billingChoiceAvailabilityDetails.getChoiceScreenType()
                   // - billingChoiceAvailabilityDetails.isExternalLinkAvailable()
               } else {
                   // Fallback to other available programs.
               }
           } else {
               // Fallback to other available programs.
           }
       }
   );
   
   

   Nota: billingProgramAvailabilityDetails te indica si está disponible la pantalla de elección de facturación renderizada por Google o por el desarrollador.

3. Llama al método getBillingChoiceInfoAsync para obtener el banner de Facturación Play y la información de lealtad. Por ejemplo:

   Kotlin

   
   // 1. Create the params required for the request
   val params = GetBillingChoiceInfoParams.newBuilder()
       .setBillingProgram(BillingClient.BillingProgram.BILLING_CHOICE)
       .setPlayBillingChoiceImageLayout(GetBillingChoiceInfoParams.ImageLayout.RECTANGULAR_FOUR_BY_ONE)
       .build()
   
   // 2. Call the suspend method on your billingClient instance
   val (billingResult, playBillingChoiceInfo) = billingClient.getBillingChoiceInfo(params)
   
   if (billingResult.responseCode == BillingResponseCode.OK && playBillingChoiceInfo != null) {
       // Access the URL of the image associated with the Play Billing Choice
       val imageUrl = playBillingChoiceInfo.playBillingChoiceImageUrl
   
       // Access the Play Loyalty string information, if available
       val loyaltyInfo = playBillingChoiceInfo.playBillingLoyaltyInfo
   
       // Populate your developer-rendered UI elements
       playBillingLoyaltyTextView.text = loyaltyInfo
       loadImage(imageUrl, playBillingImageView)
   } else {
       // Handle error scenarios
   }
   
   

   Java

   
   // 1. Create the params required for the request
   GetBillingChoiceInfoParams params = GetBillingChoiceInfoParams.newBuilder()
       .setBillingProgram(BillingClient.BillingProgram.BILLING_CHOICE)
       .setPlayBillingChoiceImageLayout(GetBillingChoiceInfoParams.ImageLayout.RECTANGULAR_FOUR_BY_ONE)
       .build();
   // 2. Call the method asynchronously on your billingClient instance
   billingClient.getBillingChoiceInfoAsync(params, (billingResult, playBillingChoiceInfo) -> {
       if (billingResult.getResponseCode() == BillingResponseCode.OK && playBillingChoiceInfo != null) {
         // Access the URL of the image associated with the Play Billing Choice
           String imageUrl = playBillingChoiceInfo.getPlayBillingChoiceImageUrl();
           // Access the Play Loyalty string information, if available
           String loyaltyInfo = playBillingChoiceInfo.getPlayBillingLoyaltyInfo();
   
           // Populate your developer-rendered UI elements
           playBillingLoyaltyTextView.setText(loyaltyInfo);
             loadImage(imageUrl, playBillingImageView);
         } else {
             // Handle error scenarios
         }
   });
   
   

4. Crea un token de transacción externa con DeveloperBillingType establecido en IN_APP. Por ejemplo:

   Kotlin

   
   // Build the parameters specifying the billing program and that the billing type is IN_APP.
   val params = BillingProgramReportingDetailsParams.newBuilder()
       .setBillingProgram(BillingProgram.BILLING_CHOICE)
       .setDeveloperBillingType(DeveloperBillingType.IN_APP)
       .build()
   
   // Call the suspending extension function to request the reporting details
   val (billingResult, billingProgramReportingDetails) =
       billingClient.createBillingProgramReportingDetails(params)
       
   if (billingResult.responseCode != BillingResponseCode.OK) {
       // Handle failures such as retrying due to network errors.
       return
   }
   
   // Extract the transaction token from the returned reporting details
   val transactionToken = billingProgramReportingDetails?.externalTransactionToken
   
   // Persist the external transaction token locally. Pass it to
   // DeveloperBillingOptionParams when launchBillingFlow is called.
   // It can also be used as part of your external website
   
   

   Java

   
   BillingProgramReportingDetailsParams params =
       BillingProgramReportingDetailsParams.newBuilder()
           .setBillingProgram(BillingProgram.BILLING_CHOICE)
           .setDeveloperBillingType(DeveloperBillingType.IN_APP)
           .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
               // DeveloperBillingOptionParams when launchBillingFlow is called.
               // It can also be used as part of your external website
           }
       }
   );
   
   
   

5. Cuando el usuario hace clic en Comprar, llama a showBillingProgramInformationDialog para mostrar un diálogo de información. Por ejemplo, consulta Diálogo de información para los usuarios. En la solicitud, se deben establecer BillingProgram y transactionToken del paso 4.

   Nota: El control parental se muestra para los usuarios supervisados.

6. Inicia la pantalla de elección de facturación alternativa si el resultado del paso anterior es OK.

7. Controla la selección del usuario del tipo de facturación de la siguiente manera:

   • Si el usuario selecciona Play Billing, llama a launchBillingFlow siguiendo la orientación estándar de Play Billing. El resultado de facturación se devuelve al PurchasesUpdatedListener registrado en el paso 1.
   • Si el usuario selecciona tu facturación alternativa, debes controlar la transacción por tu cuenta y registrarla en Play con el token generado en el paso 4.

Cómo controlar la situación 2A

Google renderiza la pantalla de elección y la facturación alternativa se controla fuera de tu app. Sigue estos pasos para habilitar la opción de facturación en esta situación:

1. Llama a enableBillingProgram con EnableBillingProgramParams cuando compiles tu instancia de BillingClient y, luego, inicia la conexión. Por ejemplo:

   Kotlin

   
   // Build the parameters to enable the Billing Choice program and assign the listener
   // to handle user selection of the developer-provided billing option.
   val params = EnableBillingProgramParams.newBuilder()
       .setBillingProgram(BillingProgram.BILLING_CHOICE)
       .setDeveloperProvidedBillingListener(developerProvidedBillingListener)
       .build()
   
   // Build the parameters to enable support for pending purchases.
   val pendingPurchasesParams = PendingPurchasesParams.newBuilder()
       .enableOneTimeProducts()
       .build()
   
   // Construct the BillingClient instance with the purchases updated listener,
   // pending purchases support, and the billing choice params.
   val billingClient = BillingClient.newBuilder(context)
       .setListener(purchasesUpdatedListener)
       .enablePendingPurchases(pendingPurchasesParams)
       .enableBillingProgram(params)
       .build()
   
   // Establish a connection to Google Play
   val billingResult = suspendCancellableCoroutine { continuation ->
       billingClient.startConnection(object : BillingClientStateListener {
           // Called when the connection setup process completes.
           override fun onBillingSetupFinished(billingResult: BillingResult) {
               // Resume the coroutine and pass back the BillingResult to the caller.
               continuation.resume(billingResult)
           }
   
           // Called if the connection to the Play Store service is dropped.
           // This prevents the await or suspension point from hanging indefinitely.
           override fun onBillingServiceDisconnected() {
               continuation.resume(
                   BillingResult.newBuilder()
                       .setResponseCode(BillingClient.BillingResponseCode.SERVICE_DISCONNECTED)
                       .setDebugMessage("Billing service disconnected during connection setup")
                       .build()
               )
           }
       })
   }
   
   

   Java

   
   EnableBillingProgramParams params = EnableBillingProgramParams.newBuilder()
           .setBillingProgram(BillingProgram.BILLING_CHOICE)
           .setDeveloperProvidedBillingListener(developerProvidedBillingListener)
           .build();
   
   BillingClient billingClient = BillingClient.newBuilder(context)
           .setListener(purchasesUpdatedListener)
           .enablePendingPurchases(
                   PendingPurchasesParams.newBuilder()
                           .enableOneTimeProducts()
                           .build()
           )
           .enableBillingProgram(params)
           .build();
   
   

2. Verifica la disponibilidad de lo siguiente:

   • Opción de facturación renderizada por Google
   • Vínculo web externo

   Llama a isBillingProgramAvailableAsync para verificar la disponibilidad del programa y, luego, llama a queryProductDetailsAsync para mostrar los productos disponibles. Por ejemplo:

   Kotlin

   
   // Check the availability of the billing choice program asynchronously using coroutines
   val (billingResult, billingProgramAvailabilityDetails) =
       billingClient.isBillingProgramAvailable(BillingProgram.BILLING_CHOICE)
   
   // Ensure the billing program query succeeded
   if (billingResult.responseCode == BillingResponseCode.OK) {
       // Retrieve the availability details specific to the billing choice program
       val billingChoiceAvailabilityDetails =
           billingProgramAvailabilityDetails.billingChoiceAvailabilityDetails
   
       // Check if billing choice is available, renders via Google Play, and external link is supported
       if (billingChoiceAvailabilityDetails != null &&
           billingChoiceAvailabilityDetails.choiceScreenType == ChoiceScreenType.GOOGLE_RENDERED &&
           billingChoiceAvailabilityDetails.isExternalLinkAvailable
       ) {
           // Billing choice is available and external transaction links are supported. Query products and proceed.
       } else {
           // Fallback to other available programs.
       }
   } else {
       // Fallback to other available programs.
   }
   
   
   

   Java

   
   // ...
   billingClient.isBillingProgramAvailableAsync(
       BillingProgram.BILLING_CHOICE,
       (billingResult, billingProgramAvailabilityDetails) -> {
           if (billingResult.getResponseCode() == BillingResponseCode.OK) {
               BillingChoiceAvailabilityDetails billingChoiceAvailabilityDetails =
                   billingProgramAvailabilityDetails.getBillingChoiceAvailabilityDetails();
   
               if (billingChoiceAvailabilityDetails != null
                       && billingChoiceAvailabilityDetails.getChoiceScreenType() == ChoiceScreenType.GOOGLE_RENDERED
                       && billingChoiceAvailabilityDetails.isExternalLinkAvailable()) {
                   // Billing choice is available and external transaction links are supported.
                   // Query products and proceed.
               } else {
                   // Fallback to other available programs.
               }
           } else {
               // Fallback to other available programs.
           }
       }
   );
   
   
   

3. Llama a createBillingProgramReportingDetailsAsync para crear un token de transacción externa cuando el usuario muestre su intención de comprar. Por ejemplo:

   Kotlin

   
   // Build the parameters for creating reporting details
   val params =
       BillingProgramReportingDetailsParams.newBuilder()
           .setBillingProgram(BillingProgram.BILLING_CHOICE)
           .setDeveloperBillingType(DeveloperBillingType.EXTERNAL_LINK)
           .build()
   
   // Call the suspend function to create billing program reporting details
   val (billingResult, billingProgramReportingDetails) =
       billingClient.createBillingProgramReportingDetails(params)
   
   // Handle response failure cases
   if (billingResult.responseCode != BillingResponseCode.OK) {
       // Handle failures such as retrying due to network errors.
       return
   }
   
   // Retrieve the external transaction token
   val transactionToken =
       billingProgramReportingDetails?.externalTransactionToken
   
   // Persist the external transaction token locally. Pass it to
   // DeveloperBillingOptionParams when launchBillingFlow is called.
   // It can also be used as part of your external website
   
   

   Java

   
   BillingProgramReportingDetailsParams params =
       BillingProgramReportingDetailsParams.newBuilder()
           .setBillingProgram(BillingProgram.BILLING_CHOICE)
           .setDeveloperBillingType(DeveloperBillingType.EXTERNAL_LINK)
           .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
               // DeveloperBillingOptionParams when launchBillingFlow is called.
               // It can also be used as part of your external website.
           }
       }
   );
   
   

4. Llama a launchBillingFlow para activar el flujo de compra cuando el usuario haga clic en Comprar. Si la opción de facturación está disponible para el usuario, realiza lo siguiente:

   1. Pasa DeveloperBillingOptionParams a BillingFlowParams.
   2. Pasa el token de transacción externa del paso 3 a DeveloperBillingOptionParams.

   Por ejemplo:

   Kotlin

   
   // Build the developer billing option parameters with the external link URI,
   // the transaction token, and browser/app launch mode.
   val developerBillingOptionParams =
       DeveloperBillingOptionParams.newBuilder()
           .setBillingProgram(BillingProgram.BILLING_CHOICE)
           .setLinkUri(Uri.parse("https://www.example.com/external/purchase"))
           .setExternalTransactionToken(transactionToken)
           .setLaunchMode(
               DeveloperBillingOptionParams.LaunchMode.LAUNCH_IN_EXTERNAL_BROWSER_OR_APP
           )
           .build()
   
   

   Java

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

   Nota: El control parental se muestra para los usuarios supervisados.

5. Controla la selección del usuario del tipo de facturación de la siguiente manera:

   • Si el usuario selecciona Play Billing, llama a launchBillingFlow siguiendo la orientación estándar de Play Billing. El resultado de facturación se devuelve al PurchasesUpdatedListener registrado en el paso 1.
   • Si el usuario selecciona tu facturación alternativa, el resultado de la facturación se devuelve al DeveloperProvidedBillingListener registrado en el paso
     .
     1. El objeto DeveloperProvidedBillingDetails que se devuelve contiene el objeto externalTransactionToken que se pasó a DeveloperBillingOptionParams en el paso 4 si es un token válido.

Situación de control 2B

El desarrollador renderiza la pantalla de elección y la facturación alternativa se controla fuera de la app. Sigue estos pasos para habilitar la elección de facturación en esta situación:

1. Llama a enableBillingProgram sin DeveloperProvidedBillingListener en EnableBillingProgramParams cuando construyas una instancia de BillingClient y, luego, inicia la conexión. Por ejemplo:

   Kotlin

   
   // Build the parameters to enable the Billing Choice program.
   val params = EnableBillingProgramParams.newBuilder()
       .setBillingProgram(BillingProgram.BILLING_CHOICE)
       .build()
   
   // Construct the BillingClient instance with the purchases updated listener,
   // pending purchases support, and the billing choice params.
   val billingClient = BillingClient.newBuilder(context)
       .setListener(purchasesUpdatedListener)
       .enablePendingPurchases()
       .enableBillingProgram(params)
       .build()
   
   // Establish a connection to Google Play
   val billingResult = suspendCancellableCoroutine<BillingResult> { continuation ->
       billingClient.startConnection(object : BillingClientStateListener {
           // Called when the connection setup process completes.
           override fun onBillingSetupFinished(billingResult: BillingResult) {
               // Resume the coroutine and pass back the BillingResult to the caller.
               continuation.resume(billingResult)
           }
   
           // Called if the connection to the Play Store service is dropped.
           // This prevents the await or suspension point from hanging indefinitely.
           override fun onBillingServiceDisconnected() {
               continuation.resume(
                   BillingResult.newBuilder()
                       .setResponseCode(BillingClient.BillingResponseCode.SERVICE_DISCONNECTED)
                       .setDebugMessage("Billing service disconnected during connection setup")
                       .build()
               )
           }
       })
   }
   
   

   Java

   
   EnableBillingProgramParams params = EnableBillingProgramParams.newBuilder()
           .setBillingProgram(BillingProgram.BILLING_CHOICE)
           .build();
   
   BillingClient billingClient = BillingClient.newBuilder(context)
           .setListener(purchasesUpdatedListener)
           .enablePendingPurchases()
           .enableBillingProgram(params)
           .build();
   
   

2. Verifica la disponibilidad de lo siguiente:

   • Opción de facturación renderizada por Google
   • Vínculo web externo

   Llama a isBillingProgramAvailableAsync para verificar la disponibilidad del programa y, luego, llama a queryProductDetailsAsync para mostrar los productos disponibles. Por ejemplo:

   Kotlin

   
   // Check the availability of the billing choice program asynchronously using a coroutine
   val (billingResult, billingProgramAvailabilityDetails) =
       billingClient.isBillingProgramAvailable(BillingProgram.BILLING_CHOICE)
   
   // Ensure the response code is OK
   if (billingResult.responseCode == BillingResponseCode.OK) {
       // Retrieve the billing choice availability details
       val billingChoiceAvailabilityDetails =
           billingProgramAvailabilityDetails.billingChoiceAvailabilityDetails
   
       // Check if billing choice details are available, choice screen is developer-rendered,
       // and external transaction links are supported.
       if (billingChoiceAvailabilityDetails != null &&
           billingChoiceAvailabilityDetails.choiceScreenType == ChoiceScreenType.DEVELOPER_RENDERED &&
           billingChoiceAvailabilityDetails.isExternalLinkAvailable
       ) {
           // Billing choice is available and external transaction links are supported.
           // Query products and proceed.
       } else {
           // Fallback to other available programs.
       }
   } else {
       // Fallback to other available programs.
   }
   
   

   Java

   
   // ...
   
   billingClient.isBillingProgramAvailableAsync(
       BillingProgram.BILLING_CHOICE,
       (billingResult, billingProgramAvailabilityDetails) -> {
           if (billingResult.getResponseCode() == BillingResponseCode.OK) {
               BillingChoiceAvailabilityDetails billingChoiceAvailabilityDetails =
                   billingProgramAvailabilityDetails.getBillingChoiceAvailabilityDetails();
               if (billingChoiceAvailabilityDetails != null &&
                   billingChoiceAvailabilityDetails.getChoiceScreenType() == ChoiceScreenType.DEVELOPER_RENDERED &&
                   billingChoiceAvailabilityDetails.isExternalLinkAvailable()) {
                   // Billing choice is available and external transaction links are supported. Query products and proceed.
               } else {
                   // Fallback to other available programs.
               }
           } else {
               // Fallback to other available programs.
           }
       }
   );
   
   

3. Llama al método getBillingChoiceInfoAsync para obtener el banner de Facturación Play y la información de lealtad.

   Kotlin

   
   // 1. Create the params required for the request
   val params = GetBillingChoiceInfoParams.newBuilder()
       .setBillingProgram(BillingClient.BillingProgram.BILLING_CHOICE)
       .setPlayBillingChoiceImageLayout(GetBillingChoiceInfoParams.ImageLayout.RECTANGULAR_FOUR_BY_ONE)
       .build()
   
   // 2. Call the suspend method on your billingClient instance
   val (billingResult, playBillingChoiceInfo) = billingClient.getBillingChoiceInfo(params)
   
   if (billingResult.responseCode == BillingResponseCode.OK && playBillingChoiceInfo != null) {
       // Access the URL of the image associated with the Play Billing Choice
       val imageUrl = playBillingChoiceInfo.playBillingChoiceImageUrl
   
       // Access the Play Loyalty string information, if available
       val loyaltyInfo = playBillingChoiceInfo.playBillingLoyaltyInfo
   
       // Populate your developer-rendered UI elements
       playBillingLoyaltyTextView.text = loyaltyInfo
       loadImage(imageUrl, playBillingImageView)
   } else {
       // Handle error scenarios
   }
   
   

   Java

   
   // 1. Create the params required for the request
   GetBillingChoiceInfoParams params = GetBillingChoiceInfoParams.newBuilder()
       .setBillingProgram(BillingClient.BillingProgram.BILLING_CHOICE)
       .setPlayBillingChoiceImageLayout(GetBillingChoiceInfoParams.ImageLayout.RECTANGULAR_FOUR_BY_ONE)
       .build();
   // 2. Call the method asynchronously on your billingClient instance
   billingClient.getBillingChoiceInfoAsync(params, (billingResult, playBillingChoiceInfo) -> {
       if (billingResult.getResponseCode() == BillingResponseCode.OK && playBillingChoiceInfo != null) {
         // Access the URL of the image associated with the Play Billing Choice
           String imageUrl = playBillingChoiceInfo.getPlayBillingChoiceImageUrl();
           // Access the Play Loyalty string information, if available
           String loyaltyInfo = playBillingChoiceInfo.getPlayBillingLoyaltyInfo();
   
           // Populate your developer-rendered UI elements
           playBillingLoyaltyTextView.setText(loyaltyInfo);
             loadImage(imageUrl, playBillingImageView);
         } else {
             // Handle error scenarios
         }
   });
   
   

4. Llama a createBillingProgramReportingDetailsAsync para crear un token de transacción externa cuando el usuario muestre su intención de comprar. Por ejemplo:

   Kotlin

   
   // Build the parameters for creating reporting details
   val params =
       BillingProgramReportingDetailsParams.newBuilder()
           .setBillingProgram(BillingProgram.BILLING_CHOICE)
           .setDeveloperBillingType(DeveloperBillingType.EXTERNAL_LINK)
           .build()
   
   // Call the suspend function to create billing program reporting details
   val (billingResult, billingProgramReportingDetails) =
       billingClient.createBillingProgramReportingDetails(params)
   
   // Handle response failure cases
   if (billingResult.responseCode != BillingResponseCode.OK) {
       // Handle failures such as retrying due to network errors.
       return
   }
   
   // Retrieve the external transaction token
   val transactionToken =
       billingProgramReportingDetails?.externalTransactionToken
   
   // Persist the external transaction token locally. Pass it to
   // DeveloperBillingOptionParams when launchBillingFlow is called.
   // It can also be used as part of your external website
   
   

   Java

   
   BillingProgramReportingDetailsParams params =
       BillingProgramReportingDetailsParams.newBuilder()
           .setBillingProgram(BillingProgram.BILLING_CHOICE)
           .setDeveloperBillingType(DeveloperBillingType.EXTERNAL_LINK)
           .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
               // DeveloperBillingOptionParams when launchBillingFlow is called.
               // It can also be used as part of your external website.
           }
       }
   );
   
   

5. Lanza tu pantalla de selección alternativa cuando el usuario haga clic en Comprar.

6. Controla la selección del usuario del tipo de facturación de la siguiente manera:

   • Si el usuario selecciona Play Billing, llama a launchBillingFlow siguiendo la orientación estándar de Play Billing. El resultado de facturación se devuelve al PurchasesUpdatedListener registrado en el paso 1.

     Se muestran los controles parentales para los usuarios supervisados.

   • Si el usuario selecciona tu facturación alternativa, llama a launchExternalLink. Por ejemplo:

     Kotlin

     
     // An activity reference from which the purchase flow will be launched.
     val activity: Activity = ...
     
     val params = LaunchExternalLinkParams.newBuilder()
         .setBillingProgram(BillingProgram.BILLING_CHOICE)
         // You can pass along the external transaction token from
         // BillingProgramReportingDetails as a URL parameter in the URI
         .setLinkUri(yourLinkUri)
         .setLinkType(LaunchExternalLinkParams.LinkType.LINK_TO_DIGITAL_CONTENT_OFFER)
         .setLaunchMode(
             LaunchExternalLinkParams.LaunchMode.LAUNCH_IN_EXTERNAL_BROWSER_OR_APP
         )
         .build()
     
     // Call launchExternalLink with a callback
     billingClient.launchExternalLink(activity, params) { billingResult ->
         if (billingResult.responseCode == BillingResponseCode.OK) {
             // Proceed with the rest of the purchase flow. If the user
             // purchases an item, be sure to report the transaction to Google
             // Play.
         } else {
             // Handle failures such as retrying due to network errors.
         }
     }
     
     

     Java

     
     // An activity reference from which the purchase flow will be launched.
     Activity activity = ...;
     
     LaunchExternalLinkParams params = LaunchExternalLinkParams.newBuilder()
         .setBillingProgram(BillingProgram.BILLING_CHOICE)
         // You can pass along the external transaction token from
         // BillingProgramReportingDetails as a URL parameter in the URI
         .setLinkUri(yourLinkUri)
         .setLinkType(LaunchExternalLinkParams.LinkType.LINK_TO_DIGITAL_CONTENT_OFFER)
         .setLaunchMode(
             LaunchExternalLinkParams.LaunchMode.LAUNCH_IN_EXTERNAL_BROWSER_OR_APP)
         .setExternalTransactionToken(transactionToken)
         .build();
     
     LaunchExternalLinkResponseListener listener =
         new LaunchExternalLinkResponseListener() {
           @Override
           public void onLaunchExternalLinkResponse(BillingResult billingResult) {
             if (billingResult.getResponseCode() == BillingResponseCode.OK) {
               // Proceed with the rest of the purchase flow. If the user
               // purchases an item, be sure to report the transaction to Google
               // Play.
             } else {
               // Handle failures such as retrying due to network errors.
             }
           }
         };
     
     billingClient.launchExternalLink(activity, params, listener);
     
     

   • Pasa el token de transacción externa del paso 4 a LaunchExternalLinkParams. Si devuelve OK, continúa con la transacción y repórtala a Google Play.

     El control parental se muestra para los usuarios supervisados.

Opción de facturación durante el reemplazo de la suscripción

En el caso del reemplazo de suscripciones, no se debe mostrar la pantalla de elección del usuario, ya que la elección del usuario para la compra original se conserva para actualizaciones y cambios a versiones inferiores.

Si la compra original se procesó a través de la Facturación de Google Play, debes llamar a launchBillingFlow con la información estándar del reemplazo de suscripciones de la Facturación de Google Play.

Sin embargo, si la compra original se procesó a través de una facturación alternativa, el manejo de los reemplazos de suscripciones difiere ligeramente según las situaciones.

Reemplazo de suscripción en la situación 1A

Los usuarios que soliciten una actualización o un cambio a una versión inferior deben pasar por el sistema de facturación alternativo del desarrollador sin volver a pasar por la experiencia de elección del usuario.

Para ello, llama a launchBillingFlow cuando el usuario solicite una actualización o un cambio a una versión inferior. Usa setOriginalExternalTransactionId dentro del objeto SubscriptionUpdateParams en los parámetros para proporcionar el ID de transacción externo para la compra original. Esto no muestra la pantalla de elección del usuario, ya que la elección del usuario para la compra original se conserva para actualizaciones y cambios a versiones anteriores. En este caso, la llamada a launchBillingFlow genera un nuevo token de transacción externa para la transacción que puedes recuperar desde la devolución de llamada.

// The external transaction ID from the current
// alternative billing subscription.
val externalTransactionId = //... ;

val developerBillingOptionParams = DeveloperBillingOptionParams.newBuilder()
    .setBillingProgram(BillingProgram.BILLING_CHOICE)
    .build()

val billingFlowParams = BillingFlowParams.newBuilder()
    .setProductDetailsParamsList(
        listOf(
            BillingFlowParams.ProductDetailsParams.newBuilder()
                // Fetched using queryProductDetailsAsync.
                .setProductDetails(productDetailsNewPlan)
                // offerIdToken can be found in
                // ProductDetails=>SubscriptionOfferDetails.
                .setOfferToken(offerTokenNewPlan)
                .build()
        )
    )
    .setSubscriptionUpdateParams(
        BillingFlowParams.SubscriptionUpdateParams.newBuilder()
            .setOriginalExternalTransactionId(externalTransactionId)
            .build()
    )
    .enableDeveloperBillingOption(developerBillingOptionParams)
    .build()

val billingResult = billingClient.launchBillingFlow(activity, billingFlowParams)

// When the user selects the alternative billing flow,
// the DeveloperProvidedBillingListener is triggered.

// The external transaction ID from the current
// alternative billing subscription.
String externalTransactionId = //... ;

DeveloperBillingOptionParams developerBillingOptionParams =
    DeveloperBillingOptionParams.newBuilder()
        .setBillingProgram(BillingProgram.BILLING_CHOICE)
        .build();

List<ProductDetailsParams> productDetailsParamsList = new ArrayList<>();
productDetailsParamsList.add(
    ProductDetailsParams.newBuilder()
        // Fetched using queryProductDetailsAsync.
        .setProductDetails(productDetailsNewPlan)
        // offerIdToken can be found in
        // ProductDetails=>SubscriptionOfferDetails
        .setOfferToken(offerTokenNewPlan)
        .build());

BillingFlowParams billingFlowParams =
    BillingFlowParams.newBuilder()
        .setProductDetailsParamsList(productDetailsParamsList)
        .setSubscriptionUpdateParams(
            SubscriptionUpdateParams.newBuilder()
                .setOriginalExternalTransactionId(externalTransactionId)
                .build())
        .enableDeveloperBillingOption(developerBillingOptionParams)
        .build();

BillingResult billingResult = billingClient.launchBillingFlow(activity, billingFlowParams);

// When the user selects the alternative billing flow,
// the DeveloperProvidedBillingListener is triggered.

Cuando se complete la actualización o el cambio a una versión inferior, debes informar una nueva transacción con el token de transacción externa que obtuviste en la llamada anterior para la compra de la nueva suscripción.

Reemplazo de suscripción en la situación 1B

En este caso, se debe generar un nuevo token de transacción externa. La única diferencia con una compra normal es que, en este caso, se conserva la elección del usuario y no es necesario mostrar la pantalla de elección para actualizar o cambiar a una versión anterior. Sin embargo, debes mostrar el diálogo de información única y el reconocimiento parental.

Para ver un ejemplo de código de integración, consulta el paso 4 del caso 1B: El desarrollador renderiza la pantalla de selección y la facturación alternativa se controla dentro de tu app.

Cuando se complete la actualización o el cambio a una versión inferior, debes informar una nueva transacción con el token de transacción externa que obtuviste en la llamada anterior para la compra de la nueva suscripción.

Reemplazo de suscripción en la situación 2A

Para las suscripciones que se compraron originalmente a través del sitio web del desarrollador o una app de pagos después de la elección del usuario, los usuarios que solicitan una actualización o un cambio a una versión inferior deben pasar por el sitio web del desarrollador o una app de pagos sin volver a pasar por la experiencia de elección del usuario.

Para ello, llama a launchBillingFlow cuando el usuario solicite una actualización o un cambio a una versión inferior. En lugar de especificar otros parámetros en el objeto SubscriptionUpdateParams, usa setOriginalExternalTransactionId y proporciona el ID de transacción externo para la compra original. También se debe proporcionar DeveloperBillingOptionParams en esta llamada. Esto no muestra la pantalla de elección del usuario, ya que la elección del usuario para la compra original se conserva para actualizaciones y cambios a versiones anteriores. Por ejemplo:

val externalTransactionId = //... ;

// 1. Construct DeveloperBillingOptionParams indicating the billing program
val developerBillingOptionParams = DeveloperBillingOptionParams.newBuilder()
    .setBillingProgram(BillingClient.BillingProgram.BILLING_CHOICE)
    .build()

// 2. Build BillingFlowParams combining DeveloperBillingOptionParams and SubscriptionUpdateParams
val billingFlowParams = BillingFlowParams.newBuilder()
    .setProductDetailsParamsList(
        listOf(
            BillingFlowParams.ProductDetailsParams.newBuilder()
                // Fetched using queryProductDetailsAsync.
                .setProductDetails(productDetailsNewPlan)
                // offerIdToken can be found in ProductDetails=>SubscriptionOfferDetails.
                .setOfferToken(offerTokenNewPlan)
                .build()
        )
    )
    .setSubscriptionUpdateParams(
        SubscriptionUpdateParams.newBuilder()
            .setOriginalExternalTransactionId(externalTransactionId)
            .build()
    )
    .enableDeveloperBillingOption(developerBillingOptionParams)
    .build()

String externalTransactionId = //... ;

// 1. Construct DeveloperBillingOptionParams indicating the billing program
DeveloperBillingOptionParams developerBillingOptionParams =
    DeveloperBillingOptionParams.newBuilder()
        .setBillingProgram(BillingClient.BillingProgram.BILLING_CHOICE)
        .build();

// 2. Add ProductDetailsParams
List productDetailsParamsList = new ArrayList<>();
productDetailsParamsList.add(
    ProductDetailsParams.newBuilder()
        // Fetched using queryProductDetailsAsync.
        .setProductDetails(productDetailsNewPlan)
        // offerIdToken can be found in ProductDetails=>SubscriptionOfferDetails
        .setOfferToken(offerTokenNewPlan)
        .build());

// 3. Build BillingFlowParams combining DeveloperBillingOptionParams and SubscriptionUpdateParams
BillingFlowParams billingFlowParams =
    BillingFlowParams.newBuilder()
        .setProductDetailsParamsList(productDetailsParamsList)
        .setSubscriptionUpdateParams(
            SubscriptionUpdateParams.newBuilder()
                .setOriginalExternalTransactionId(externalTransactionId)
                .build())
        .enableDeveloperBillingOption(developerBillingOptionParams)
        .build();

También debes generar un nuevo token de transacción externa. Por ejemplo:

val params =
    BillingProgramReportingDetailsParams.newBuilder()
        .setBillingProgram(BillingProgram.BILLING_CHOICE)
        .setDeveloperBillingType(DeveloperBillingType.EXTERNAL_LINK)
        .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.
        }
    }
)

BillingProgramReportingDetailsParams params =
    BillingProgramReportingDetailsParams.newBuilder()
        .setBillingProgram(BillingProgram.BILLING_CHOICE)
        .setDeveloperBillingType(DeveloperBillingType.EXTERNAL_LINK)
        .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.
      }
    });

Después de generar el token nuevo, debes llamar al método launchBillingFlow para iniciar el flujo de compra.

Cuando se complete la actualización o el cambio a una versión inferior, debes informar una nueva transacción con el token de transacción externa que obtuviste en la llamada anterior para la compra de la nueva suscripción.

Reemplazo de suscripción en la situación 2B

Los pasos para controlar el reemplazo de suscripciones en este caso son similares a los que se describen en Reemplazo de suscripciones en el caso 2A. La única diferencia es que, después de generar el token de transacción, en lugar de llamar al método launchBillingFlow, debes llamar a launchExternalLink para mostrar el diálogo de renuncia de responsabilidad del vínculo externo. En este caso, se conserva la elección del usuario y no es necesario que muestres la pantalla de elección para la actualización o el cambio a una versión inferior.

Para ver un código de integración de muestra, consulta el paso 6 del Escenario 2B: El desarrollador renderiza la pantalla de selección y la facturación alternativa se controla dentro de tu app.

Cuando se complete la actualización o el cambio a una versión inferior, debes informar una nueva transacción con el token de transacción externa que obtuviste en la llamada anterior para la compra de la nueva suscripción.