IAP Validation

Introduction

Cheaters and invalid IAP transactions can cause Adjust & Looker dashboards to display inaccurate values and the UA networks to train their algorithms on bad data. This can lead to the contamination of UA algorithms’ decision-making process and incorrect game design choices.

LionSDK offers static methods for IAP receipt validation to help reduce or eliminate the negative impacts of cheaters’ IAP transactions.

💡

By default, we do not block cheaters from cheating - they can still get their “stolen” goods; however, we do prevent event data from being sent to networks and flag those transactions as cheaters so that we filter out bad data. However, you can optionally block bad purchases; see the examples below.

Behind the scenes, LionSDK uses the Nakama SDK from Heroic Labs to help validate and track IAP receipts.

What does the package do?

Fire Adjust iap_purchase event to Adjust ONLY if the purchase is valid. This event displays revenue on Adjust dashboards and is passed to Networks as an important data point.
Fire inapp_purchase event to Snowflake (Looker) for valid and invalid(cheater) transactions. A parameter of the event will declare the validity of the purchases. This helps internally with monitoring; Looker dashboards will automatically filter out invalid transactions.

Requirements

Setup the Game on our Server

Based on the game status, the requirements differ:

If the game is hosted on Lion Studios’ Google Play / App Store accounts, contact your Product Manager so that the Product Manager can collaborate with the QA team to retrieve the credentials and complete the game setup.
If the game is hosted on your own Google Play / App Store account, we will require your Service Account’s Client Email & Private Key (GP) and Shared Secret (iOS). Deliver these keys to your Product Manager so that they can complete the setup.

Remove Events (if applicable)

LionSDK will automatically fire the required Adjust and Analytics IAP events. In your Unity Project, you should remove these events from your game code to prevent duplication and overcounting:

Remove any existing Adjust IAP-related events (iap_purchase, purchase_failed, purchase_unknown and purchase_notverified)
Remove any existing calls to LionAnalytics.InAppPurchase

Remove Adjust Purchase Verification package (if applicable)

If it is installed in your project, delete the Adjust Purchase SDK.

Install LionSDK

Complete the steps in Getting Started

Implementation

Call `IAPValidation.ValidateAndLog()`

If you use Unity Purchasing, you typically want to call IAPValidation.ValidateAndLog() in your ProcessPurchase method. This will send your receipt to our remote receipt validation service and log the results to both Lion Analytics and Adjust.

Parameters:

Product product: this is the UnityEngine.Purchasing.Product object that Unity Purchasing provides in the ProcessPurchase function’s PurchaseEventArgs parameter’s purchasedProduct field.
IAPGameplayInfo iapGameplayInfo: This object contains information required by LionAnalytics, including details about the in-game rewards. These include:
- List ReceivedItems
- List ReceivedCurrencies
- String PurchaseLocation

💡

See LionAnalytics documentation for further descriptions of these fields.

Action onSuccess (optional): This callback, if provided, will be raised if the receipt is valid.
Action onFailure (optional): This callback, if provided, will be raised if the receipt has not been validated. The ValidationStatus will provide the reason for the failure to validate.

💡

If you are not using Unity’s Purchasing package, you can replace the Product product parameter with IAPInfo iapInfo. This object must be constructed with the following elements: transactionID, productID, receiptPayload, isoCurrencyCode, localizedPrice, and localizedTitle.

Examples:

Simple inline call:

using LionStudios.Suite.Purchasing;

IAPValidation.ValidateAndLog(
    purchaseEventArgs.purchasedProduct, 
    new IAPGameplayInfo(
        new List<Item>()
        {
            new Item("NoAds", 1),
            new Item("SpecialWeapon", 1),
            new Item("BonusCards", 10)
        },
        new List<VirtualCurrency>()
        {
            new VirtualCurrency("coins", "normal", 10000),
            new VirtualCurrency("gems", "special", 10)
        },
        "shop"));

Full ProcessPurchase example:

using LionStudios.Suite.Purchasing;

PurchaseProcessingResult IStoreListener.ProcessPurchase(PurchaseEventArgs purchaseEventArgs)
{
    /// Your code

    Product product = purchaseEventArgs.purchasedProduct;
    IAPGameplayInfo gameplayInfo;
    switch (product.definition.id)
    {
        case "com.company.game.noads":
            gameplayInfo = new IAPGameplayInfo(
                new List<Item>(){ new Item("NoAds", 1) }, 
                new List<VirtualCurrency>(), 
                "ingame");
            break;
        case "com.company.game.noadsspecial":
            gameplayInfo = new IAPGameplayInfo(
                new List<Item>(){ new Item("NoAds", 1) }, 
                new List<VirtualCurrency>() { new VirtualCurrency("coins", "normal", 1000) }, 
                "specialpopup");
            break;
        case "com.company.game.coinpack1":
            gameplayInfo = new IAPGameplayInfo(
                new List<Item>(), 
                new List<VirtualCurrency>() { new VirtualCurrency("coins", "normal", 1000) }, 
                "iapshop");
            break;
        case "com.company.game.coinpack2":
            gameplayInfo = new IAPGameplayInfo(
                new List<Item>(), 
                new List<VirtualCurrency>() { new VirtualCurrency("coins", "normal", 5000) }, 
                "iapshop");
            break;
        default:
            gameplayInfo = new IAPGameplayInfo(null, null, "unknown");
            break;
    }

    IAPValidation.ValidateAndLog(product, gameplayInfo);
    
    // Your code for rewarding the player
    
}

Conditional reward

In some rare cases, you’ll want to reward the player only if the receipt is valid. This is not normal behavior and should be reserved for multiplayer games where cheaters can harm the experience of other players.

In this case, you will do the same as the previous example except for the last lines:

IAPValidation.ValidateAndLog(
		product, 
		gameplayInfo, 
		() => GiveReward(product.definition.id), 
		DisplayError);

void GiveReward(string productId)
{
    // Your code for rewarding the player
}

void DisplayError(ValidationStatus status)
{
    // Your code for displaying an error message to the player
}

Validation

If the package is implemented correctly, for each purchase, two events will be fired:

inapp_purchase: a LionAnalytics event used for analytics on Looker.
iap_purchase: a native Adjust event used by Adjust for revenue metrics.

Make sure that these events are received by following either of the paths below:

If you have access to Looker, for each relevant event, check the following:
- The event name appears [ref]
If you do not have access to Looker, please use the LionAnalytics QA Tool following the instructions here: Event Validation

validation

In Looker,inapp_purchase events have a ValidationStatus parameter that can be:

Success: The receipt is valid.
Failure: The receipt is invalid. Probably a cheater.
Error: Something went wrong when trying to validate the receipt, so we can’t define if the receipt is valid.

TroubleShooting

Many (or all) transactions showing Error validating IAP/Failure in Looker.
- Explanation: This kind of failure indicates an error communicating with Google, leading to a Failure status and a validation message, Error validating IAP.
- Cause: All games published in Lion Studios Google Play account(s) should already have the correct API Service Account credentials in place for all games, so while this is the most common cause for the error, it is not common for our games.
The cause we see most often is a bug in Google Play that occurs when your IAP bundles are created before linking your API Service Account on Google Play Console. Google assumes you first linked your API Service account, then added your various IAP packages. If you did this out of order, Google won’t recognize your existing IAP bundles.
- Resolution: Go to your IAP bundle in your Google Play Console and edit some details such as description of the IAP and save it again. We usually add a space, save changes, then remove the added spaceand save again. Any change made to the IAP bundle will trigger Google to reread IAP bundles, and should fix the bug so these bogus failures go away.

FAQ

I’m seeing the error: Library\PackageCache\com.lionstudios.beta.iap@0.1.0-b9\Runtime\IAPValidation.cs(128,25): error CS0103: The name ‘STORE NAME’ does not exist in the current context
- Please switch Unity Build Settings to iOS or Android platform.