
Compras no app com Flutter: offer token e restauração
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
buyNonConsumableemtry … on PlatformExceptione orestorePurchasesemtry … 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:
- Um produto avulso comum é comprado como antes, sem token.
- Um produto com lista de ofertas é comprado com um token da lista desse produto.
- Lista de ofertas vazia: não comprar.
- 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.
- ✓
buyNonConsumableerestorePurchasesestão envolvidos emtry. - ✓ O direito é concedido antes do
completePurchase, e ocompletePurchaseé 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.
