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 Playgama.com.

You can find the open-source code for Demo project (including the IAP examples) here: https://github.com/Playgama/bridge-unity-examples

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:

1. Downloaded and installed the latest Playgama SDK into your Unity project. Here is more information.

2. Registered a developer account on the Developer portal.

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

How the IAP Demo game looks

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 commonId to each. This ID will be used consistently across platforms and in your code.

💡 Important: For commonId, 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.

2KB

playgama-bridge-config.json

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": ""
        },
        "facebook": {
            "bannerPlacementId": "",
            "interstitialPlacements": [],
            "rewardedPlacements": []
        }
    },
    "payments": [
        {
            "commonId": "NO_Ads",
            "yandex": {
                "id": "NO_Ads"
            },
            "facebook": {
                "productID": "NO_Ads"
            },
            "msn": {
                "productId": "NO_Ads"
            },
            "playgama": {
                "amount": 1
            },
            "qa_tool": {
                "id": "NO_Ads",
                "amount": 1
            },
            "playdeck": {
                "amount": 1,
                "description": "NO_Ads"
            }
        }, 
        {
            "commonId": "100_Coins",
            "yandex": {
                "id": "100_Coins"
            },
            "facebook": {
                "productID": "100_Coins"
            },
            "msn": {
                "productId": "100_Coins"
            },
            "playgama": {
                "amount": 1 // in platform virtual currency Golden Fennecs
            },
            "qa_tool": {
                "id": "100_Coins",
                "amount": 1 // in platform virtual currency Golden Fennecs
            },
            "playdeck": {
                "amount": 1, // in platform virtual currency Stars
                "description": "100_Coins"
            }
        }
    ]
}

Key Configuration Fields:

• commonId: 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 commonId to get purchases name and prices inside our game.

• Platform-Specific IDs (id, productID, productId): The identifier for this IAP on each specific platform. Often, it's the same as the commonId. Ensure you configure these for every platform you intend to support.

• 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 iapName)
    {
        // Show spinner & start the purchase flow
        iapLoading.SetActive(true);
        currentPurchaseId = iapName;
        Bridge.payments.Purchase(currentPurchaseId, OnPurchaseCompleted);
    }

Here is full script for IAPButton class:

1KB

IAPButton.cs

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(buttonID);
        purchasePrice.text = playgamaIAP.GetPurchasePriceById(buttonID);
    }

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 iapName) function that we are using inside IAPButton.cs.

 public void InitiatePurchase(string iapName)
    {
        // Show spinner & start the purchase flow
        iapLoading.SetActive(true);
        currentPurchaseId = iapName;
        Bridge.payments.Purchase(currentPurchaseId, 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 commonId 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).

For the first button it will be NO Ads - exactly like we filled in json file in “commonId” - value

Now we do the same for 100 Coins IAP

The iapName 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 iapName)
    {
        // Show spinner & start the purchase flow
        iapLoading.SetActive(true);
        currentPurchaseId = iapName;
        Bridge.payments.Purchase(currentPurchaseId, OnPurchaseCompleted);
    }

    private void OnPurchaseCompleted(bool success, Dictionary<string, string> purchase)
    {
        Debug.Log($"OnPurchaseCompleted ({currentPurchaseId}), success: {success}");

        // Hide spinner after a moment
        Invoke(nameof(InvokeDisable), 1f);

        if (!success) return;

        if (currentPurchaseId == "NO_Ads")
        {
            // Non-consumable: just mark bought
            isNoAdsBought = true;
            UpdateNoAdsAvailableText(true);
        }
        else
        {
            // Consumable: consume to credit coins, etc.
            Bridge.payments.ConsumePurchase(currentPurchaseId, OnConsumePurchaseCompleted);
        }
    }

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 currentPurchaseId 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 currentPurchaseId 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

Once you've implemented these steps and build your game, upload the build to the QA Tool available on the Playgama Developer portal. Testing in the QA environment ensures your IAPs work as expected before releasing your game.

• 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

Non-Consumable Purchases example

• 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.

Consumable Purchases example

Feel free to contact your Developer Success Manager if you need any help or support.

Let's boost your game experience and revenue together! 🚀