
Acquisti in-app Flutter su Android: offer token e ripristino
In un gioco Flutter un acquisto raramente si rompe sul pulsante «Acquista» in sé. Si rompe ai margini: quando Play restituisce un prodotto con un elenco di offerte, quando un ripristino parte senza account Google, quando una transazione non viene mai chiusa. Ci sono capitate tutte e tre in AI Inc: Tycoon: dopo un rilascio Crashlytics ha mostrato un crash INVALID_OFFER_TOKEN su un tablet, proprio dentro il negozio del gioco. Qui sotto trovate sette passaggi per configurare in_app_purchase su Android in modo che il gioco non si chiuda, e i quattro test che lo garantiscono.
In breve:
- Un solo identificatore di prodotto: lo stesso nella console e nel gioco.
- Un solo ascoltatore del flusso degli acquisti per tutto il processo, non uno per acquisto.
- Un prodotto con elenco di offerte si compra con un offer token; elenco vuoto significa non comprare.
- Racchiudete
buyNonConsumableintry … on PlatformExceptionerestorePurchasesintry … on Exception. - Concedete il diritto prima di chiudere la transazione e chiamate sempre
completePurchase. - Portate la logica che sceglie i parametri d'acquisto in una funzione a parte e testatela senza telefono.
Passaggio 1. Usate un solo identificatore di prodotto
L'identificatore nella Play Console deve coincidere con la chiave con cui il gioco salva ciò che è stato acquistato. Non create un secondo nome: qualsiasi tabella «store → gioco» diventa una seconda fonte di verità e si discosta dalla prima già al prossimo prodotto nuovo. Allora il giocatore paga per qualcosa che non riceve. Nel nostro progetto è il campo id del catalogo del negozio, e un test apposito verifica che gli identificatori coincidano.
Scegliete anche il tipo di prodotto con consapevolezza. Tutto ciò che vende il nostro gioco è un aspetto che resta per sempre, quindi sono acquisti non consumabili (buyNonConsumable). Un prodotto consumabile significherebbe una valuta, e nel gioco non ce n'è.
Passaggio 2. Iscrivetevi al flusso degli acquisti una volta sola
Il purchaseStream del plugin è uno per processo e consegna tutto: ciò che è appena stato acquistato, ciò che è stato ripristinato e ciò che è stato pagato dopo, tra un avvio e l'altro. Iscrivetevi all'avvio e gestite gli eventi in base allo stato.
_sub ??= _store.purchaseStream.listen(_onPurchases);
Due iscrizioni gestirebbero un acquisto due volte, e l'operatore ??= non ne lascia nascere una seconda. Nel gioco l'iscrizione ha anche onDone e onError; qui sono abbreviati.
Passaggio 3. Costruite il parametro d'acquisto e non dimenticate il token
È qui che ci hanno colti. Il pacchetto in_app_purchase_android nella versione 0.5.x controlla l'offer token in launchBillingFlow: non appena un prodotto ha un elenco subscriptionOfferDetails, il plugin pretende un token, anche se il prodotto è singolo e nella console non avete creato alcuna offerta. Abbiamo acquistato il prodotto «Senza pubblicità» senza token e abbiamo ottenuto INVALID_OFFER_TOKEN.
Ora il parametro lo costruisce una funzione a parte:
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,
);
}
Si legge così: lo store non ha trovato nulla, quindi non compriamo; non c'è un elenco di offerte, acquisto normale; c'è un elenco ma è vuoto, quindi non compriamo (il plugin rifiuterebbe qualsiasi token); c'è un elenco, prendiamo il token da lì. A causa di ProductType e GooglePlayPurchaseParam, abbiamo dovuto aggiungere il pacchetto in_app_purchase_android al pubspec come dipendenza diretta.
Passaggio 4. Racchiudete l'acquisto stesso in un try
Anche con il token giusto, lo store può rifiutare. Una PlatformException non gestita chiude il gioco proprio sul pulsante, e il giocatore vede soltanto che l'app è crollata.
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;
}
Un rifiuto diventa un semplice «non è andata»: il gioco lo dice al giocatore e non si rompe nulla. Altre due piccole cose: limitate l'attesa della risposta con un timeout (noi aspettiamo tre minuti) e ricordate che un pagamento in ritardo arriva comunque dal flusso.
Passaggio 5. Concedete il diritto prima di chiudere la transazione
Per ogni evento del flusso procedete in quest'ordine: controllate lo stato, concedete il diritto, chiudete la transazione.
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);
}
L'ordine conta. Se il gioco venisse interrotto tra la chiusura della transazione e la concessione del diritto, il giocatore resterebbe con qualcosa di pagato ma bloccato. E pendingCompletePurchase va sempre chiuso, altrimenti lo store considera l'acquisto incompleto e lo restituisce a ogni avvio. Inoltre, secondo le regole di Play Billing, Google rimborsa al giocatore gli acquisti non confermati dopo alcuni giorni. Chiudete quindi ogni transazione che il plugin chiede di chiudere.
Passaggio 6. Il ripristino deve saper tacere
Un ripristino silenzioso a ogni avvio del gioco è una buona idea, ma restorePurchases lancia un'eccezione quando Play non ha risposto: nessun account Google, nessuna rete o Play non ancora pronto. Non gestita, diventa un «fatal» in Crashlytics. Abbiamo racchiuso la chiamata e aggiunto un flag a parte, perché il pulsante «Ripristina acquisti» possa dire onestamente «Google Play non risponde».
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 di due secondi non è un difetto, ma la conseguenza del fatto che la risposta arriva da un flusso, mentre lo store non dice mai «non arriverà altro». Restituiamo ciò che ha fatto in tempo ad arrivare. Se manca qualcosa, il ripristino si può ripetere.
Passaggio 7. Scrivete quattro test
La funzione che sceglie i parametri è pura, quindi un normale flutter test la verifica senza telefono e senza Play. Ci sono bastati quattro casi:
- Un normale prodotto singolo si compra come prima, senza token.
- Un prodotto con elenco di offerte si compra con un token preso dall'elenco di quel prodotto.
- Un elenco di offerte vuoto: non comprare.
- Lo store non ha trovato nulla: non comprare.
Questi test sono nati dopo il crash reale. Ora un errore simile lo vedremo nei test e non in Crashlytics.
Checklist
- ✓ L'identificatore del prodotto è lo stesso nella console e nel gioco.
- ✓ Un solo iscritto ascolta
purchaseStream. - ✓ Una funzione a parte costruisce il parametro d'acquisto, con test sul token.
- ✓
buyNonConsumableerestorePurchasessono racchiusi intry. - ✓ Il diritto viene concesso prima di
completePurchase, ecompletePurchaseviene sempre chiamato. - ✓ Il gioco ha un messaggio per il caso «Play non risponde».
Domande frequenti
Serve un offer token per un prodotto singolo?
Solo se lo store ha restituito il prodotto con un elenco di offerte. Se subscriptionOfferDetails è null, acquistate senza token, come nel nostro primo test.
Perché «Ripristina acquisti» aspetta due secondi?
Lo store consegna la risposta da un flusso e non dice quale parte sia l'ultima. Una breve pausa permette di raccogliere tutto ciò che è arrivato. Il giocatore non se ne accorge.
Perché la transazione va sempre chiusa?
Finché non è chiusa, lo store considera l'acquisto incompleto e lo restituisce a ogni avvio. Chiudete quindi ogni transazione che il plugin chiede di chiudere.
Devo aggiungere in_app_purchase_android a parte?
Se usate i suoi tipi, come GooglePlayPurchaseParam o ProductType, sì: aggiungetelo a pubspec.yaml come dipendenza diretta, invece di contare sul fatto che lo porti in_app_purchase.
Vi servono acquisti, pubblicità con ricompensa e ripristino in un gioco mobile senza sorprese al rilascio? Li configuriamo chiavi in mano, con i test. Maggiori dettagli nella pagina dei servizi. Per editori e studi c'è la collaborazione con le aziende. E per sapere perché abbiamo scelto Flutter, leggete Flutter o Unity.
