Initialize Unity IAP
Learn how to initialize the Unity IAP package, configure essential settings, and verify setup to start processing in‑app purchases across supported platforms.
Read time 5 minutesLast updated a month ago
Before you use Unity In-App Purchasing (IAP), initialize the IAP package.
Important
If you want to integrate a Direct-to-Consumer (D2C) payment provider, there are some differences so refer to Initialize services to handle the startup sequence instead.
If you want to use Unity Analytics or Unity Authentication in your project, you need to initialize Unity Gaming Services (UGS) first before initializing IAP. Refer to the Initialize Unity Gaming Services section below for a how-to.
Initialize Unity Gaming Services
Call to initialize all Unity Gaming Services. This method returns a that you can use to track initialization progress.
UnityServices.InitializeAsync()TaskTo learn more, refer to the Initialization example. For a fully functional sample, import the 06 Initialize Gaming Services sample (Package Manager > In-App Purchasing > Samples).
For more information, refer to the Services Core API.
Initialize In-App Purchasing
Prerequisites
Choose one of the catalog setup methods in Create an IAP catalog to define the products you want to offer for purchase.
Initialization steps
Initialization consists of the following steps:
- Getting a for your app store.
StoreController - Attaching event listeners to the .
StoreController - Connecting to your app store.
- Fetching products from your app store.
- Fetching purchases from your app store.
using System.Collections.Generic;using UnityEngine.Purchasing;public class MyIAPManager{ private StoreController m_StoreController; public MyIAPManager() { // Define products var catalogProvider = new CatalogProvider(); catalogProvider.AddProduct("100_gold_coins", ProductType.Consumable, new StoreSpecificIds() { {"100_gold_coins_google", GooglePlay.Name}, {"100_gold_coins_mac", MacAppStore.Name} }); // Get StoreController m_StoreController = UnityIAPServices.StoreController(); // Add event listeners m_StoreController.OnStoreDisconnected += OnStoreDisconnected; m_StoreController.OnProductsFetched += OnProductsFetched; m_StoreController.OnProductsFetchFailed += OnProductsFetchFailed; m_StoreController.OnPurchasesFetched += OnPurchasesFetched; m_StoreController.OnPurchasesFetchFailed += OnPurchasesFetchFailed; // Connect to store m_StoreController.Connect().ContinueWith(_ => { // Fetch products from store catalogProvider.FetchProducts( list => m_StoreController.FetchProducts(list) ); }); } /// <summary> /// Invoked when connection is lost to the current store, or on a Connect() failure. /// </summary> /// <param name="failure">Information regarding the failure.</param> private void OnStoreDisconnected(StoreConnectionFailureDescription failure) { } /// <summary> /// Invoked with products that are successfully fetched. /// </summary> /// <param name="products">Products successfully returned from the app store.</param> private void OnProductsFetched(List<Product> products) { // Fetch purchases for successfully retrieved products m_StoreController.FetchPurchases(); } /// <summary> /// Invoked when an attempt to fetch products has failed or when a subset of products failed to be fetched. /// </summary> /// <param name="failure">Information regarding the failure.</param> private void OnProductsFetchFailed(ProductFetchFailed failure) { } /// <summary> /// Invoked when previous purchases are fetched. /// </summary> /// <param name="orders">All active pending, completed, and deferred orders for previously fetched products.</param> private void OnPurchasesFetched(Orders orders) { } /// <summary> /// Invoked when an attempt to fetch previous purchases has failed. /// </summary> /// <param name="failure">Information regarding the failure.</param> private void OnPurchasesFetchFailed(PurchasesFetchFailureDescription failure) { } /// <summary> /// Invoked when a purchase needs to be processed and fulfilled. /// </summary> /// <param name="order">The order awaiting fulfillment.</param> private void OnPurchasePending(PendingOrder order) { }}
Get a StoreController
StoreControllerStoreControllerAttach event handlers to the StoreController
For your store to function correctly, attach handlers to these events:
- OnStoreDisconnected
- OnProductsFetched
- OnProductsFetchFailed
- OnPurchasesFetched
- OnPurchasesFetchFailed
- OnPurchasePending
You may need to implement additional handlers as you integrate In-App Purchasing into your project. For a full list of events available through , refer to Events.
StoreControllerConnect to your app store
Call StoreController.Connect to connect to the app store. The returned resolves when the connection either completes or fails. A connection failure will invoke the event. You must be connected to the store before using any IAP functionality.
TaskOnStoreDisconnectedFetch products
Note
Define your products in your catalog before fetching them. To choose a catalog setup method, refer to Create an IAP catalog.
To validate that your products are available for purchase, call StoreController.FetchProducts. Upon success, the event will be invoked with a list of successfully returned products. will be invoked in the event of a failure.
OnProductsFetchedOnProductsFetchFailedPurchases can only be fetched or initiated for products which have been successfully returned. can be called multiple times during runtime, but you must wait for any previous requests to finish before calling again.
FetchProductsFetchProductsWhen using the Apple App Store, may be invoked for unprocessed orders after completes.
OnPurchasePendingFetchProductsFetch products from a catalog created in the Editor
The initialization steps example above defines products directly in code with . If you instead defined your products using the IAP Catalog window in the Editor, follow these steps to fetch them:
CatalogProvider- Call to load the catalog you created in the Editor.
ProductCatalog.LoadDefaultCatalog - Pass the catalog to to get a
CodelessCatalogProvider.PopulateCatalogProviderpopulated with your products.CatalogProvider
The following example loads a catalog created in the Editor and populates a with its products:
CatalogProvider// Load the catalog created in the Editorvar catalog = ProductCatalog.LoadDefaultCatalog();var catalogProvider = CodelessCatalogProvider.PopulateCatalogProvider(catalog);
Use this in place of the one built with in the initialization steps example above, then continue with as shown.
catalogProviderCatalogProvider.AddProductcatalogProvider.FetchProductsGetProducts
GetProductsFetchProductsFetchProductsFetchProductsGetProductsFetch purchases
Call to request your player's current active orders. Active orders include , (active subscriptions and active non-consumables), and . Refer to Purchases for more information.
StoreController.FetchPurchasesPendingOrdersConfirmedOrdersDeferredOrdersCalls to will trigger one of two event handlers: , which will be invoked with an object containing all Pending, Confirmed, and Deferred orders returned from the store or , which will be invoked in the event of a failure.
When using Google Play, this will invoke the event for any purchases which have not been processed.
FetchPurchasesOnPurchasesFetchedOrdersOnPurchasesFetchFailedOnPurchasePendingThis is not strictly required to begin using In-App Purchasing functionality. However, it is recommended that you fetch and handle existing purchases before initiating new purchases, as you may encounter unexpected behavior otherwise.
Note that if you fetch additional products during runtime, you will need to fetch purchases again.
Fetch purchases offline
Some platform libraries, such as Apple's StoreKit 2, cache entitlements on the device for offline access without caching product data. Although this approach isn't recommended, you can still call after an callback. In this case, returns purchase information, but the linked products will have a of . Also, both and are set to the store-specific identifier.
FetchPurchasesOnProductsFetchFailedFetchPurchasestypeProductType.UnknownProductDefinition.idProductDefinition.storeSpecificIdNote
This doesn't apply to StoreKit 1. While StoreKit 1 caches the receipt on the device, the package requires fetched product data to parse receipt data. If product fetching fails, doesn't return any purchase information.
FetchPurchasesGetPurchases
GetPurchasesFetchPurchasesFetchPurchasesGetProductsFetchProductsFetchPurchasesGetPurchasesAutomatically initialize Codeless IAP
For instructions on how to set up Codeless IAP, refer to Set Up Codeless IAP.
Note
You should not enable auto-initialize if you also initialize manually in a script, as this may cause errors.
Automatic Unity Game Services initialization for Codeless IAP
If you are using the Codeless IAP, enable Unity Gaming Services automatic initialization by checking the Automatically initialize Unity Gaming Services checkbox at the bottom of the IAP Catalog window.
This ensures that Unity Gaming Services initializes immediately when the application starts.
To use this feature, Automatically initialize UnityIAPServices (recommended) must be enabled. If you do not see these checkboxes inside the IAP Catalog, it may be because you have not yet added products in the catalog window.
This initializes Unity Gaming Services with the default initialization options. Some services require specific initialization options and might not work with the default configuration. If you need custom options, initialize Unity Gaming Services using the coded API described above.