← NovidadesGuia · Flutter

Compras no app com Flutter: offer token e restauração

Artigos#Flutter#in_app_purchase#Google Play Billing#compras no app#Android#Dart#desenvolvimento de jogos

Num jogo em Flutter, a compra raramente quebra no botão «Comprar» em si. Ela quebra nas bordas: quando o Play devolve um produto com uma lista de ofertas, quando uma restauração roda sem conta Google, quando uma transação nunca é fechada. Passamos pelas três em AI Inc: Tycoon: depois de um lançamento, o Crashlytics mostrou uma falha INVALID_OFFER_TOKEN num tablet, bem dentro da loja do jogo. Abaixo estão sete passos para configurar o in_app_purchase no Android sem que o jogo feche, e os quatro testes que garantem isso.

Resumindo:

  • Um só identificador de produto: o mesmo no console e no jogo.
  • Um único ouvinte do fluxo de compras para o processo todo, não um por compra.
  • Um produto com lista de ofertas se compra com um offer token; lista vazia significa não comprar.
  • Envolva o buyNonConsumable em try … on PlatformException e o restorePurchases em try … on Exception.
  • Conceda o direito antes de fechar a transação e chame sempre o completePurchase.
  • Isole a lógica que escolhe os parâmetros da compra numa função própria e teste-a sem celular.

Passo 1. Use um só identificador de produto

O identificador no Play Console deve coincidir com a chave sob a qual o jogo guarda o que foi comprado. Não crie um segundo nome: qualquer tabela «loja → jogo» vira uma segunda fonte da verdade e se afasta da primeira já no próximo produto novo. Aí o jogador paga por algo que não recebe. No nosso projeto, é o campo id do catálogo da loja, e um teste à parte confere se os identificadores coincidem.

Decida também o tipo de produto com critério. Tudo o que o nosso jogo vende é um visual que fica para sempre, então são compras não consumíveis (buyNonConsumable). Um produto consumível significaria uma moeda, e o jogo não tem nenhuma.

Passo 2. Assine o fluxo de compras uma única vez

O purchaseStream do plugin é um por processo e entrega tudo: o que acabou de ser comprado, o que foi restaurado e o que foi pago depois, entre duas execuções. Assine-o na inicialização e trate os eventos pelo status.

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

Duas assinaturas tratariam uma compra duas vezes, e o operador ??= não deixa surgir uma segunda. No jogo, a assinatura tem ainda onDone e onError; aqui foram abreviados.

Passo 3. Monte o parâmetro da compra e não esqueça o token

Foi aqui que nos pegaram. O pacote in_app_purchase_android na versão 0.5.x confere o offer token em launchBillingFlow: assim que um produto tem uma lista subscriptionOfferDetails, o plugin exige um token, mesmo que o produto seja avulso e você nunca tenha criado ofertas no console. Compramos o produto «Sem anúncios» sem token e recebemos INVALID_OFFER_TOKEN.

Agora uma função própria monta o 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,
  );
}

Ela se lê assim: a loja não achou nada, então não compramos; não há lista de ofertas, compra normal; há lista, mas está vazia, então não compramos (o plugin rejeitaria qualquer token); há lista, pegamos o token dela. Por causa de ProductType e GooglePlayPurchaseParam, tivemos de adicionar o pacote in_app_purchase_android ao pubspec como dependência direta.

Passo 4. Envolva a própria compra em try

Mesmo com o token certo, a loja pode recusar. Uma PlatformException não tratada fecha o jogo bem no botão, e o jogador só vê que o app caiu.

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

Uma recusa vira um simples «não deu certo»: o jogo avisa o jogador e nada quebra. Mais duas coisinhas: limite a espera pela resposta com um tempo máximo (nós esperamos três minutos) e lembre que um pagamento tardio chega do mesmo jeito pelo fluxo.

Passo 5. Conceda o direito antes de fechar a transação

Para cada evento do fluxo, siga esta ordem: confira o status, conceda o direito, feche a transação.

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

A ordem importa. Se o jogo fosse interrompido entre o fechamento da transação e a concessão do direito, o jogador ficaria com algo pago, mas bloqueado. E é preciso sempre fechar o pendingCompletePurchase, senão a loja considera a compra inacabada e a devolve a cada execução. Além disso, pelas regras do Play Billing, o Google reembolsa ao jogador as compras não confirmadas depois de alguns dias. Portanto, feche toda transação que o plugin pedir para fechar.

Passo 6. A restauração precisa saber ficar quieta

Uma restauração silenciosa a cada início do jogo é uma boa ideia, mas o restorePurchases lança uma exceção quando o Play não respondeu: sem conta Google, sem rede ou com o Play ainda não pronto. Sem tratamento, ela vira um «fatal» no Crashlytics. Envolvemos a chamada e acrescentamos um indicador à parte, para o botão «Restaurar compras» poder dizer com honestidade «O Google Play não está respondendo».

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

A pausa de dois segundos não é defeito, e sim consequência de a resposta chegar por um fluxo, enquanto a loja nunca diz «não vem mais nada». Devolvemos o que deu tempo de chegar. Se faltar algo, a restauração pode ser repetida.

Passo 7. Escreva quatro testes

A função que escolhe os parâmetros é pura, então um flutter test comum a verifica sem celular e sem o Play. Quatro casos bastaram para nós:

  1. Um produto avulso comum é comprado como antes, sem token.
  2. Um produto com lista de ofertas é comprado com um token da lista desse produto.
  3. Lista de ofertas vazia: não comprar.
  4. A loja não achou nada: não comprar.

Esses testes surgiram depois da falha real. Agora um erro parecido vai aparecer nos testes, e não no Crashlytics.

Checklist

  • ✓ O identificador do produto é o mesmo no console e no jogo.
  • ✓ Um só assinante escuta o purchaseStream.
  • ✓ Uma função própria monta o parâmetro da compra, com testes sobre o token.
  • ✓ buyNonConsumable e restorePurchases estão envolvidos em try.
  • ✓ O direito é concedido antes do completePurchase, e o completePurchase é sempre chamado.
  • ✓ O jogo tem uma mensagem para o caso «o Play não está respondendo».

Perguntas frequentes

Preciso de um offer token para um produto avulso?

Só se a loja devolveu o produto com uma lista de ofertas. Se subscriptionOfferDetails for null, compre sem token, como no nosso primeiro teste.

Por que «Restaurar compras» espera dois segundos?

A loja entrega a resposta por um fluxo e não diz qual parte é a última. Uma pausa curta permite juntar tudo o que chegou. O jogador não percebe.

Por que preciso sempre fechar a transação?

Enquanto ela não for fechada, a loja considera a compra inacabada e a devolve a cada execução. Então feche toda transação que o plugin pedir para fechar.

Preciso adicionar o in_app_purchase_android separadamente?

Se você usa os tipos dele, como GooglePlayPurchaseParam ou ProductType, sim: adicione-o ao pubspec.yaml como dependência direta, em vez de confiar que o in_app_purchase o traga.


Precisa de compras, anúncios com recompensa e restauração em um jogo mobile sem surpresas no lançamento? Configuramos tudo, de ponta a ponta, com testes. Saiba mais na página de serviços. Para editoras e estúdios há a parceria com empresas. E, para saber por que escolhemos o Flutter, leia Flutter ou Unity.