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 la Facturación Google Play, usa la biblioteca de la Facturación Google Play.

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

Los códigos promocionales te permiten entregar 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 a sus empleados códigos para familiares y amigos a fin de que los compartan con sus conocidos.

Cada código promocional se asocia con un ID del producto específico (también conocido como SKU). Puedes crear códigos promocionales para tus productos integrados en la aplicación actuales. También puedes mantener un SKU fuera de Play Store para que la única forma de obtener ese artículo sea ingresando 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 su precio total. Si tu app 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 compatibilidad con códigos promocionales.

Cómo crear y canjear 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, como se describe en Cómo implementar la facturación integrada. En lo que respecta a la app, esta es igual a 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 tú 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 saber cómo generar vínculos a Google Play desde una app de Android, consulta Vinculación 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ó mediante el canje de 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 la actividad y cuando esta se reanuda. Llamar a getPurchases() cuando se inicia la actividad y cuando se reanuda 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().

Tu app debe permitir que los usuarios puedan canjear códigos promocionales dentro de ella. 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 recibirá información sobre la compra cuando 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 determinar de inmediato el momento en que el usuario canjea un código registrando un receptor para el intent PURCHASES_UPDATED. 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 objeto 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.

A fin de 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 no es necesario y podría disgustar al 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 para 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 correctamente la compra que hizo el usuario con el código promocional.

Está instalada la app, pero no se está ejecutando

Si el usuario canjea un código promocional para 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 correctamente la compra que hizo el usuario con el código promocional.

Está instalada la app y se está ejecutando

Si el usuario canjea un código promocional para una app que está en ejecución en el dispositivo, Play Store notifica a la app mediante un intent PURCHASES_UPDATED. 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 del método onReceive() de tu app para controlar el intent.
  3. El método onReceive() debe llamar al getPurchases() como respuesta al intent. Verifica que tu app llame a este método y que detecte correctamente la compra que hizo el usuario con el código promocional.
  4. El usuario activa de nuevo tu app. Verifica que haya comprado el artículo.