IAP de Unity 5: ¿Qué ha cambiado desde IAP 4 y cómo migrar?
Daniel Godley - Unity
Senior Content Marketing Manager
La versión 5 de Unity In-App Purchasing (IAP) reemplaza la arquitectura basada en interfaz de IAP 4 con una única clase StoreController controlada por eventos. La migración requiere cambios en el código: se eliminan las interfaces IStoreListener e IDetailedStoreListener y el ConfigurationBuilder, la inicialización es asíncrona y las compras se procesan a través de eventos del ciclo de vida. IAP 5 también permite la monetización web-móvil, procesadores de pago personalizados (como Stripe y Coda) y tiendas web independientes.
Lo que necesitas saber sobre Unity IAP 5
- Unity IAP 5 elimina las interfaces IStoreListener e IDetailedStoreListener necesarias en IAP 4.
- Toda la lógica de compra en Unity IAP 5 se ejecuta a través de una sola clase: UnityIAPServices.StoreController(), que activa eventos a lo largo del ciclo de vida de la compra.
- Se elimina el ConfigurationBuilder de IAP 4. Las definiciones de productos se pasan directamente a FetchProducts() como objetos ProductDefinition con un ID y un tipo de producto.
- La clase de identificadores heredados pasa a llamarse StoreSpecificIds en IAP 5.
- La inicialización de Unity IAP 5 es asíncrona y requiere que Unity Gaming Services se inicialice primero mediante await UnityServices.InitializeAsync().
- Los recibos de Apple en IAP 5 se validan automáticamente a través de StoreKit 2 antes de llegar al desarrollador. La validación de Google Play requiere la clave de licencia de Google del desarrollador, la cual se oculta mediante la herramienta incluida en el paquete de IAP .
- La compatibilidad con StoreKit 1 regresa en la IAP 5 para dispositivos que no se pueden actualizar a iOS 15.0 (dispositivos anteriores al iPhone 6s).
- El paquete incluye una implementación de referencia funcional: el ejemplo mínimo de IAP codificado (script PaywallManager), disponible en el Administrador de paquetes de Unity .
Unity IAP 5 introduce importantes mejoras arquitectónicas, cambios estructurales en la inicialización y flujos de trabajo de obtención de productos más limpios. Además, allana el camino para funciones avanzadas del ecosistema que se vislumbran en el horizonte, incluidos proveedores de pago directo (como Stripe y Coda) y tiendas en línea que permiten segmentar mejor las ventas y conservar una mayor parte de los ingresos por compras. Tanto si estás migrando de Unity IAP 4 a IAP 5 como si estás configurando por primera vez las compras integradas en la aplicación móvil en el motor de juegos Unity , este desglose paso a paso cubre el flujo de trabajo de implementación completo.
Arquitectura
IAP de Unity 4
Interfaces IStoreListener / IDetailedStoreListener con funciones de devolución de llamada fijas
IAP de Unity 5
Clase StoreController única con eventos de ciclo de vida
Identificadores de tienda
IAP de Unity 4
nuevos ID()
IAP de Unity 5
new StoreSpecificIds()
Configuración del producto
IAP de Unity 4
Productos empaquetados en un ConfigurationBuilder antes de la inicialización.
IAP de Unity 5
Los objetos ProductDefinition se pasan directamente a FetchProducts() en cualquier momento.
Iniciar una compra
IAP de Unity 4
Llamado con una cadena de identificación de producto
IAP de Unity 5
Se llama a PurchaseProduct(producto) con el objeto de producto completo.
Gestión de compras
IAP de Unity 4
Devolución de llamada de ProcessPurchase a través de IStoreController
IAP de Unity 5
Evento OnPurchasePending(Order), confirmado con ConfirmPurchase(pendingOrder)
Validación de recibos (Apple)
IAP de Unity 4
Validación manual multiplataforma
IAP de Unity 5
Prevalidado por StoreKit 2
gestores de compras de la interfaz de usuario
IAP de Unity 4
Basado en la identificación del producto
IAP de Unity 5
Sin cambios: los controladores de interfaz de usuario existentes siguen funcionando.
IAP de Unity 4
IAP de Unity 5
Arquitectura
Interfaces IStoreListener / IDetailedStoreListener con funciones de devolución de llamada fijas
Clase StoreController única con eventos de ciclo de vida
Identificadores de tienda
nuevos ID()
new StoreSpecificIds()
Configuración del producto
Productos empaquetados en un ConfigurationBuilder antes de la inicialización.
Los objetos ProductDefinition se pasan directamente a FetchProducts() en cualquier momento.
Iniciar una compra
Llamado con una cadena de identificación de producto
Se llama a PurchaseProduct(producto) con el objeto de producto completo.
Gestión de compras
Devolución de llamada de ProcessPurchase a través de IStoreController
Evento OnPurchasePending(Order), confirmado con ConfirmPurchase(pendingOrder)
Validación de recibos (Apple)
Validación manual multiplataforma
Prevalidado por StoreKit 2
gestores de compras de la interfaz de usuario
Basado en la identificación del producto
Sin cambios: los controladores de interfaz de usuario existentes siguen funcionando.
Cómo migrar de Unity IAP 4 a IAP 5
La migración consta de cuatro pasos:
Inicializar y conectar. Inicializa Unity Gaming Services, obtén un StoreController, suscríbete a sus eventos y llama a Connect() para acceder a Google Play o a la Apple App Store. Utilice OnStoreConnected y OnStoreDisconnected para alternar la interfaz de usuario de compra.
Obtener productos. Crea una List a partir del catálogo de productos IAP del editor o en el código (por ejemplo, new ProductDefinition("gem_chest_01", ProductType.Consumable)) y pásala a FetchProducts(). La tienda muestra precios y descripciones adaptados al mercado local.
Obtener compras pendientes. Llama a FetchPurchases() para recuperar transacciones interrumpidas o pospuestas. Los pedidos pendientes llegan a través del evento OnPurchasePending, pero los desarrolladores también deben procesar orders.PendingOrders, ya que en algunas versiones de iOS se pueden perder eventos pendientes. En este punto, los artículos no consumibles y las suscripciones confirmadas pueden reactivarse.
Comprar, otorgar, confirmar. Llamar a PurchaseProduct(producto). En OnPurchasePending, concede el artículo, valida el recibo y llama a ConfirmPurchase(pendingOrder). Gestionar los fallos en OnPurchaseFailed: una cancelación por parte del usuario no necesita mensaje, otros errores deben mostrarse al jugador.
El flujo de compra de Unity IAP 5
Utilice la infografía a continuación para ver todo el proceso de compra de Unity IAP5, incluidas las nuevas funciones, las tiendas en línea, los catálogos y los proveedores de pago.
Descarga aquí el PDF de alta resolución.
Errores comunes al actualizar a IAP 5
- Subvenciones duplicadas: el mismo pedido puede aparecer tanto a través de OnPurchasePending como mediante una verificación manual de pedidos pendientes. Realiza un seguimiento de las transacciones procesadas en un HashSet (que se genera a partir de OnPurchasesConfirmed) y verifícalo antes de otorgar la autorización.
- Compras simultáneas: desactive los botones de compra mientras un pedido esté en curso para evitar solicitudes duplicadas.
- Filtraciones de eventos: IAP 5 se basa en eventos: cancela la suscripción a todos los eventos de StoreController cuando se destruye el gestor de compras.
- StoreKit 1 suspendía las compras: en dispositivos anteriores a iOS 15, las compras no confirmadas podían impedir que un jugador volviera a comprar el mismo producto. Se recomienda utilizar un sistema de gestión interna que rastree y resuelva estas compras.
Verificación del lado del servidor
Los ID de transacción de los pedidos de IAP 5 se pueden enviar a Unity Cloud Code para su verificación en el servidor, y los artículos se otorgan a los jugadores a través de Unity Economy.