Únete a ⁠ #Android11: The Beta Launch Show el 3 de junio.

Referencia de AIDL de promociones integradas en la aplicación

Advertencia: El AIDL ya no es compatible y se quitará en una versión futura. Para implementar las funciones de Facturación Google Play, usa la Biblioteca de Facturación Google Play.

Esta documentación proporciona información técnica de referencia para crear promociones mediante la API de AIDL de Facturación Google Play.

Los códigos promocionales te permiten proporcionar contenido o funciones de manera gratuita a un número limitado de usuarios. Después de crear un código promocional, puedes distribuirlo conforme a las Condiciones del Servicio. El usuario ingresa el código promocional en tu app o la app de Google Play Store y recibe el artículo sin costo. Puedes usar códigos promocionales de forma creativa para atraer a los usuarios de distintas maneras, como las siguientes:

  • Un juego puede tener un artículo especial, como un personaje o un artículo decorativo, que solo esté disponible para usuarios que asistan a un evento. El desarrollador puede distribuir tarjetas con códigos promocionales en el evento y los usuarios podrán ingresarlos para desbloquear el artículo.
  • Un desarrollador de apps puede distribuir códigos promocionales en negocios locales a fin de incentivar a usuarios potenciales a probar la app.
  • Un desarrollador de apps puede entregar códigos para familiares y amigos a sus empleados con el objetivo de que los compartan con sus conocidos.

Cada código promocional se asocia con un ID de producto específico (también conocido como SKU). Puedes crear códigos promocionales para tus productos actuales integrados en la aplicación. También puedes mantener un SKU fuera de Play Store para que solo se pueda obtener ese artículo al ingresar el código promocional de SKU. Cuando un usuario ingrese el código promocional en Play Store o en una app, obtendrá el artículo como si pagara el precio total. Si la app ya usa la versión 3 (o una posterior) de la API de Facturación integrada para admitir compras directas desde la aplicación, será fácil agregar códigos promocionales compatibles.

Crea y canjea códigos promocionales

Para crear códigos promocionales, usa Google Play Console. Cada código promocional se asocia a un único producto registrado en Play Console.

Un usuario puede canjear un código promocional de estas dos maneras:

  • Puede ingresar el código promocional como parte del flujo de compra habitual de la app, según lo detallado en Cómo implementar la Facturación integrada. En lo que respecta a la app, es igual que una compra común, con la excepción de que el usuario hace el pago con un código promocional en lugar de dinero.
  • El usuario puede canjear el código en la aplicación Google Play Store. Puede escribir el código en la aplicación Google Play Store de forma manual o puedes generar una URL en tu app para proporcionarle el código en Google Play Store automáticamente. Para proporcionar un código automáticamente, genera y ejecuta una URL con la siguiente estructura y reemplaza <code> por el código promocional:
    https://play.google.com/redeem?code=<code>
    Por ejemplo:
    https://play.google.com/redeem?code=bvlkfdxkjghlkgdhlkj
    Para aprender a generar vínculos hacia Google Play desde una app de Android, consulta la sección Cómo vincular con Google Play. Una vez que se ingresa el código, Play Store le solicitará al usuario que abra la app (si tiene la última versión instalada), la descargue o la actualice.

Cómo brindar compatibilidad con códigos promocionales en tu app

Para admitir códigos promocionales, tu app debe llamar al método getPurchases() cada vez que se inicia o se reanuda. Este método muestra un paquete con todas las compras actuales no consumidas, incluidas las que el usuario realizó con un código promocional. El enfoque más simple consiste en llamar a getPurchases() en el método onResume() de tu actividad, ya que esa devolución de llamada se activa cuando se crea y cuando se reanuda la actividad. Llamar a getPurchases() cuando se inicia y reanuda la app garantiza que se descubran todas las compras y los canjes que pueda haber hecho el usuario mientras no se ejecutaba la app. Además, si un usuario realiza una compra mientras la app está en ejecución y esta no la capta por algún motivo, advertirá la compra de todas formas la próxima vez que se reanude la actividad y llame a getPurchases().

Debe permitirse el canje de códigos promocionales dentro de la app. Si esta admite el flujo de trabajo de compras directas desde la aplicación (que se describe en Cómo realizar solicitudes de Facturación integrada), también admitirá automáticamente el canje de códigos promocionales desde la aplicación. Cuando inicias la IU de compra directa desde la aplicación, el usuario tiene la opción de pagar la compra con el método onActivityResult(), que recibe un intent de respuesta que le informa a la aplicación si se completó la compra. Sin embargo, tu app debe llamar de todas formas a getPurchases() al iniciarse o reanudarse, en caso de que el flujo de trabajo de la compra y del consumo no se hayan completado. Por ejemplo, si el usuario canjea un código promocional con éxito y tu app falla antes de que se consuma el artículo, tu app igual recibe información sobre la compra cuando la app llame a getPurchases() en el siguiente inicio.

Tu app también debe admitir un caso en el cual un usuario canjee un código promocional en la app de Play Store mientras la aplicación esté en ejecución. Tu app puede registrar un objeto de escucha del intent PURCHASES_UPDATED para determinar de inmediato cuando el usuario canjea un código. Play Store activa este intent cuando un usuario canjea un código promocional.

Para recibir el intent PURCHASES_UPDATED, crea un objeto BroadcastReceiver de manera dinámica y regístralo a fin de recibir el com.android.vending.billing.PURCHASES_UPDATED. Registra el receptor con un código similar al siguiente en el método onResume() de tu actividad:

Kotlin

val filter = IntentFilter("com.android.vending.billing.PURCHASES_UPDATED")

Java

IntentFilter filter = new IntentFilter("com.android.vending.billing.PURCHASES_UPDATED");

Cuando el usuario hace una compra, el sistema invoca al método onReceive() de tu receptor de emisión. Ese método debe llamar al objeto getPurchases() para ver qué compras hizo el usuario.

Para reducir la sobrecarga del sistema cuando tu app no esté en ejecución, el método onPause() de tu actividad debe cancelar el registro del receptor de emisión:

Kotlin

unRegisterReceiver(myPromoReceiver);

Java

unRegisterReceiver(myPromoReceiver);

Nota: No registres este receptor de emisión en el manifiesto de la app. Esto puede provocar que el sistema inicie la app para controlar el intent si el usuario hace una compra mientras la app no está en ejecución. Este comportamiento es innecesario y podría ser molesto para el usuario. Para captar cualquier compra que el usuario haya hecho mientras la app no estaba en ejecución, llama a getPurchases() cuando el usuario la inicie.

Prueba promociones integradas en la aplicación

Si tu app admite promociones integradas en la aplicación, prueba los siguientes casos prácticos.

El usuario canjea el código promocional en la app

Si el usuario canjea un código promocional dentro del flujo de compra de la app, según lo detallado en Cómo realizar solicitudes de Facturación integrada, el sistema invoca al método onActivityResult() de tu actividad para administrar la compra. Verifica que onActivityResult() procese la compra de manera correcta, sin importar si el usuario paga con dinero o con un código promocional.

El usuario canjea el código promocional en Google Play Store

Si el usuario canjea un código promocional en Play Store, hay varios flujos de trabajo posibles. Verifica cada uno de ellos.

No está instalada la app

Si el usuario canjea un código promocional de una app que no está instalada en el dispositivo, Play Store le pide al usuario que instale la app (si está instalada, pero no actualizada, Play Store le pedirá al usuario que la actualice). Prueba la siguiente secuencia en un dispositivo que no tenga tu app instalada.

  1. El usuario canjea un código promocional para la app en Play Store. Play Store le pide al usuario que instale tu app.
  2. El usuario instala y, luego, inicia la app. Verifica que, al iniciarse, llame a getPurchases() y detecte de manera correcta la compra que hizo el usuario con el código promocional.

La app está instalada, pero no se está ejecutando

Si el usuario canjea un código promocional de una app que está instalada en el dispositivo, Play Store le pedirá que la abra. Prueba la siguiente secuencia en un dispositivo que tenga tu app instalada, pero que no esté en ejecución:

  1. El usuario canjea un código promocional para la app en Play Store. Play Store le pide al usuario que cambie a tu app.
  2. El usuario inicia tu app. Verifica que, al iniciarse, llame a getPurchases() y detecte de manera correcta la compra que hizo el usuario con el código promocional.

La app está instalada y en ejecución

Si el usuario canjea un código promocional para una app que está actualmente en ejecución en el dispositivo, Play Store usa un intent PURCHASES_UPDATED para notificar a la app. Prueba la siguiente secuencia:

  1. El usuario inicia tu app. Verifica que la app se haya registrado de manera correcta para recibir el intent PURCHASES_UPDATED.
  2. El usuario inicia la app de Play Store, ya sea de forma manual o mediante una URL generada que incluye un código promocional, y canjea ese código. Play Store activa un intent PURCHASES_UPDATED. Verifica que se active la devolución de llamada de onReceive() de tu app para controlar el intent.
  3. El método onReceive() debe llamar al objeto getPurchases() como respuesta al intent. Verifica que tu app llame a este método y que detecte correctamente la compra que el usuario realizó con el código promocional.
  4. El usuario regresa a tu app. Verifica que tenga el artículo que compró.