← ActualitésGuide · Flutter

Achats intégrés Flutter sur Android : offer token

Articles#Flutter#in_app_purchase#Google Play Billing#achats intégrés#Android#Dart#développement de jeux

Dans un jeu Flutter, un achat casse rarement sur le bouton « Acheter » lui-même. Il casse sur les bords : quand Play renvoie un produit avec une liste d'offres, quand une restauration se lance sans compte Google, quand une transaction n'est jamais fermée. Nous avons rencontré les trois dans AI Inc: Tycoon : après une sortie, Crashlytics a montré un plantage INVALID_OFFER_TOKEN sur une tablette, en plein dans la boutique du jeu. Voici sept étapes pour brancher in_app_purchase sur Android sans que le jeu se ferme, et les quatre tests qui le garantissent.

En bref :

  • Un seul identifiant de produit : le même dans la console et dans le jeu.
  • Un seul écouteur du flux d'achats pour tout le processus, pas un par achat.
  • Un produit avec une liste d'offres s'achète avec un offer token ; une liste vide, on n'achète pas.
  • Enveloppez buyNonConsumable dans try … on PlatformException et restorePurchases dans try … on Exception.
  • Accordez le droit avant de fermer la transaction, et appelez toujours completePurchase.
  • Isolez la logique de choix des paramètres d'achat dans une fonction à part et testez-la sans téléphone.

Étape 1. Utilisez un seul identifiant de produit

L'identifiant dans la Play Console doit correspondre à la clé sous laquelle le jeu enregistre ce qui a été acheté. Ne créez pas de second nom : toute table « boutique → jeu » devient une deuxième source de vérité et s'écarte de la première dès le prochain nouveau produit. Le joueur paie alors pour quelque chose qu'il ne reçoit pas. Dans notre projet, c'est le champ id du catalogue de la boutique, et un test dédié vérifie que les identifiants concordent.

Choisissez aussi le type de produit en connaissance de cause. Tout ce que vend notre jeu est une apparence qui reste pour toujours : ce sont donc des achats non consommables (buyNonConsumable). Un produit consommable signifierait une monnaie, et le jeu n'en a pas.

Étape 2. Abonnez-vous une seule fois au flux d'achats

Le purchaseStream du plugin est unique par processus et livre tout : ce qui vient d'être acheté, ce qui a été restauré et ce qui a été payé plus tard entre deux lancements. Abonnez-vous-y au démarrage et traitez les événements selon leur statut.

_sub ??= _store.purchaseStream.listen(_onPurchases);

Deux abonnements traiteraient un achat deux fois, et l'opérateur ??= empêche d'en créer un second. Dans le jeu, l'abonnement a aussi onDone et onError ; ils sont abrégés ici.

Étape 3. Construisez le paramètre d'achat sans oublier le token

C'est ici que nous nous sommes fait prendre. Le paquet in_app_purchase_android en version 0.5.x vérifie l'offer token dans launchBillingFlow : dès qu'un produit a une liste subscriptionOfferDetails, le plugin exige un token, même si le produit est ponctuel et que vous n'avez créé aucune offre dans la console. Nous avons acheté le produit « Sans pub » sans token et obtenu INVALID_OFFER_TOKEN.

Désormais, une fonction à part construit le paramètre :

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,
  );
}

Elle se lit ainsi : la boutique n'a rien trouvé, on n'achète pas ; pas de liste d'offres, achat ordinaire ; il y a une liste mais elle est vide, on n'achète pas (le plugin rejetterait n'importe quel token) ; il y a une liste, on prend le token qui s'y trouve. À cause de ProductType et de GooglePlayPurchaseParam, nous avons dû ajouter le paquet in_app_purchase_android au pubspec comme dépendance directe.

Étape 4. Enveloppez l'achat lui-même dans un try

Même avec le bon token, la boutique peut refuser. Une PlatformException non gérée ferme le jeu en plein sur le bouton, et le joueur voit seulement que l'application a planté.

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 refus devient un simple « ça n'a pas marché » : le jeu le dit au joueur et rien ne casse. Deux petites choses encore : limitez l'attente de la réponse par un délai (nous attendons trois minutes) et souvenez-vous qu'un paiement tardif arrive quand même par le flux.

Étape 5. Accordez le droit avant de fermer la transaction

Pour chaque événement du flux, procédez dans cet ordre : vérifiez le statut, accordez le droit, fermez la transaction.

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'ordre compte. Si le jeu était interrompu entre la fermeture de la transaction et l'octroi du droit, le joueur resterait avec un achat payé mais verrouillé. Et il faut toujours fermer pendingCompletePurchase, sinon la boutique considère l'achat comme inachevé et le renvoie à chaque lancement. De plus, selon les règles de Play Billing, Google rembourse au joueur les achats non confirmés au bout de quelques jours. Fermez donc chaque transaction que le plugin demande de fermer.

Étape 6. La restauration doit savoir se taire

Une restauration silencieuse à chaque démarrage du jeu est une bonne idée, mais restorePurchases lève une exception quand Play n'a pas répondu : pas de compte Google, pas de réseau ou Play pas encore prêt. Non gérée, elle devient un « fatal » dans Crashlytics. Nous avons enveloppé l'appel et ajouté un indicateur à part, pour que le bouton « Restaurer les achats » puisse dire honnêtement « Google Play ne répond pas ».

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 pause de deux secondes n'est pas un défaut, mais la conséquence du fait que la réponse arrive par un flux, alors que la boutique ne dit jamais « il n'y aura plus rien ». Nous renvoyons ce qui a eu le temps d'arriver. S'il manque quelque chose, la restauration peut être relancée.

Étape 7. Écrivez quatre tests

La fonction de choix des paramètres est pure : un simple flutter test la vérifie, sans téléphone ni Play. Quatre cas nous ont suffi :

  1. Un produit ponctuel ordinaire s'achète comme avant, sans token.
  2. Un produit avec une liste d'offres s'achète avec un token pris dans la liste de ce produit.
  3. Une liste d'offres vide : on n'achète pas.
  4. La boutique n'a rien trouvé : on n'achète pas.

Ces tests sont apparus après le vrai plantage. Une erreur semblable se verra désormais dans les tests, et non dans Crashlytics.

Checklist

  • ✓ L'identifiant du produit est le même dans la console et dans le jeu.
  • ✓ Un seul abonné écoute purchaseStream.
  • ✓ Une fonction à part construit le paramètre d'achat, avec des tests sur le token.
  • ✓ buyNonConsumable et restorePurchases sont enveloppés dans try.
  • ✓ Le droit est accordé avant completePurchase, et completePurchase est toujours appelé.
  • ✓ Le jeu a un message pour le cas « Play ne répond pas ».

Questions fréquentes

Faut-il un offer token pour un produit ponctuel ?

Seulement si la boutique a renvoyé le produit avec une liste d'offres. Si subscriptionOfferDetails vaut null, achetez sans token, comme dans notre premier test.

Pourquoi « Restaurer les achats » attend-il deux secondes ?

La boutique livre la réponse par un flux et ne dit pas quelle partie est la dernière. Une courte pause permet de recueillir tout ce qui est arrivé. Le joueur ne la remarque pas.

Pourquoi faut-il toujours fermer la transaction ?

Tant qu'elle n'est pas fermée, la boutique considère l'achat comme inachevé et le renvoie à chaque lancement. Fermez donc chaque transaction que le plugin demande de fermer.

Faut-il ajouter in_app_purchase_android séparément ?

Si vous utilisez ses types, comme GooglePlayPurchaseParam ou ProductType, oui : ajoutez-le au pubspec.yaml comme dépendance directe, au lieu de compter sur in_app_purchase pour le tirer.


Besoin d'achats, de publicités avec récompense et de restauration dans un jeu mobile sans surprises à la sortie ? Nous les mettons en place clé en main, avec les tests. Plus de détails sur la page services. Pour les éditeurs et les studios, il y a la collaboration avec les entreprises. Et pour savoir pourquoi nous avons choisi Flutter, lisez Flutter ou Unity.