
Compras integradas en Flutter: offer token y restaurar
En un juego de Flutter, una compra rara vez falla en el propio botón «Comprar». Falla en los bordes: cuando Play devuelve un producto con una lista de ofertas, cuando una restauración se ejecuta sin cuenta de Google, cuando una transacción nunca se cierra. Nos pasaron las tres cosas en AI Inc: Tycoon: tras un lanzamiento, Crashlytics mostró un cierre inesperado por INVALID_OFFER_TOKEN en una tableta, justo dentro de la tienda del juego. A continuación van siete pasos para configurar in_app_purchase en Android de modo que el juego no se cierre, y los cuatro tests que lo garantizan.
En resumen:
- Un solo identificador de producto: el mismo en la consola y en el juego.
- Un único oyente del flujo de compras para todo el proceso, no uno por compra.
- Un producto con lista de ofertas se compra con un offer token; una lista vacía significa no comprar.
- Envuelva
buyNonConsumableentry … on PlatformExceptionyrestorePurchasesentry … on Exception. - Conceda el derecho antes de cerrar la transacción y llame siempre a
completePurchase. - Saque la lógica que elige los parámetros de compra a una función aparte y pruébela sin teléfono.
Paso 1. Use un solo identificador de producto
El identificador en Play Console debe coincidir con la clave bajo la que el juego guarda lo comprado. No cree un segundo nombre: cualquier tabla «tienda → juego» se convierte en una segunda fuente de verdad y se separa de la primera con el siguiente producto nuevo. Entonces el jugador paga por algo que no recibe. En nuestro proyecto es el campo id del catálogo de la tienda, y un test aparte comprueba que los identificadores coinciden.
Decida también el tipo de producto con criterio. Todo lo que vende nuestro juego es un aspecto que se queda para siempre, así que son compras no consumibles (buyNonConsumable). Un producto consumible significaría una moneda, y el juego no tiene ninguna.
Paso 2. Suscríbase al flujo de compras una sola vez
El purchaseStream del plugin es uno por proceso y lo entrega todo: lo recién comprado, lo restaurado y lo que se pagó más tarde entre dos inicios. Suscríbase al arrancar y procese los eventos según su estado.
_sub ??= _store.purchaseStream.listen(_onPurchases);
Dos suscripciones procesarían una compra dos veces, y el operador ??= impide que aparezca una segunda. En el juego la suscripción tiene además onDone y onError; aquí se han abreviado.
Paso 3. Construya el parámetro de compra y no olvide el token
Aquí nos pillaron. El paquete in_app_purchase_android en la versión 0.5.x comprueba el offer token en launchBillingFlow: en cuanto un producto tiene una lista subscriptionOfferDetails, el plugin exige un token, aunque el producto sea de pago único y en la consola no haya creado ninguna oferta. Compramos el producto «Sin anuncios» sin token y obtuvimos INVALID_OFFER_TOKEN.
Ahora una función aparte construye el parámetro:
PurchaseParam? purchaseParamFor(List<ProductDetails> found) {
if (found.isEmpty) return null;
final play = found.whereType<GooglePlayProductDetails>().toList();
if (play.isEmpty) return PurchaseParam(productDetails: found.first);
final d = play.firstWhere(
(p) => p.productDetails.productType == ProductType.inapp,
orElse: () => play.first,
);
final offers = d.productDetails.subscriptionOfferDetails;
if (offers == null) return PurchaseParam(productDetails: d);
if (offers.isEmpty) return null;
return GooglePlayPurchaseParam(
productDetails: d,
offerToken: d.offerToken ?? offers.first.offerIdToken,
);
}
Se lee así: la tienda no encontró nada, no compramos; no hay lista de ofertas, compra normal; hay lista pero está vacía, no compramos (el plugin rechazaría cualquier token); hay lista, tomamos el token de ella. Por ProductType y GooglePlayPurchaseParam tuvimos que añadir el paquete in_app_purchase_android al pubspec como dependencia directa.
Paso 4. Envuelva la propia compra en try
Incluso con el token correcto, la tienda puede negarse. Una PlatformException sin tratar cierra el juego justo en el botón, y el jugador solo ve que la aplicación se ha cerrado.
bool started;
try {
started = await _store.buyNonConsumable(purchaseParam: param);
} on PlatformException catch (e) {
debugPrint('purchase $id: ${e.code}');
started = false;
}
if (!started) {
_waiting.remove(id);
return false;
}
Una negativa pasa a ser un simple «no ha salido»: el juego se lo dice al jugador y no se rompe nada. Dos detalles más: limite la espera de la respuesta con un tiempo máximo (nosotros esperamos tres minutos) y recuerde que un pago tardío llega igualmente por el flujo.
Paso 5. Conceda el derecho antes de cerrar la transacción
Para cada evento del flujo, siga este orden: compruebe el estado, conceda el derecho y cierre la transacción.
for (final p in list) {
final ok = p.status == PurchaseStatus.purchased ||
p.status == PurchaseStatus.restored;
if (ok) {
purchaseGranted?.call(
p.productID,
restored: p.status == PurchaseStatus.restored,
);
}
if (p.pendingCompletePurchase) await _store.completePurchase(p);
if (p.status == PurchaseStatus.pending) continue;
_waiting.remove(p.productID)?.complete(ok);
}
El orden importa. Si el juego se interrumpiera entre el cierre de la transacción y la concesión del derecho, el jugador se quedaría con algo pagado pero bloqueado. Y hay que cerrar siempre pendingCompletePurchase, o la tienda considera la compra inacabada y la devuelve en cada inicio. Además, según las reglas de Play Billing, Google reembolsa al jugador las compras no confirmadas al cabo de unos días. Cierre, pues, toda transacción que el plugin pida cerrar.
Paso 6. La restauración debe saber callar
Una restauración silenciosa en cada inicio del juego es buena idea, pero restorePurchases lanza una excepción cuando Play no ha respondido: no hay cuenta de Google, no hay red o Play aún no está listo. Sin tratar, se convierte en un «fatal» en Crashlytics. Envolvimos la llamada y añadimos un indicador aparte para que el botón «Restaurar compras» pueda decir con honestidad «Google Play no responde».
try {
await _store.restorePurchases();
} on Exception catch (e) {
debugPrint('restore: $e');
_restoreFailed = true;
return {..._restored};
}
await Future<void>.delayed(const Duration(seconds: 2));
return {..._restored};
La pausa de dos segundos no es un defecto, sino consecuencia de que la respuesta llega por un flujo y la tienda nunca dice «ya no vendrá nada más». Devolvemos lo que ha llegado a tiempo. Si falta algo, la restauración se puede repetir.
Paso 7. Escriba cuatro tests
La función que elige los parámetros es pura, así que un simple flutter test la comprueba sin teléfono ni Play. Nos bastaron cuatro casos:
- Un producto de pago único normal se compra como antes, sin token.
- Un producto con lista de ofertas se compra con un token de la lista de ese producto.
- Una lista de ofertas vacía: no comprar.
- La tienda no encontró nada: no comprar.
Estos tests surgieron tras el cierre inesperado real. Ahora un error parecido lo veremos en los tests y no en Crashlytics.
Lista de comprobación
- ✓ El identificador del producto es el mismo en la consola y en el juego.
- ✓ Un solo suscriptor escucha
purchaseStream. - ✓ Una función aparte construye el parámetro de compra, con tests sobre el token.
- ✓
buyNonConsumableyrestorePurchasesestán envueltos entry. - ✓ El derecho se concede antes de
completePurchase, ycompletePurchasese llama siempre. - ✓ El juego tiene un mensaje para el caso «Play no responde».
Preguntas frecuentes
¿Hace falta un offer token para un producto de pago único?
Solo si la tienda devolvió el producto con una lista de ofertas. Si subscriptionOfferDetails es null, compre sin token, como en nuestro primer test.
¿Por qué «Restaurar compras» espera dos segundos?
La tienda entrega la respuesta por un flujo y no dice cuál es la última parte. Una pausa corta permite recoger todo lo que ha llegado. El jugador no la nota.
¿Por qué hay que cerrar siempre la transacción?
Mientras no esté cerrada, la tienda considera la compra inacabada y la devuelve en cada inicio. Cierre, pues, toda transacción que el plugin pida cerrar.
¿Hay que añadir in_app_purchase_android por separado?
Si usa sus tipos, como GooglePlayPurchaseParam o ProductType, sí: añádalo a pubspec.yaml como dependencia directa en lugar de confiar en que in_app_purchase lo traiga.
¿Necesita compras, anuncios con recompensa y restauración en un juego móvil sin sorpresas en el lanzamiento? Los configuramos llave en mano, con tests. Más información en la página de servicios. Para editores y estudios existe la colaboración con empresas. Y para saber por qué elegimos Flutter, lea Flutter o Unity.
