← НовиниГайд · Flutter

Покупки у Flutter на Android: токен пропозиції й відновлення

Статті#Flutter#in_app_purchase#Google Play Billing#покупки в грі#Android#Dart#геймдев

Покупка у Flutter-грі ламається не на кнопці «Купити», а на краях: коли Play повертає товар зі списком пропозицій, коли відновлення йде без акаунта Google, коли транзакцію забули закрити. Ми пройшли всі три в AI Inc: Tycoon: після релізу Crashlytics показав падіння INVALID_OFFER_TOKEN на планшеті, просто в магазині гри. Нижче сім кроків, як підключити in_app_purchase для Android так, щоб гра не закривалася, і чотири тести, які це тримають.

Коротко:

  • Один ідентифікатор товару: той самий у консолі й у грі.
  • Слухач потоку покупок — один на весь процес, а не на кожну покупку.
  • Товар зі списком пропозицій купуйте з токеном пропозиції; порожній список — не купуйте.
  • buyNonConsumable обгортайте в try … on PlatformException, restorePurchases — у try … on Exception.
  • Право видавайте до закриття транзакції, а completePurchase викликайте завжди.
  • Логіку вибору параметрів покупки виносьте в окрему функцію й тестуйте без телефона.

Крок 1. Заведіть один ідентифікатор товару

Ідентифікатор у Play Console має збігатися з ключем, під яким гра зберігає куплене. Другого імені не заводьте: будь-яка таблиця «стор → гра» стає другим джерелом правди й розходиться з першим на першому ж новому товарі. Тоді гравець платить за те, чого не отримав. У нашому проєкті це поле id каталогу магазину, а збіг ідентифікаторів перевіряє окремий тест.

Тип товару теж вирішуйте свідомо. Усе, що продає наша гра, — вигляд, який лишається назавжди, тож це неспоживні покупки (buyNonConsumable). Спожитий товар означав би валюту, а її в грі немає.

Крок 2. Підпишіться на потік покупок один раз

Потік purchaseStream у плагіна один на процес і віддає все: щойно куплене, відновлене й те, що доплатилося між запусками. Підпишіться на нього при старті й розбирайте події за статусом.

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

Дві підписки дадуть дві обробки однієї покупки, а оператор ??= не дає створити другу. У грі в підписки є ще onDone та onError, тут їх скорочено.

Крок 3. Побудуйте параметр покупки й не забудьте токен

Це місце, де нас упіймали. Пакет in_app_purchase_android версії 0.5.x перевіряє токен пропозиції в launchBillingFlow: щойно в товару є список subscriptionOfferDetails, плагін вимагає токен, навіть якщо товар одноразовий і в консолі ви не створювали жодних пропозицій. Ми купували товар «Без реклами» без токена й отримали INVALID_OFFER_TOKEN.

Тепер параметр будує окрема функція:

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

Читається так: стор нічого не знайшов — не купуємо; список пропозицій відсутній — звичайна покупка; список є, але порожній — не купуємо (плагін відкине будь-який токен); список є — беремо токен із нього. Через ProductType і GooglePlayPurchaseParam пакет in_app_purchase_android довелося підключити в pubspec прямою залежністю.

Крок 4. Обгорніть саму покупку в try

Навіть із правильним токеном стор може відмовити. Необроблений PlatformException закриває гру просто на кнопці, а гравець бачить лише, що застосунок упав.

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

Відмова стає звичайним «не вдалося»: гра каже це гравцеві й нічого не ламає. Ще дві дрібниці: очікування відповіді обмежте таймаутом (ми чекаємо три хвилини) і пам'ятайте, що пізня оплата однаково прийде через потік.

Крок 5. Видавайте право до закриття транзакції

Для кожної події з потоку робіть у такому порядку: перевірте статус, видайте право, закрийте транзакцію.

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

Порядок важливий. Якби гру перервали між закриттям транзакції та видачею права, гравець лишився б із оплаченим, але заблокованим товаром. А закривати pendingCompletePurchase треба завжди: інакше стор вважає покупку незавершеною й повертає її на кожному запуску. До того ж за правилами Play Billing непідтверджені покупки Google повертає гравцеві за кілька днів.

Крок 6. Відновлення покупок має вміти мовчати

Тихе відновлення на кожному старті гри — добра ідея, але restorePurchases кидає виняток, коли Play не відповів: немає акаунта Google, мережі або Play ще не готовий. Необроблений, він стає «фатальним» у Crashlytics. Ми обгорнули виклик і додали окремий прапорець, щоб кнопка «Відновити покупки» могла чесно сказати «Google Play не відповідає».

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

Пауза в дві секунди — не вада, а наслідок того, що відповідь приходить потоком, а «більше нічого не буде» стор не каже ніколи. Ми віддаємо те, що встигло прийти. Якщо чогось не вистачило, відновлення можна повторити.

Крок 7. Напишіть чотири тести

Функція вибору параметрів чиста, тож її перевіряє звичайний flutter test без телефона й без Play. Нам вистачило чотирьох випадків:

  1. Звичайний одноразовий товар купується як раніше, без токена.
  2. Товар зі списком пропозицій купується з токеном зі списку цього товару.
  3. Порожній список пропозицій — не купувати.
  4. Стор нічого не знайшов — не купувати.

Ці тести з'явилися після реального падіння. Тепер схожу помилку ми побачимо в тестах, а не в Crashlytics.

Чекліст

  • ✓ Ідентифікатор товару в консолі й у грі один.
  • ✓ Потік purchaseStream слухає один підписник.
  • ✓ Параметр покупки будує окрема функція, є тести на токен.
  • ✓ buyNonConsumable і restorePurchases обгорнуті в try.
  • ✓ Право видається до completePurchase, а completePurchase викликається завжди.
  • ✓ Гра має рядок для випадку «Play не відповідає».

Часті запитання

Чи потрібен токен пропозиції для одноразового товару?

Лише якщо стор віддав товар зі списком пропозицій. Якщо subscriptionOfferDetails дорівнює null, купуйте без токена, як у першому нашому тесті.

Чому «Відновити покупки» чекає дві секунди?

Відповідь стор віддає потоком і не повідомляє, що вона остання. Коротка пауза дозволяє зібрати все, що надійшло. Для гравця це непомітно.

Чому транзакцію треба закривати завжди?

Поки вона не закрита, стор вважає покупку незавершеною й повертає її на кожному запуску. Тому закривайте кожну транзакцію, яку плагін просить закрити.

Чи треба підключати in_app_purchase_android окремо?

Якщо ви використовуєте його типи, як-от GooglePlayPurchaseParam чи ProductType, так: додайте його в pubspec.yaml прямою залежністю, а не покладайтесь на те, що його тягне in_app_purchase.


Потрібні покупки, реклама за нагороду й відновлення в мобільній грі без сюрпризів у релізі? Ми підключаємо їх під ключ разом із тестами. Детальніше — на сторінці послуг. Для видавців і студій є співпраця з компаніями. Про те, чому ми обрали Flutter, читайте в статті «Flutter чи Unity».