Unity IAP 5: O que mudou em relação ao IAP 4 e como migrar
Daniel Godley - Unity
Senior Content Marketing Manager
A versão 5 do Unity In-App Purchasing (IAP) substitui a arquitetura baseada em interfaces do IAP 4 por uma única classe StoreController orientada a eventos. A migração requer alterações no código: as interfaces IStoreListener e IDetailedStoreListener e o ConfigurationBuilder são removidos, a inicialização é assíncrona e as compras são processadas por meio de eventos de ciclo de vida. O IAP 5 também permite a monetização da web para dispositivos móveis, processadores de pagamento personalizados (como Stripe e Coda) e lojas virtuais independentes.
O que você precisa saber sobre as IAP do Unity 5
- O Unity IAP 5 remove as interfaces IStoreListener e IDetailedStoreListener necessárias no IAP 4.
- Toda a lógica de compra no Unity IAP 5 é executada por meio de uma única classe: UnityIAPServices.StoreController(), que dispara eventos ao longo do ciclo de vida da compra.
- O ConfigurationBuilder do IAP 4 foi removido. As definições de produto são passadas diretamente para FetchProducts() como objetos ProductDefinition com um ID e um tipo de produto.
- A classe IDs legada foi renomeada para StoreSpecificIds no IAP 5.
- A inicialização do Unity IAP 5 é assíncrona e requer que o Unity Gaming Services seja inicializado primeiro através de await UnityServices.InitializeAsync().
- Os recibos da Apple no IAP 5 são validados automaticamente pelo StoreKit 2 antes de chegarem ao desenvolvedor. A validação do Google Play exige a chave de licença do Google do desenvolvedor, que é ocultada com a ferramenta incluída no pacote de IAP .
- O suporte ao StoreKit 1 retorna na IAP 5 para dispositivos que não podem ser atualizados para o iOS 15.0 (dispositivos anteriores ao iPhone 6s).
- Uma implementação de referência funcional é fornecida no pacote: o exemplo Minimal Coded IAP (script PaywallManager), disponível no Unity Package Manager.
O Unity IAP 5 introduz grandes refinamentos arquitetônicos, mudanças estruturais na inicialização e fluxos de trabalho de busca de produtos mais limpos. Além disso, abre caminho para recursos avançados do ecossistema que estão por vir, incluindo provedores de pagamento direto (como Stripe e Coda) e lojas virtuais que permitem segmentar melhor as vendas e reter uma parcela maior da receita das compras. Quer você esteja migrando do Unity IAP 4 para o IAP 5 ou configurando compras dentro do aplicativo para dispositivos móveis no motor de jogo Unity pela primeira vez, este guia passo a passo abrange todo o fluxo de trabalho de implementação.
Arquitetura
Unity IAP 4
Interfaces IStoreListener / IDetailedStoreListener com callbacks fixos
Unity IAP 5
Classe StoreController única com eventos de ciclo de vida
IDs de loja
Unity IAP 4
novos IDs()
Unity IAP 5
novo StoreSpecificIds()
Configuração do produto
Unity IAP 4
Produtos agrupados em um ConfigurationBuilder antes da inicialização
Unity IAP 5
Objetos ProductDefinition passados diretamente para FetchProducts() a qualquer momento.
Iniciar uma compra
Unity IAP 4
Chamado com uma string de ID do produto
Unity IAP 5
PurchaseProduct(product) foi chamado com o objeto de produto completo.
Gestão de compras
Unity IAP 4
Retorno de chamada ProcessPurchase via IStoreController
Unity IAP 5
Evento OnPurchasePending(Order), confirmado com ConfirmPurchase(pendingOrder)
Validação de recibo (Apple)
Unity IAP 4
Validação manual multiplataforma
Unity IAP 5
Pré-validado pelo StoreKit 2
manipuladores de compra da interface do usuário
Unity IAP 4
Com base no ID do produto
Unity IAP 5
Sem alterações — os manipuladores de interface do usuário existentes continuam funcionando.
Unity IAP 4
Unity IAP 5
Arquitetura
Interfaces IStoreListener / IDetailedStoreListener com callbacks fixos
Classe StoreController única com eventos de ciclo de vida
IDs de loja
novos IDs()
novo StoreSpecificIds()
Configuração do produto
Produtos agrupados em um ConfigurationBuilder antes da inicialização
Objetos ProductDefinition passados diretamente para FetchProducts() a qualquer momento.
Iniciar uma compra
Chamado com uma string de ID do produto
PurchaseProduct(product) foi chamado com o objeto de produto completo.
Gestão de compras
Retorno de chamada ProcessPurchase via IStoreController
Evento OnPurchasePending(Order), confirmado com ConfirmPurchase(pendingOrder)
Validação de recibo (Apple)
Validação manual multiplataforma
Pré-validado pelo StoreKit 2
manipuladores de compra da interface do usuário
Com base no ID do produto
Sem alterações — os manipuladores de interface do usuário existentes continuam funcionando.
Como migrar do Unity IAP 4 para o IAP 5
A migração segue quatro etapas:
Inicialize e conecte. Inicialize o Unity Gaming Services, obtenha um StoreController, inscreva-se em seus eventos e chame Connect() para acessar o Google Play ou a Apple App Store. Use OnStoreConnected e OnStoreDisconnected para ativar/desativar a interface de compra.
Buscar produtos. Crie uma lista de `ProductDefinition` a partir do catálogo de produtos IAP do editor ou em código (por exemplo, `new ProductDefinition("gem_chest_01", ProductType.Consumable)`) e passe-a para `FetchProducts()`. A loja retorna preços e descrições localizados.
Recuperar compras pendentes. Chame a função FetchPurchases() para recuperar transações interrompidas ou adiadas. Os pedidos pendentes chegam através do evento OnPurchasePending, mas os desenvolvedores também devem processar orders.PendingOrders, pois os eventos de pedidos pendentes podem ser perdidos em algumas versões do iOS. Neste momento, os itens não consumíveis e as assinaturas já confirmadas podem ser renovadas.
Comprar, conceder, confirmar. Chame PurchaseProduct(produto). Em OnPurchasePending, conceda o item, valide o recibo e chame ConfirmPurchase(pendingOrder). Lidar com falhas em OnPurchaseFailed — um cancelamento do usuário não precisa de mensagem, outros erros devem ser exibidos ao jogador.
Fluxo de compra IAP do Unity 5
Use o infográfico abaixo para visualizar todo o fluxo de compra do Unity IAP5, incluindo os novos recursos, lojas virtuais, catálogos e provedores de pagamento.
Faça o download do PDF em alta resolução aqui.
Armadilhas comuns ao atualizar para o IAP 5
- Concessões duplicadas: o mesmo pedido pode surgir tanto por meio do OnPurchasePending quanto por meio de uma solicitação manual de pedido pendente. Registre as transações processadas em um HashSet (preenchido a partir de OnPurchasesConfirmed) e verifique-o antes de conceder a permissão.
- Compras simultâneas: desative os botões de compra enquanto um pedido estiver em andamento para evitar solicitações duplicadas.
- Vazamentos de eventos: O IAP 5 é orientado a eventos — cancele a inscrição de todos os eventos do StoreController quando o gerenciador de compras for destruído.
- Compras suspensas pelo StoreKit 1: em dispositivos com versões anteriores ao iOS 15, compras não confirmadas podem impedir que um jogador compre o mesmo produto novamente. Recomenda-se um sistema de backend que rastreie e processe essas compras.
Verificação do lado do servidor
Os IDs de transação dos pedidos IAP 5 podem ser enviados para o Unity Cloud Code para verificação no servidor, com os itens concedidos aos jogadores através do Unity Economy.