Custom purchasing integration for Unity developers

Overview

This guide covers integration for implementing a purchasing adapter in your made-with-Unity game, to take advantage of Unity's optimization features without using Unity IAP.

  • If you are an iOS developer using Objective-C, click here.
  • If you are an Android developer using Java, click here.

Guide contents

  1. Configure your Project for Unity Ads.
  2. Manually configure your Product Catalog on the developer dashboard.
  3. Configure an IAP Promo on the developer dashboard.
  4. Implement a purchasing adapter in your game code, using the Monetization.IPurchasingAdapter interface API.
  5. Implement game logic and purchase events within the purchasing adapter.
  6. Initialize the purchasing adapter and Unity Ads SDK.

Implementation

Configuring your Project for Unity Ads

To implement a purchasing adapter, you must integrate Unity Ads in your Project. To do so, follow the steps in the basic ads integration guide that detail the following:

Important: Custom purchase integration requires the Unity Ads SDK version 3.0 or higher.

Once your Project is configured for Unity Ads, proceed to creating a Product Catalog.

Configuring Product Catalogs on the developer dashboard

Before implementing your purchasing adapter, navigate to the Operate tab of the developer dashboard, then follow the manual configuration instructions for populating a Product Catalog.

Configuring Promotions on the developer dashboard

From the Operate tab of the developer dashboard, follow the instructions for configuring an IAP Promo.

Implementing the purchasing adapter

A purchasing adapter acts as the hook for the Monetization API to retrieve the information it needs from your custom IAP implementation.

In your game script, include the UnityEngine.Monetization namespace, then create a class that implements a purchasing adapter. You will use two methods (RetrieveProducts and Purchase) to define the game logic you want the purchasing adapter to use. These methods require a class using the IPurchasingAdapter interface. You must implement them so the SDK can call them as needed when managing your Product transactions.

using UnityEngine.Monetization;

public class IAPManager: MonoBehaviour, IPurchasingAdapter {
    // Implement RetrieveProducts and OnPurchase functions here
}

Retrieving your Product Catalog

The SDK calls RetrieveProducts to retrieve the list of available Products. The function must convert your IAP products into Monetization.Product objects. This requires a minimum of the following properties defined for each product:

  • productID
  • localizedPriceString
  • productType
  • isoCurrencyCode
  • localizedTitle

The function takes an IRetrieveProductsListener listener. Call the listener’s OnProductsRetrieved function to send the retrieved Products list back to the SDK.

Processing a purchase

The SDK calls Purchase when a user clicks the buy button for a promotional asset. The purchase’s success or failure handling depends on your in-app purchasing implementation.

The function takes an ITransactionListener listener.

  • If the transaction succeeds, call the listener’s OnTransactionComplete method using a TransactionDetails object.
  • If the transaction fails, call the listener’s OnTransactionError method, using a TransactionErrorDetails object.

Example adapter implementation

using UnityEngine.Monetization;

public class IAPAdapter: MonoBehaviour, IPurchasingAdapter {

    // Retrieve and provide your Product Catalog for the SDK:    
    public void RetrieveProducts (IRetrieveProductsListener listener) {    

        // Query your Products here, convert them to Monetization.Products, then populate the Product list with them:        
        List<Product> products = new List<Product> ();
        products.Add (new Product) {
            productId = "100bronzeCoins",
            localizedTitle = "100 Bronze Coins",
            localizedDescription = "Awesome Bronze Coins for a new low price!",
            localizedPriceString = "$1.99",
            isoCurrencyCode = "USD",
            productType = "Consumable",
            localizedPrice = 1.99m
        });

        // provide the retrieved Products list:
        listener.OnProductsRetrieved (products);
    }

    // Define game logic for handling purchases:    
    public void Purchase (string productId, ITransactionListener listener, IDictionary<string, object> dict) {
        // Example third-party purchasing function:
        ThirdPartyPurchasing.purchaseProduct (productId);

        // When ThirdPartyPurchasing succeeds:
        listener.OnTransactionComplete (new TransactionDetails {
            currency = "USD",
            price = 1.99m,
            productId = "100bronzeCoins",
            transactionId = ThirdPartyPurchasing.transactionId,
            receipt =
                "{\n\"data\": \"{\\\"Store\\\":\\\"fake\\\",\\\"TransactionID\\\":\\\"ce7bb1ca-bd34-4ffb-bdee-83d2784336d8\\\",\\\"Payload\\\":\\\"{ \\\\\\\"this\\\\\\\": \\\\\\\"is a fake receipt\\\\\\\" }\\\"}\"\n}"
        });

        // When ThirdPartyPurchasing fails:
        listener.OnTransactionError (new TransactionErrorDetails {
            transactionError = TransactionError.NetworkCancelled,
            exceptionMessage = "Test exception message",
            store = Store.GooglePlay,
            storeSpecificErrorCode = "Example: Google Play lost connection",
        });
    }
}

Initializing the purchasing adapter and SDK

After you’ve implemented the purchasing adapter, you must provide a reference to it using SetPurchasingAdapter. Finally, you must initialize the SDK using your Project’s Game ID for the appropriate platform. You can locate the ID on the Operate tab of the Developer Dashboard by selecting the Project, then selecting Settings > Project Settings from the left navigation bar (see the Dashboard guide section on Project Settings for details).

To avoid errors, implement these calls as early as possible in your game’s run-time life cycle. For example:

Start () {
    Monetization.SetPurchasingAdapter (GameObject.Find ("IAPManager").GetComponent<IAPAdapter> ()); 
    Monetization.Initialize ("1234567", false);
}

In this example, "IAPManager" references a GameObject containing a script component called IAPAdapter, which extends the purchasing adapter.

What's next?

Learn how to implement custom IAP Promo assets in your game, or return to the Monetization hub.