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 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 a un ID de producto en particular (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.

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, 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.
  • Puede canjear el código en la app de Google Play Store. El usuario puede ingresar el código en la app de Google Play Store manualmente, o bien puedes generar una URL en tu app que proporcione el código en Google Play Store de manera automática. Para la opción automática, genera y lanza una URL con la siguiente estructura, y sustituye <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.

Admite 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, así como cuando se reanuda la actividad. Llamar a getPurchases() cuando se inicia y reanuda la app garantiza que esta detecte todas las compras y canjes que pueda haber hecho el usuario mientras no se estaba ejecutando. Además, si un usuario realiza una compra mientras la app está en ejecución, y esta no la capta por alguna razón, de todos modos advertirá la compra la próxima vez que la actividad se reanude 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 un método onActivityResult() que recibe un intent de respuesta que le informa a la app si se completó la compra. Sin embargo, tu app debe llamar igualmente a getPurchases() cuando se reinicia o reanuda en caso de que no se completen el flujo de trabajo de la compra y del consumo. Por ejemplo, si el usuario canjea un código promocional de manera correcta 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 para recibir com.android.vending.billing.PURCHASES_UPDATED. Registra el receptor insertando 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 a getPurchases() para ver las compras que 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. Si se declara el receptor en el manifiesto, puedes hacer que el sistema inicie la app para gestionar el intent, en el caso de que el usuario haga 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 en el flujo de compra de la app, como se describe en Cómo realizar una solicitud de facturación integrada, el sistema invocará el método onActivityResult() de tu actividad para gestionar la compra. Verifica que onActivityResult() controle la compra de forma correcta, independientemente de que el usuario pague 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.

La app no está instalada

Si el usuario canjea un código promocional para una app que no está instalada en el dispositivo, Play Store le pedirá que la instale. (Si la app 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 tu app. Verifica que, al iniciarse, la app llame a getPurchases() y detecte correctamente 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 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, la app llame a getPurchases() y detecte correctamente 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á 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 la aplicación. Verifica que la app se haya registrado correctamente para recibir el intent PURCHASES_UPDATED.
  2. El usuario inicia la app de Play Store, ya sea manualmente o mediante una URL generada que incluye un código promocional, y canjea el código promocional. Play Store activa un intent PURCHASES_UPDATED. Verifica que la devolución de llamada de onReceive() de tu app se active para controlar el intent.
  3. El método onReceive() debería responder al intent llamando a getPurchases(). 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 activa de nuevo tu app. Verifica que el usuario haya comprado el artículo.