unity-iap

Unity IAP Implementation Skill

Purpose

Implement a Unity IAP (In-App Purchase) system for consumable products using Unity Purchasing package. The architecture follows a clean separation pattern: a thin wrapper service handles platform communication, a ScriptableObject catalog defines products, and decoupled events handle UI communication.

When to Use

• Adding consumable IAP products (gems, coins, etc.)
• Integrating Unity Purchasing package
• Creating a shop/store UI that triggers purchases
• Setting up receipt validation for Google Play or App Store

Architecture Overview

UI (ShopPopup)
    |
    |-- [Purchase button click] --> Event: PurchaseRequested(productId)
    |
IAPService (MonoBehaviour + IDetailedStoreListener)
    |
    |-- [Platform purchase flow]
    |-- [Receipt validation]
    |-- [Grant reward] --> CurrencyVariable += amount
    |-- [Broadcast result] --> Event: PurchaseCompleted / PurchaseFailed
    |
UI (ShopPopup)
    |-- [Result event received] --> Update UI

Key Principles:

• UI never references IAPService directly
• IAPService never references UI
• Communication via events (SOAP ScriptableEvent or C# Action/event)
• Product data lives in a ScriptableObject catalog
• Reward granting happens inside IAPService for atomicity

Implementation Steps

Step 1: Install Unity Purchasing Package

Add com.unity.purchasing via Package Manager or manifest.json.

Step 2: Create Product Data Classes

IAPProductEntry - Serializable data class per product:

[Serializable]
public class IAPProductEntry
{
    public string ProductId;    // Must match store console ID
    public int RewardAmount;    // Currency amount to grant
    public Sprite Icon;         // Optional: for shop UI
}

IAPProductCatalog - ScriptableObject holding all products:

[CreateAssetMenu(menuName = "IAP/Product Catalog")]
public class IAPProductCatalog : ScriptableObject
{
    public List<IAPProductEntry> Products = new();

    public int GetRewardAmount(string productId)
    {
        return Products.Find(p => p.ProductId == productId)?.RewardAmount ?? 0;
    }
}

Step 3: Create IAPService

Implement IDetailedStoreListener with this lifecycle:

1. Awake() - DontDestroyOnLoad(gameObject)
2. Start() - InitializePurchasing() using ConfigurationBuilder
3. OnEnable() - Subscribe to purchase request event
4. OnDisable() - Unsubscribe from purchase request event

Critical methods:

• InitializePurchasing() - Register products from catalog, call UnityPurchasing.Initialize(this, builder)
• HandlePurchaseRequest(string productId) - Validate state, call _storeController.InitiatePurchase(product)
• ProcessPurchase(PurchaseEventArgs) - Validate receipt, grant reward, broadcast success
• OnPurchaseFailed(Product, PurchaseFailureDescription) - Broadcast failure

Step 4: Receipt Validation

private bool ValidateReceipt(string receipt)
{
#if UNITY_ANDROID && !UNITY_EDITOR
    try
    {
        var validator = new CrossPlatformValidator(
            GooglePlayTangle.Data(), null, Application.identifier);
        validator.Validate(receipt);
        return true;
    }
    catch (IAPSecurityException) { return false; }
#else
    return true;
#endif
}

Pre-release requirement: Generate GooglePlayTangle.cs via: Window > Unity IAP > IAP Receipt Validation Obfuscator

Step 5: Wire Up Shop UI

The shop UI should:

• Reference the purchase request event and result events
• Call purchaseRequestEvent.Raise(productId) on button click
• Subscribe to completed/failed events to update UI
• Use IAPService.GetLocalizedPrice(productId) for price display

Step 6: Assembly Definition Setup

Add Unity.Purchasing.SecurityStub reference to the main asmdef for Editor compatibility with Obfuscator/CrossPlatformValidator classes.

Step 7: Create Inspector Setup Guide

After implementation, generate a setup guide documenting:

• GameObject creation and component assignment
• All SerializeField references to assign
• ScriptableObject asset creation steps
• Pre-release checklist (Tangle generation, store console setup)

Communication Patterns

With SOAP (Recommended for SOAP projects)

Create ScriptableEvent<string> subclasses for purchase events. See references/implementation-patterns.md.

Without SOAP

Use C# events or UnityEvent:

public static event Action<string> OnPurchaseRequested;
public static event Action<string> OnPurchaseCompleted;
public static event Action<string> OnPurchaseFailed;

Common Pitfalls

Pitfall	Solution
Obfuscator not found in Editor	Add Unity.Purchasing.SecurityStub asmdef reference
AppleTangle missing	Pass null to CrossPlatformValidator if Apple not targeted
Sirenix errors in test asmdef	Add Sirenix DLLs to precompiledReferences when overrideReferences: true
Pending purchases lost	Return PurchaseProcessingResult.Complete only AFTER granting reward
Price shows empty	GetLocalizedPrice() only works after OnInitialized callback

Additional Resources

Reference Files

• references/implementation-patterns.md - Complete code templates with SOAP and non-SOAP variants