Step-by-step IAP integration guide for Unity

Last updated 1 day ago

Step-by-step IAP integration guide for Unity

This guide provides a clear, step-by-step walkthrough for integrating in-game purchases (also known as in-app purchases or IAP) into your web game using the Playgama SDK. While this guide uses Unity as the example engine, the Playgama SDK is designed to work seamlessly with other engines and JavaScript frameworks. Once integrated, your IAP will function across any supported portal, including .

You can find the open-source code for Demo project (including the IAP examples) here:

Understanding In-App Purchases and Pricing

In-app purchases (IAP) allow players to buy digital items or features directly within your game. The way you set prices for your IAP can vary depending on the platform where your game is published.

Some platforms may require you to set prices directly in real-world currency (e.g., USD).
Other platforms utilize a virtual currency system. In this case, you'll set and display the price of your IAP in the platform's specific virtual currency (for example, Golden Fennecs* for Playgama.com, Yan for Yandex, Stars for Playdeck, etc.). Players first acquire the platform's currency and then spend it on items in your game.

_{(* Note: The conversion rate between Golden Fennecs and real-world currencies is managed by the platform Playgama.com. Basically, 1 Golden Fennec equals $0.05 USD, meaning an item priced at $3.99 USD would cost approximately 80 Golden Fennecs. Precise rates can be confirmed with your Developer Success Manager.)}

Prerequisites

Before you begin, ensure you have:

Downloaded and installed the latest Playgama SDK into your Unity project. is more information.
Registered a developer account on the .

This guide references our , which showcases a basic integration using the Playgama Bridge SDK. You can find the open-source code .

Step 1: Define Your IAP Types and Items

1) First, decide which types of purchases your game will offer. We support two main types:

Consumable: single-use items (e.g., coins, gems, boosters), they can be purchased repeatedly. Ideal for temporary boosts or resource refill.
Permanent: items that remain with the player permanently (e.g., ad-free mode, skins, characters), they can only be purchased once.

Understanding this difference will help you design a clear, player-friendly IAP strategy.

2) Next, create a list of your specific IAP items and assign a unique id to each. This id will be used consistently across platforms and in your code.

💡 Important: For id, it is allowed to use letters, numbers, and the underscore character (_), but you can't use spaces or the hyphen character (-).

Example IAPs for our Demo game:

NO_Ads: A non-consumable item to permanently remove advertisements (player buy once and then have it unlimited within the game).
100_Coins: A consumable item granting 100 units of the demo's in-game currency (player can buy as much as they want and then spent within the game).

Step 2: Configure IAP in `playgama-bridge-config.json`

You need to declare your IAPs within the playgama-bridge-config.json file located in your Unity project. This file tells the SDK about your purchasable items on different platforms.

Add your IAP definitions to the payments array in the JSON file. Here’s an example based on our Demo project:

{
    "platforms": {
        "game_distribution": {
            "gameId": ""
        },
        "telegram": {
            "adsgramBlockId": ""
        },
        "y8": {
            "gameId": "",
            "adsenseId": "",
            "channelId": ""
        },
        "lagged": {
            "devId": "",
            "publisherId": ""
        }
    },
    "advertisement": {
        "interstitial": {
            "preloadOnStart": true
        },
        "rewarded": {
            "preloadOnStart": true
        }
    },
    "payments": [
        {
            "id": "NO_Ads",
            "playgama": {
                "amount": 1
            },
            "playdeck": {
                "amount": 1,
                "description": "Disable Interstitial advertisements from the game"
            }
        },
        {
            "id": "100_Coins",
            "playgama": {
                "amount": 1
            },
            "playdeck": {
                "amount": 1,
                "description": "Get 100 coins"
            }
        }
    ]
}

Key Configuration Fields:

id: The primary identifier you'll use in your game's code to refer to this IAP. Make it descriptive (e.g., REMOVE_ADS, PACK_100_GEMS). Later we will use id to get purchase names and prices inside our game.
amount : The price of the IAP in platform currency (Golden Fennecs** for playgama and qa_tool, Stars for playdeck). Calculate this based on your desired USD price point using the platform's conversion rate.

^{** 1 Golden Fennec equals $0.05 USD. For the qa_tool, you can set a low amount (like 1) for easy testing.}

description : A user-friendly description of the IAP displayed on the specific platform.

Replace the example IAPs in the payments section with your own game's items.

Step 3: Implement IAP Logic in Unity

With the configuration complete, let's integrate the IAP functionality into your Unity project. We'll use the PlaygamaIAP.cs script provided in the demo project as a foundation. While this script covers the essential calls, you may want to refactor or build upon it for a production-ready implementation.

Initialization and Catalog Fetching:

The core logic typically starts by fetching the available product catalog from the Playgama Bridge SDK. This retrieves details like localized names and prices for the IAPs you defined in the JSON file.

private void Start()
{
    // Initialize No-Ads text based on saved flag
    UpdateNoAdsAvailableText(isNoAdsBought);

    // Fetch the product catalog
    Bridge.payments.GetCatalog(OnGetCatalogCompleted);
}

Inside Start method, first we initialize NoAdsAvailableText, then load catalog by using Bridge.payments.GetCatalog method and OnGetCatalogCompleted callback.

Inside OnGetCatalogCompleted we are getting the information from Catalog and display it in our demo project.

Step 4: Trigger Purchases from UI Elements

You'll need UI elements (typically Buttons) in your game to allow players to initiate purchases. We call InitiatePurchase method with specific name to Initiate Purchase. Instead of name you can also use ID and match ID in your script, but for this case to keep things simple we will use name.

public void InitiatePurchase(string id)
{
    // Show spinner & start the purchase flow
    iapLoading.SetActive(true);
    currentPurchaseId = id;
    Bridge.payments.Purchase(currentPurchaseId, OnPurchaseCompleted);
}

Here is full script for IAPButton class:

You need to add IAPButton.cs script the the same gameobject which also has attached Button component. You can refer in screenshot below:

So basically, in our IAPButton.cs script, we have method for calling IAP purchase from PlaygamaIAP.cs script and a RefreshButton() method, which is reloading / assigning purchase.

private void OnEnable()
{
    playgamaIAP.OnPurchasesLoaded.AddListener(RefreshButton);
}

private void OnDisable()
{
    playgamaIAP.OnPurchasesLoaded.RemoveListener(RefreshButton);
}


public void RefreshButton()
{
    purchaseName.text = playgamaIAP.GetPurchaseNameById(id);
    purchasePrice.text = playgamaIAP.GetPurchasePriceById(id);
}

In this example we subscribe / unsubscribe to OnPurchaseLoaded event and inside RefreshButton function we just refresh text on the button.

So, essentially, when the user clicks the button, in our Demo project the function with the parameter "NO_Ads" (or "100_Coins") is called, and we initiate the purchase via the PlaygamaIAP.cs script.

Step 5: Handle Purchase Completion and Consumption

The final step is handling the outcome of the purchase attempt within your main IAP script. Let’s dive deeper into InitiatePurchase(string id) function that we are using inside IAPButton.cs.

public void InitiatePurchase(string id)
{
    // Show spinner & start the purchase flow
    iapLoading.SetActive(true);
    Bridge.payments.Purchase(id, OnPurchaseCompleted);
}

As shown in Step 4, your UI button will call the InitiatePurchase method located in your PlaygamaIAP.cs script. The iapName parameter passed to this method is the id you defined in your playgama-bridge-config.json file (e.g., "NO_Ads", "100_Coins").

You need to fill it for each supported platform (but no worries, it can be same for each platform).

The id is typically set in the Unity Editor for each IAPButton using [SerializeField] section (screenshot below):

Now we are getting to the most interesting part — that’s the InitiatePurchase function with OnPurchaseCompleted callback inside PlaygamaIAP.cs class. This function is responsible for starting the purchase process with the Playgama SDK.

public void InitiatePurchase(string id)
{
    // Show spinner & start the purchase flow
    iapLoading.SetActive(true);
    Bridge.payments.Purchase(id, OnPurchaseCompleted);
}

private void OnPurchaseCompleted(bool success, Dictionary<string, string> purchase)
{
    // Hide spinner after a moment
    Invoke(nameof(InvokeDisable), 0.5f);

    if (!success) return;
    
    purchase.TryGetValue("id", out var purchaseId);
    
    Debug.Log($"OnPurchaseCompleted ({purchaseId}), success: {success}");

    if (purchaseId == "NO_Ads")
    {
        // Non-consumable: just mark bought
        isNoAdsBought = true;
        UpdateNoAdsAvailableText(true);
    }
    else
    {
        // Consumable: consume to credit coins, etc.
        Bridge.payments.ConsumePurchase(purchaseId, OnConsumePurchaseCompleted);
    }
}
    
private void OnConsumePurchaseCompleted(bool success, Dictionary<string, string> purchase)
{
    if (!success) return;
 
    purchase.TryGetValue("id", out var purchaseId);
    
    Debug.Log($"OnConsumePurchaseCompleted ({purchaseId}), success: {success}");
   
    
    if (purchaseId == "100_Coins")
    {
        coinAmount += 100;
        coinAmountText.text = "Balance: " + coinAmount + " Coins";
    }
}

OnPurchaseCompleted callback function is executed once the platform processes the purchase request. It checks the success flag. If false, the purchase failed, and the function exits. If success is true:

It checks if the purchaseId is "NO_Ads". If so, it's a non-consumable item. The game state is updated by setting isNoAdsBought to true, and the UI is refreshed via UpdateNoAdsAvailableText(true)(remember to save this isNoAdsBought state persistently).
If the purchaseId is not "NO_Ads" (e.g., "100_Coins"), it's treated as a consumable item. In this case, Bridge.payments.ConsumePurchase() is called. This is crucial for consumable items, as it informs the platform that the item has been delivered, allowing the player to purchase it again.

💡 Important: Always call ConsumePurchasemethod for consumable items after a successful purchase callback like in example above. Failure to consume prevents the player from buying the item again and may indicate the item wasn't properly delivered.

Step 6: Testing Your Integration

Test Purchases: All purchases made through the QA Tool are "testing" transactions. You will not be charged any real money during this testing phase.
Non-Consumable Purchase Outcome:
- For non-consumable purchase you will get "Success" message for payment in the QA Tool logs

Consumable Purchase Outcome:
- For consumable purchase you will get "Success" message for payment, and right after you should see "Success" message for consume. (Remember, you need to call Consume method right after purchase, if it's consumable)
- Important Reminder: For consumable items, it is crucial to call the ConsumePurchase method immediately after a successful purchase confirmation.