← NeuigkeitenGuide · Flutter

Flutter In-App-Käufe auf Android: Offer-Token und Restore

Artikel#Flutter#in_app_purchase#Google Play Billing#In-App-Käufe#Android#Dart#Spieleentwicklung

In einem Flutter-Spiel bricht ein Kauf selten am „Kaufen“-Button selbst. Er bricht an den Rändern: wenn Play ein Produkt mit einer Liste von Angeboten liefert, wenn eine Wiederherstellung ohne Google-Konto läuft, wenn eine Transaktion nie geschlossen wird. Alle drei haben wir in AI Inc: Tycoon erlebt: Nach einem Release zeigte Crashlytics einen Absturz mit INVALID_OFFER_TOKEN auf einem Tablet, mitten im Shop des Spiels. Unten stehen sieben Schritte, wie Sie in_app_purchase für Android so einrichten, dass das Spiel nicht schließt, und die vier Tests, die das absichern.

Kurz gesagt:

  • Eine Produkt-ID: dieselbe in der Konsole und im Spiel.
  • Ein Listener am Kauf-Stream für den ganzen Prozess, nicht einer pro Kauf.
  • Ein Produkt mit Angebotsliste kaufen Sie mit einem Offer-Token; eine leere Liste heißt: nicht kaufen.
  • buyNonConsumable in try … on PlatformException einpacken, restorePurchases in try … on Exception.
  • Das Recht vergeben, bevor die Transaktion geschlossen wird, und completePurchase immer aufrufen.
  • Die Logik zur Wahl der Kaufparameter in eine eigene Funktion auslagern und ohne Smartphone testen.

Schritt 1. Nutzen Sie eine Produkt-ID

Die ID in der Play Console muss mit dem Schlüssel übereinstimmen, unter dem das Spiel das Gekaufte speichert. Legen Sie keinen zweiten Namen an: Jede Tabelle „Store → Spiel“ wird zur zweiten Quelle der Wahrheit und läuft beim nächsten neuen Produkt von der ersten auseinander. Dann bezahlt ein Spieler etwas, das er nie bekommt. In unserem Projekt ist das das Feld id des Shop-Katalogs, und ein eigener Test prüft, ob die IDs übereinstimmen.

Entscheiden Sie auch den Produkttyp bewusst. Alles, was unser Spiel verkauft, ist ein Aussehen, das für immer bleibt, also sind es nicht verbrauchbare Käufe (buyNonConsumable). Ein verbrauchbares Produkt wäre eine Währung, und die gibt es im Spiel nicht.

Schritt 2. Abonnieren Sie den Kauf-Stream einmal

Der purchaseStream des Plugins ist einmal pro Prozess vorhanden und liefert alles: frisch Gekauftes, Wiederhergestelltes und das, was zwischen Starts nachträglich bezahlt wurde. Abonnieren Sie ihn beim Start und behandeln Sie die Ereignisse nach Status.

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

Zwei Abonnements würden einen Kauf zweimal verarbeiten, und der Operator ??= lässt kein zweites entstehen. Im Spiel hat das Abonnement außerdem onDone und onError; hier sind sie gekürzt.

Schritt 3. Bauen Sie den Kaufparameter und vergessen Sie das Token nicht

Hier hat es uns erwischt. Das Paket in_app_purchase_android in Version 0.5.x prüft das Angebots-Token in launchBillingFlow: Sobald ein Produkt eine Liste subscriptionOfferDetails hat, verlangt das Plugin ein Token, auch wenn das Produkt einmalig ist und Sie in der Konsole nie Angebote angelegt haben. Wir kauften das Produkt „Ohne Werbung“ ohne Token und bekamen INVALID_OFFER_TOKEN.

Jetzt baut eine eigene Funktion den Parameter:

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

Sie liest sich so: Der Store hat nichts gefunden, also kaufen wir nicht; keine Angebotsliste, also ein normaler Kauf; es gibt eine Liste, aber sie ist leer, also kaufen wir nicht (das Plugin lehnt jedes Token ab); es gibt eine Liste, also nehmen wir das Token daraus. Wegen ProductType und GooglePlayPurchaseParam mussten wir das Paket in_app_purchase_android in der pubspec als direkte Abhängigkeit aufnehmen.

Schritt 4. Packen Sie den Kauf selbst in try

Auch mit dem richtigen Token kann der Store ablehnen. Eine unbehandelte PlatformException schließt das Spiel direkt am Button, und der Spieler sieht nur, dass die App abgestürzt ist.

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

Eine Ablehnung wird zu einem gewöhnlichen „hat nicht geklappt“: Das Spiel sagt es dem Spieler und geht nichts kaputt. Noch zwei Kleinigkeiten: Begrenzen Sie das Warten auf die Antwort mit einem Timeout (wir warten drei Minuten) und denken Sie daran, dass eine späte Zahlung trotzdem über den Stream kommt.

Schritt 5. Vergeben Sie das Recht vor dem Schließen der Transaktion

Gehen Sie für jedes Ereignis aus dem Stream in dieser Reihenfolge vor: Status prüfen, Recht vergeben, Transaktion schließen.

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

Die Reihenfolge ist wichtig. Würde das Spiel zwischen dem Schließen der Transaktion und der Rechtevergabe unterbrochen, bliebe der Spieler mit etwas Bezahltem, aber Gesperrtem zurück. Und pendingCompletePurchase müssen Sie immer schließen, sonst hält der Store den Kauf für unfertig und gibt ihn bei jedem Start zurück. Außerdem erstattet Google nach den Regeln von Play Billing nicht bestätigte Käufe nach einigen Tagen dem Spieler. Schließen Sie also jede Transaktion, die das Plugin zu schließen verlangt.

Schritt 6. Die Wiederherstellung muss schweigen können

Eine stille Wiederherstellung bei jedem Spielstart ist eine gute Idee, aber restorePurchases wirft eine Ausnahme, wenn Play nicht antwortet: kein Google-Konto, kein Netz oder Play ist noch nicht bereit. Unbehandelt wird sie in Crashlytics zu einem „fatal“. Wir haben den Aufruf eingepackt und ein eigenes Flag ergänzt, damit der Button „Käufe wiederherstellen“ ehrlich sagen kann: „Google Play antwortet nicht“.

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

Die Pause von zwei Sekunden ist kein Fehler, sondern die Folge davon, dass die Antwort über einen Stream kommt und der Store nie sagt „es kommt nichts mehr“. Wir geben zurück, was rechtzeitig eingetroffen ist. Fehlt etwas, lässt sich die Wiederherstellung wiederholen.

Schritt 7. Schreiben Sie vier Tests

Die Funktion zur Wahl der Parameter ist rein, deshalb prüft sie ein gewöhnliches flutter test ohne Smartphone und ohne Play. Uns reichten vier Fälle:

  1. Ein gewöhnliches einmaliges Produkt wird wie zuvor ohne Token gekauft.
  2. Ein Produkt mit Angebotsliste wird mit einem Token aus der Liste dieses Produkts gekauft.
  3. Eine leere Angebotsliste heißt: nicht kaufen.
  4. Der Store hat nichts gefunden, also nicht kaufen.

Diese Tests sind nach dem echten Absturz entstanden. Einen ähnlichen Fehler sehen wir jetzt in den Tests und nicht in Crashlytics.

Checkliste

  • ✓ Die Produkt-ID ist in der Konsole und im Spiel dieselbe.
  • ✓ Ein Abonnent hört auf purchaseStream.
  • ✓ Eine eigene Funktion baut den Kaufparameter, es gibt Tests zum Token.
  • ✓ buyNonConsumable und restorePurchases sind in try eingepackt.
  • ✓ Das Recht wird vor completePurchase vergeben, und completePurchase wird immer aufgerufen.
  • ✓ Das Spiel hat eine Meldung für den Fall „Play antwortet nicht“.

Häufige Fragen

Brauche ich für ein einmaliges Produkt ein Offer-Token?

Nur wenn der Store das Produkt mit einer Angebotsliste geliefert hat. Ist subscriptionOfferDetails gleich null, kaufen Sie ohne Token, wie in unserem ersten Test.

Warum wartet „Käufe wiederherstellen“ zwei Sekunden?

Der Store liefert die Antwort über einen Stream und sagt nicht, welcher Teil der letzte ist. Eine kurze Pause erlaubt es, alles einzusammeln, was eingetroffen ist. Für den Spieler ist sie unmerklich.

Warum muss ich die Transaktion immer schließen?

Solange sie nicht geschlossen ist, hält der Store den Kauf für unfertig und gibt ihn bei jedem Start zurück. Schließen Sie also jede Transaktion, die das Plugin zu schließen verlangt.

Muss ich in_app_purchase_android separat einbinden?

Wenn Sie seine Typen nutzen, etwa GooglePlayPurchaseParam oder ProductType, ja: Nehmen Sie es als direkte Abhängigkeit in die pubspec.yaml auf, statt sich darauf zu verlassen, dass in_app_purchase es mitbringt.


Brauchen Sie Käufe, Belohnungswerbung und Wiederherstellung in einem Mobile-Spiel ohne Überraschungen beim Release? Wir richten sie schlüsselfertig samt Tests ein. Mehr dazu auf der Seite Leistungen. Für Publisher und Studios gibt es die Zusammenarbeit mit Unternehmen. Und warum wir Flutter gewählt haben, lesen Sie in Flutter oder Unity.