Upgrade to IAP version 5#

Use this guide to upgrade from Unity In-App Purchasing version 4 (or earlier) to version 5.

IAP version 5 (v5) is a major rework of the IAP package, and migration requires significant code changes.

Overview of changes#

• Configuration and initialization flow
  • Initialization has been separated into multiple calls to cover store connection, fetching products, and fetching purchases.
  • The configuration builder has been removed.
  • Products can be fetched using a list or a CatalogProvider, which can be defined at any time.
  • Store Extensions and configurations have been replaced with Store Extended Services.
• Changes to event handling and callbacks
  • IDetailedStoreListener has been replaced with optional event handlers.

Replace UnityPurchasing.Initialize()#

As of IAP v5, you can initialize the Unity IAP package with greater flexibility. Connect to the store, fetch products, and handle purchases independently and asynchronously. This approach helps you identify and resolve issues that might block a successful initialization.

Follow these steps to replace UnityPurchase.Initialize()'s behaviour:

1. Call and await StoreController.Connect()
   • When this call completes, you may assume that IAP has connected to your current app store.
2. Call FetchProducts()
   • You can add products to an instance of CatalogProvider, similar to adding products to the ConfigurationBuilder. You can also pass a list of ProductDefinitions to ProductService.FetchProducts() or StoreController.FetchProducts() For more information, refer to Code sample of new initialization process
   • Your OnProductsFetched event handler is called when the request has successfully completed. If no specified products could be fetched, OnProductsFetchFailed will be invoked.
3. Call FetchPurchases() after your products have been successfully fetched.
   • Your OnPurchasesFetched event handler is called when the request has successfully completed. The Orders object contains a filterable collection of all deferred, pending, and completed orders returned by the app store. On failure, OnPurchasesFetchFailed will be invoked.

Code sample of new initialization process using StoreController#

The following is an example of the new initialization process:

StoreController m_StoreController;  
  
async void InitializeIAP()  
{  
    m_StoreController = UnityIAPServices.StoreController();  
  
    m_StoreController.OnPurchasePending += OnPurchasePending;  
  
    await m_StoreController.Connect();  
  
    m_StoreController.OnProductsFetched += OnProductsFetched;
    m_StoreController.OnPurchasesFetched += OnPurchasesFetched;  
  
    var initialProductsToFetch = new List<ProductDefinition>  
    {  
        new(goldProductId, ProductType.Consumable),  
        new(diamondProductId, ProductType.Consumable)  
    };  
  
    m_StoreController.FetchProducts(initialProductsToFetch);  
}
void OnProductsFetched(List<Product> products)  
{  
    // Handle fetched products  
    m_StoreController.FetchPurchases()  
}  
void OnPurchasesFetched(Orders orders) {  
   // Process purchases, e.g. check for entitlements from completed orders  
}

Replace IDetailedStoreListener and IStoreListener#

IAP v5 no longer requires an implementation of IDetailedStoreListener or IStoreListener for handling purchases or initialization. Functionality previously handled by an implementation of IDetailedStoreListener should be replaced by attaching event handlers to StoreController, or the individual ProductService, PurchaseService and StoreService services.

For an example of adding event handlers to StoreController, refer to Code sample of new initialization process.

During migration, replace the IDetailedStoreListener functions' behaviours with the following:

Replace ConfigurationBuilder#

Replace the following ConfigurationBuilder functions with the following behaviours:

Replace IStoreController#

Replace IStoreController with StoreController. StoreController exposes IAP functionality similar to IStoreListener, but can be fetched by calling UnityIAPServices.StoreController() at any time.

Methods from IStoreController can be replaced with the following from StoreController:

Replace purchase flow#

To initiate a purchase, call Purchase() or PurchaseProduct()on StoreController or PurchaseService. To confirm a pending purchase, call StoreController.ConfirmPurchase(PendingOrder) or PurchaseService.ConfirmPurchase(PendingOrder) with the PendingOrder you want to confirm. For more information about the purchase flow, refer to Purchases.

Restore transactions#

RestoreTransactions has moved from Store Extensions to StoreController and PurchaseService.

Replace entitlement checks#

To check a user's entitlement to a product, IAP relies on events. You can check the entitlements for all your fetched products by calling FetchPurchases and handling the OnFetchPurchases event. To check the entitlement for a single product, call CheckEntitlement and handle the OnCheckEntitlement event.

Fetch additional products#

Call FetchProducts on either StoreController or ProductService with a list of additional products to trigger your OnPurchasesFetched event handler. Alternatively, you can call FetchProducts on a CatalogProvider instance. For an example of fetching products via ProductService, refer to Code sample of new initialization process. For an example of calling FetchProducts on CatalogProvider, refer to Define your products.

Receipt validation#

Receipt validation for Apple App Store receipts has been deprecated. Receipt validation is supported only for Google Play Store. To fetch receipts, use Order.Info.Receipt from Order instead of Product.Receipt.

Codeless IAP specifics#

Replace the following CodelessIAPStoreListener function with the following: