Agrega ofertas de pedido por adelantado para productos únicos

1. Introducción

En este codelab, te enfocarás en crear un producto único (OTP) y agregar una oferta de pedido por adelantado para el producto.

Nota: Antes de comenzar este codelab, debes solicitar acceso a la función de pedido por adelantado completando el formulario de interés sobre el PAA para productos únicos.

Público

Este codelab está dirigido a desarrolladores de apps para Android que estén familiarizados con los productos únicos y deseen comprender cómo agregar ofertas de pedido por adelantado a sus productos únicos.

Requisitos previos

Si no conoces los productos únicos, te recomendamos que completes el codelab Desbloquea nuevos mercados con precios de productos regionales.

Qué aprenderás

Cómo usar Google Play Console para crear ofertas de pedido por adelantado para tus productos únicos
Cómo usar las APIs de la Biblioteca de Facturación Play para consultar productos únicos y los detalles de la oferta de pedido por adelantado correspondiente

Qué necesitarás

Acceso a la Google Play Console con una cuenta de desarrollador (si no tienes una cuenta de desarrollador, debes crear una)
Una app de ejemplo para este codelab que puedes descargar desde GitHub.
Android Studio.

2. Compila la app de ejemplo

En este codelab, se usa una app de ejemplo para Android para enseñarte a administrar productos únicos. La app de ejemplo está diseñada para ser una app para Android completamente funcional que tiene el código fuente completo que muestra los siguientes aspectos:

Integración de la app con PBL
Recuperación de productos únicos y las ofertas de pedido por adelantado relacionadas
Ejecución de flujos de compra para precios regionales

En el siguiente video de demostración, se muestra cómo se verá y se comportará la app de ejemplo después de que se implemente y se ejecute.

Si ya estás familiarizado con los productos únicos y la Biblioteca de Facturación Play (PBL), puedes descargar la app de ejemplo y usarla.

Requisitos previos

Antes de compilar y de implementar la app de ejemplo, haz lo siguiente:

Crea una cuenta de desarrollador de Google Play Console. Si ya tienes una cuenta de desarrollador, omite este paso.
Crea una app nueva en Play Console. Cuando crees una app, puedes especificar cualquier nombre de app para la app de ejemplo.
Instala Android Studio.

Compilación

El objetivo de este paso de compilación es generar un archivo de Android App Bundle firmado de la app de ejemplo.

Para generar el Android App Bundle, sigue estos pasos:

Descarga la app de ejemplo desde GitHub.
Compila la app de ejemplo. Antes de compilar, cambia el nombre del paquete de la app de ejemplo y, luego, compila. Si tienes paquetes de otras apps en Play Console, asegúrate de que el nombre del paquete que proporcionas para la app de ejemplo sea único.

Nota: Cuando compilas la app de ejemplo, solo se crea un archivo APK que puedes usar para pruebas locales. Sin embargo, cuando ejecutas la app, no se recuperan los productos ni los precios porque no se configuraron en Play Console.
Genera un Android App Bundle firmado.

El siguiente paso es subir el Android App Bundle a Google Play Console.

3. Crea un OTP con pedido por adelantado en Play Console

Para crear productos únicos (OTP) en Google Play Console, debes tener una app en Play Console. Crea una app en Play Console y, luego, sube el paquete de aplicación firmado que creaste anteriormente.

Crea una app

Para crear una app, haz lo siguiente:

Accede a la Google Play Console con tu cuenta de desarrollador.
Haz clic en Crear app. Esto abre la página Crear app.
Ingresa un nombre de app, selecciona el idioma predeterminado y otros detalles relacionados con la app.
Haz clic en Crear app.

Ahora puedes subir el paquete de aplicación firmado de la app de ejemplo.

Sube el paquete de aplicación firmado

Sube el paquete de aplicación firmado al segmento de pruebas internas de Google Play Console. Solo después de subirlo, puedes configurar las funciones relacionadas con la monetización en Play Console.
1. Haz clic en Prueba y lanzamiento > Pruebas > Lanzamiento interno > Crear lanzamiento nuevo.
2. Ingresa un nombre de lanzamiento y sube el archivo APK firmado.
3. Haz clic en Siguiente y, luego, en Guardar y publicar.

Ahora puedes crear los productos únicos.

Crea un producto único

Ahora, crea el producto único que quieres que compren los usuarios.

Abre la app de ejemplo en Google Play Console y navega a Monetizar con Play > Productos > Productos únicos.
Haz clic en Crear un producto único.
Ingresa los siguientes detalles del producto:
- ID del producto: Ingresa un ID único. Por ejemplo, upcoming_movie_1.
- Etiquetas(opcional): Agrega etiquetas relevantes.
- Nombre: Ingresa un nombre de producto. Por ejemplo, Product Movie.
- Descripción: Ingresa una descripción del producto. Por ejemplo, Product Description.
- Una imagen de ícono que quieras agregar(opcional): Sube un ícono que represente tu producto.
Nota: A los efectos de este codelab, puedes omitir la configuración de la sección Impuestos, cumplimiento y programas.
Haz clic en Siguiente.
Agrega una opción de compra y configura su disponibilidad regional. Un producto único necesita al menos una opción de compra, que define cómo se otorga el derecho, su precio y la disponibilidad regional. Para este codelab, agregaremos la opción estándar Comprar para el producto.En la sección Opción de compra, ingresa los siguientes detalles:
- ID de la opción de compra: Ingresa un ID único. Por ejemplo, buy-movie.
- Tipo de compra: Selecciona Comprar.
- Etiquetas(opcional): Agrega etiquetas específicas para esta opción de compra.
- Haz clic en Opciones avanzadas (opcional) para configurar las opciones avanzadas. A los efectos de este codelab, puedes omitir la configuración de las opciones avanzadas.
A continuación, debes configurar la disponibilidad y el precio regionales para la opción de compra. En la disponibilidad regional, especificarás las regiones en las que estará disponible tu producto, incluidas las regiones en las que aún no se publicó tu app. De forma predeterminada, habrá una opción de compra disponible en todas las regiones.En la sección Disponibilidad y precios, haz clic en Editar disponibilidad y acceso.
1. Selecciona Establecer como no disponible.
Ten en cuenta que todas las regiones se seleccionan automáticamente y se configuran como Disponibles.
1. Anula la selección del país United States y, luego, haz clic en Establecer como no disponible. Ahora, el producto único solo estará disponible en United States.
2. En el menú desplegable Todas las regiones, selecciona Países y regiones disponibles. Solo deberías ver United States.
3. Haz clic en el ícono de Precio. Se mostrará un diálogo para establecer el precio.
4. Ingresa 10 USD y, luego, haz clic en Guardar.
Haz clic en Guardar como borrador.

Nota: Todavía no actives la opción de compra. La activaremos después de configurar la oferta de pedido por adelantado. Esto se debe a que no puedes agregar una oferta de pedido por adelantado a una opción de compra activa cuya disponibilidad regional esté establecida.

Cómo agregar una oferta de pedido por adelantado

Ahora, agregarás una oferta de pedido por adelantado para la opción de compra que creaste anteriormente. Una oferta de pedido por adelantado permite a los usuarios comprar tu artículo antes de su lanzamiento oficial. Ten en cuenta que las ofertas de pedido por adelantado solo se admiten para la opción de compra Comprar y solo se pueden configurar para productos nuevos en una región.

Para agregar una oferta de pedido por adelantado, debes seguir estos 2 pasos:

Prepara la opción de compra Comprar para la oferta de pedido por adelantado.
Agrega la oferta de pedido por adelantado para la opción de compra.

Prepara la opción de compra Comprar para la oferta de pedido por adelantado

Abre la app de ejemplo en Google Play Console y navega a Monetizar con Play > Productos > Productos únicos.
En la página Productos únicos, haz clic en la flecha hacia la derecha de tu producto (upcoming_movie_1). Se abrirá la página Editar producto único.
Haz clic en la flecha hacia la derecha de la opción de compra buy-movie que creaste anteriormente. Se abrirá la página Editar opción de compra.
Haz clic en Editar disponibilidad y acceso y, luego, selecciona Establecer como disponible y permitir que los usuarios hagan pedidos por adelantado.
En el menú desplegable Todas las regiones, selecciona Países y regiones disponibles. Solo debería mostrar United States que configuraste anteriormente.
Selecciona el país y, luego, haz clic en Establecer como disponible solo para pedidos por adelantado.
Haz clic en Guardar.

Ten en cuenta que aún no agregaste una oferta de pedido por adelantado a tu opción de compra. El siguiente paso es agregar la oferta de pedido por adelantado.

Cómo agregar una oferta de pedido por adelantado

Abre la app de ejemplo en Google Play Console y navega a Monetizar con Play > Productos > Productos únicos.
En la página Productos únicos, haz clic en Agregar oferta > Pedido por adelantado para tu producto (upcoming_movie_1). Se abrirá la página Agrega un pedido por adelantado.
Ingresa los detalles del pedido por adelantado:
- ID del pedido por adelantado: Ingresa preorder-offer-1.
- Agregar un descuento(opcional): Puedes seleccionar Ninguno, Porcentaje o Descuento absoluto. A los efectos de este codelab, selecciona Ninguno.
- Etiquetas(opcional): Agrega etiquetas relevantes.
- Fecha y hora de inicio: Establece una fecha que sea dentro de 3 días como mínimo.
- Fecha y hora de finalización: Establece una fecha que sea al menos 24 horas después de la fecha de inicio.
- Disponibilidad después del período de pedido por adelantado: Elige si el producto estará disponible inmediatamente después del período de pedido por adelantado o en una fecha y hora posteriores específicas.
- Garantía de precio más bajo(opcional): Selecciona esta opción si quieres que a los usuarios se les cobre el precio más bajo entre el precio de pedido por adelantado y el precio de lanzamiento. Esto puede ser un gran incentivo para los compradores anticipados.
Haz clic en Guardar.
Abre la página Editar producto único para tu producto único (upcoming_movie_1).
Haz clic en Activar para la opción de compra (buy-movie).
Haz clic en Activar para la oferta de pedido por adelantado (preorder-offer-1) en la opción de compra. Esto activa la oferta de pedido por adelantado y la publica en la fecha que configuraste anteriormente en los detalles del pedido por adelantado.

Video de creación de ofertas de pedido por adelantado

En el siguiente video, se muestran los pasos de creación de ofertas de pedido por adelantado que se describieron anteriormente.

4. Integración con PBL

Para integrar tu app con la Biblioteca de Facturación Play (PBL), sigue estos pasos:

Agrega la dependencia de la Biblioteca de Facturación Play a la app de ejemplo.

dependencies {
val billing_version = "8.1.0"

implementation("com.android.billingclient:billing-ktx:$billing_version")
}

Inicializa el BillingClient. El BillingClient es el SDK del cliente que reside en tu app y se comunica con la Biblioteca de Facturación Play. En el siguiente fragmento de código, se muestra cómo inicializar el cliente de facturación.

private BillingClient createBillingClient() {
return BillingClient.newBuilder(activity)
    .enablePendingPurchases(PendingPurchasesParams.newBuilder().enableOneTimeProducts().build())
    // For one-time products, add a listener to process and acknowledge the purchases. This will notify
    // Google the purchase was processed.
    // For client-only apps, use billingClient.acknowledgePurchase().
    // If you have a secure backend, you must acknowledge purchases on your server using the
    // server-side API.
    // See https://developer.android.com/google/play/billing/security#acknowledge
    // In this sample snippet purchases aren't processed. You must
    // implement your business logic to process and acknowledge the purchases.
    .setListener((billingResult, purchases) -> {})
    .enableAutoServiceReconnection()
    .build();
 }

Conéctate a Google Play.En el siguiente fragmento de código, se muestra cómo conectarse a Google Play.

/**
* Starts the billing connection with Google Play. This method should be called exactly once
* before any other methods in this class.
*
* @param productList The list of products to query for after the connection is established.
*/
public void startBillingConnection(List<Product> productList) {
    billingClient.startConnection(
        new BillingClientStateListener() {
        @Override
        public void onBillingSetupFinished(BillingResult billingResult) {
            if (billingResult.getResponseCode() == BillingResponseCode.OK) {
            Log.d(TAG, "Billing Client Connection Successful");
            queryProductDetails(productList);
            } else {
            Log.e(TAG, "Billing Client Connection Failed: " + billingResult.getDebugMessage());
            listener.onBillingSetupFailed(billingResult); // Propagate the error to the listener to show a message to the user.
            }
        }

        @Override
        public void onBillingServiceDisconnected() {
            Log.e(TAG, "Billing Client Connection Lost");
            listener.onBillingError("Billing Connection Lost");
        }
        });
}

Recupera los detalles del producto único.Después de integrar tu app con PBL, debes recuperar los detalles del producto único en tu app. En el siguiente fragmento de código, se muestra cómo recuperar los detalles del producto único en tu app.

private void queryProductDetails(List<Product> productList) {
    QueryProductDetailsParams queryProductDetailsParams =
        QueryProductDetailsParams.newBuilder().setProductList(productList).build();

    billingClient.queryProductDetailsAsync(
        queryProductDetailsParams,
        new ProductDetailsResponseListener() {
        @Override
        public void onProductDetailsResponse(
            BillingResult billingResult, QueryProductDetailsResult productDetailsResponse) {
            if (billingResult.getResponseCode() == BillingResponseCode.OK) {
            List<ProductDetails> productDetailsList =
                productDetailsResponse.getProductDetailsList();
                listener.onProductDetailsResponse(productDetailsList);
            } else {
            Log.e(TAG, "QueryProductDetailsAsync Failed: " + billingResult.getDebugMessage());
            listener.onBillingError("Query Products Failed: " + billingResult.getResponseCode());
            }
        }
        });
}

Cuando recuperas el producto único (upcoming_movie_1 en este ejemplo) en ProductDetails, obtienes una respuesta similar a la siguiente:

{
    "productId": "upcoming_movie_1",
    "type": "inapp",
    "title": "Purrfect Mayhem: The Final Playback (Movies All Day | Play Samples)",
    "name": "Purrfect Mayhem: The Final Playback",
    "description": "Yolo and Thorne must reach the original broadcasting site to initiate the \"Final Playback\" and save the timeline. Follow them through their race against the Clockinators.",
    "skuDetailsToken": "<---skuDetailsToken--->",
    "oneTimePurchaseOfferDetails": {},
    "oneTimePurchaseOfferDetailsList": [
        {
            "priceAmountMicros": 8500000,
            "priceCurrencyCode": "USD",
            "formattedPrice": "$8.50",
            "offerIdToken": "<---offerIdToken--->",
            "offerId": "preorder",
            "purchaseOptionId": "buy-option",
            "offerTags": [],
            "validTimeWindow": {
                "startTimeMillis": 1756771200000,
                "endTimeMillis": 1785542400000
            },
            "preorderDetails": {
                "preorderReleaseTimeMillis": 1785542400000,
                "preorderPresaleEndTimeMillis": 1785542400000
            }
        }
    ]
}

Ten en cuenta que los detalles de la oferta de pedido por adelantado están disponibles en oneTimePurchaseOfferDetailsList. Esta lista tiene 1 opción de compra (buy-option) para la que se configuró la oferta de pedido por adelantado en Play Console. Puedes identificar cada opción de compra de forma única por su offerIdToken.

Recupera el token de oferta junto con los detalles de la oferta de pedido por adelantado. Necesitas el token de oferta para iniciar el flujo de facturación en el paso 6.

@Override
public void onProductDetailsResponse(List<ProductDetails> productDetailsList) {

if (productDetailsList != null && !productDetailsList.isEmpty()) {

// Process productDetailsList returned by QueryProductDetailsResult
for (ProductDetails productDetails : productDetailsResult.getProductDetailsList()) {
  for (OneTimePurchaseOfferDetails oneTimePurchaseOfferDetails :
      productDetails.getOneTimePurchaseOfferDetailsList()) {
    // Checks if the offer is a preorder offer.
    if (oneTimePurchaseOfferDetails.getPreorderDetails() != null) {
      // Process the returned PreorderDetails
      OneTimePurchaseOfferDetails.PreorderDetails preorderDetails =
          oneTimePurchaseOfferDetails.getPreorderDetails();
      // Get preorder release time in millis.
      long preorderReleaseTimeMillis = preorderDetails.getPreorderReleaseTimeMillis();
      // Get preorder presale end time in millis.
      long preorderPresaleEndTimeMillis = preorderDetails.getPreorderPresaleEndTimeMillis();
      // Get offer ID
        String offerId = oneTimePurchaseOfferDetails.getOfferId();
      // Get the associated purchase option ID
      if (oneTimePurchaseOfferDetails.getPurchaseOptionId() != null) {
        String purchaseOptionId = oneTimePurchaseOfferDetails.getPurchaseOptionId();
      }
    }
  }
  }
  } else {
        Log.e(TAG, "No product details found for " + productId);
    }
}

Inicia el flujo de facturación.

/**
 * Launches the billing flow for the product with the given offer token.
*
* @param activity The activity instance from which the billing flow will be launched.
* @param productDetails The product details of the product to purchase.
* @param offerToken The offer token of the product to purchase.
* @return The result of the billing flow.
*/
public void launchPurchase(Activity activity, ProductDetails productDetails, String offerToken) {
    ImmutableList<BillingFlowParams.ProductDetailsParams> productDetailsParamsList =
        ImmutableList.of(
            BillingFlowParams.ProductDetailsParams.newBuilder()
                .setProductDetails(productDetails)
                .setOfferToken(offerToken)
                .build());
    BillingFlowParams billingFlowParams = BillingFlowParams.newBuilder()
        .setProductDetailsParamsList(productDetailsParamsList)
        .build();
    billingClient.launchBillingFlow(activity, billingFlowParams);
}

5. Prueba las opciones de compra

Antes de que tus productos únicos estén disponibles en tu app publicada, puedes probar la integración de PBL con verificadores de licencias y el Play Billing Lab.

Para comprender cómo puedes probar tus opciones de compra con el Play Billing Lab, consulta el codelab Desbloquea nuevos mercados con precios de productos regionales.

6. Próximos pasos

Aprende a analizar las bajas de compra de productos.
Aprende a desbloquear nuevos mercados con precios regionales.
Aprende a maximizar la integración de la Facturación Play.
Recuerda seguir las prácticas recomendadas para verificar y procesar las compras en tu backend seguro una vez que los usuarios comiencen a comprar estos productos.

Documentos de referencia

7. ¡Felicitaciones!

¡Felicitaciones! Navegaste correctamente por Google Play Console para crear una oferta de pedido por adelantado para un producto único. Ahora tienes una comprensión más profunda del catálogo de productos flexible de Google Play para compras únicas.

Encuesta

Valoramos mucho tus comentarios sobre este codelab. Considera tomarte unos minutos para completar nuestra encuesta.