In-App Purchase Integration

Note: You are viewing the Unity version of this topic. To view this topic for native development, see In-App Purchase Integration (Native). To view this topic for Unreal development, see In-App Purchase Integration (Unreal).

In-app purchases (IAP) allow users to purchase items without leaving your app.

There are two types of items that you can offer in your game, consumable and durable.

• Durable - Durable items are single-use items that persist with the user. Meaning, once the item has been purchased, it cannot be purchased again. For example, you may offer the initial game download for free with only a demo level, then offer additional levels as in-app purchases.
• Consumable - Consumable items can be purchased multiple times. For example, consumable IAP may be ‘character lives’ or ‘coins’ that are used during the course of gameplay. Consumable purchases must be ingested by your app before they can be made available for purchase again.

Note: All IAP operations require the user to be connected to the Internet.

Define the Items For Purchase

Before you begin integrating the IAP methods in your experience, you need to define the items that you will be offering for purchase. The in-app purchase list can be updated or modified at any time.

Define IAP with the Add-on Dashboard

Use the Add-on page of the developer dashboard to easily define items for purchase. This dashboard enables you to set a name, the SKU that you use to reference the add-on in your code, a description, price, assets and other information that describe the add-on. A description is required in order to retrieve purchasable items by SKU using API commands.

See Add-ons for more information.

Bulk Definition of IAP Items

You can define your IAP in bulk, create a tab-separated (.tsv) file with the following format. An IAP item template with this format available for download from Your Org>app namePlatform Services > Add-ons section of the developer dashboard . Select the dropdown split button on Create Add-on and then Upload TSV.

The values for the items in the table above are:

• SKU - The unique string that you use to reference the IAP item in your app. The SKU is case-sensitive, the name you define in the Dashboard must exactly match the SKU you reference in your code.
• Name - The short descriptive name that the user will see.
• Description - The full description of the item the user will see. Be as descriptive as necessary to avoid any confusion.
• Currency - Currency is the unit of currency that the item will be charged in. Only USD is supported at this time. The IAP item will be converted to the local user’s preferred currency at the time of purchase.
• Amount - The amount to charge for the IAP item. Available prices are listed below.
• Item Type - The type of item for sale. Options are consumable and durable. Please see the description above for the difference between the two.

Once you’ve created the IAP file, you can upload your IAP items by selecting Upload TSV and following the on-screen prompts. After you upload your items, you will be able to view them on the Add-Ons page.

Note: You must enter your payment information for your account before you can download the template or upload a file.

Available IAP Prices

The following are the supported IAP item price tiers:

$0.01, $0.10, $0.99, $1.49, $1.99, $2.00, $2.37, $2.49, $2.67, $2.75, $2.99, $3.34, $3.99, $4.99, $5.35, $5.99, $6.69, $6.99, $7.49, $7.99, $8.99, $9.69, $9.99, $10.49, $10.99, $11.99, $12.99, $14.99, $16.74, $16.99, $18.74, $19.99, $20.99, $22.49, $22.99, $24.99, $26.99, $27.99, $29.99, $33.49, $34.99, $36.99, $39.99, $44.99, $45.99, $48.99, $49.99, $54.99, $59.99, $69.99, $79.99 $89.99, $99.99, $159.99, $199.99

App Manifest Requirements

For IAP associated with downloadable content, mark your app as requiring an Internet connection.

• On the app dashboard, on the App Specifications page, From Is an Internet Connection Required drop-down, select the Internet connection required for downloadable contents option.
• Make sure the Android manifest file has the READ_EXTERNAL_STORAGE permission because asset files are typically stored on external storage. The following example shows the manifest entry.

<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />

Integrate IAP

Once you’ve defined the items that you would like to offer as purchases, you can start building them as purchasable items into your app.

The following SDK methods can be called from your client app. Detail about each function can be found in the Platform SDK Reference Content.

Anti-Fraud Measures

In-App Purchases can be a wonderful way to increase income from your game. They also increase the content, and targeted In-App Purchase releases can draw users back to your game to try out new outfits, accessories, and more.

But popular games can be targeted for instances of fraud and other abuses of your purchases. Here are suggestions to prevent abuse of purchasable in game content and fraud in your purchases. We suggest incorporating anti-fraud and anti-abuse measures into your game when you’re adding In-App Purchases.

• Check for Voided Purchases - Only allow a user to interact with legitimately purchased items. It’s recommended to not load an item into a scene until the the item purchase is verified.
• Don’t package your unlocked content in your main application - Consider using asset files instead of including In-App Purchase content with your application. Check to confirm that a user has purchased content before downloading it to your application.

Get a List of Assets Associated with an App

At app startup, you can call the following method to get a list of all the assets associated with the app.

Platform.AssetFile.GetList

This method returns a list of available asset details. Each item in the array has the following properties:

• assetFileName - the file name,
• assetFileID - Asset identifier
• IapStatus, which is one of the following values: free, entitled, or not-entitled
• downloadStatus, which is one of the following values:
  • installed meaning that user has installed the file
  • available meaning that user can download the file
  • in-progress meaning the file is being downloaded or is installing for that user.

Initiate downloads

If there is a file that is available to download, meaning its status is free or entitled, and download_status = available, you can initiate the download by calling:

• Platform.AssetFile.DownloadById

To make this call, pass the ID of the item as returned by the initial GetList call. When you make this call, you will receive an immediate DownloadResult response with the path to the asset as a confirmation that the request was successful. You should also listen for DownloadUpdate notifications which return info about transferred bytes, and a complete flag that notifies you when the download is complete.

Retrieve all of the user’s purchased items

To retrieve a list of IAP purchases that the user has made, use the following method. The returned list includes all durable type purchases and any consumable type purchases that have not been consumed.

Platform.IAP.GetViewerPurchases()

Retrieve a cached list of durable items a user has purchased

To retrieve a list of durable IAP items that the user has purchased use the following method. The returned list contains non-consumable purchases and is populated from the device cache. You should always use GetViewerPurchases first and then this method if the other call fails.

Platform.IAP.GetViewerPurchasesDurableCache()

Retrieve a list of available items and prices by SKU

To retrieve a list of IAP items that are available to the user to purchase by SKU, use this method. The SKUs must have a description to be retrieved by this method.

Platform.IAP.GetProductsBySKU()

Launch the checkout flow for a SKU

To launch the checkout flow for a user to complete the purchase of a specified user, use the following method:

Platform.IAP.LaunchCheckoutFlow()

Consume a purchased item

To consume a purchased item on behalf of a user, which then marks the item as used, in-app, use the following method:

Platform.IAP.ConsumePurchase()

Example Implementation

The following Unity example demonstrates the end-to-end flow of retrieving information for an IAP item, displaying that information to the user, consuming any outstanding purchases, and initiating the checkout flow when a user indicates that they would like to make a purchase. The following example is taken from the VRBoardGame sample app. See the Sample Appspage for more information about the apps that are available.

using UnityEngine;
using Oculus.Platform;
using Oculus.Platform.Models;
using UnityEngine.UI;


// This class coordinates In-App-Purchases (IAP) for the application.  Follow the
// instructions in the Readme for setting up IAP on the Oculus Dashboard.  Only
// one consumable IAP item is used is the demo: the Power-Ball!
public class IAPManager : MonoBehaviour
{
    // the game controller to notify when the user purchase more powerballs
    [SerializeField] private GameController m_gameController;

    // where to record to display the current price for the IAP item
    [SerializeField] private Text m_priceText;

    // purchasable IAP products we've configured on the Oculus Dashboard
    private const string CONSUMABLE_1 = "PowerballPack1";

    void Start()
    {
        FetchProductPrices();
        FetchPurchasedProducts();
    }

    // get the current price for the configured IAP item
    public void FetchProductPrices()
    {
        string[] skus = { CONSUMABLE_1 };
        IAP.GetProductsBySKU(skus).OnComplete(GetProductsBySKUCallback);
    }

    void GetProductsBySKUCallback(Message<ProductList> msg)
    {
        if (msg.IsError)
        {
            PlatformManager.TerminateWithError(msg);
            return;
        }

        foreach (Product p in msg.GetProductList())
        {
            Debug.LogFormat("Product: sku:{0} name:{1} price:{2}", p.Sku, p.Name, p.FormattedPrice);
            if (p.Sku == CONSUMABLE_1)
            {
                m_priceText.text = p.FormattedPrice;
            }
        }
    }

    // fetches the Durable purchased IAP items.  should return none unless you are expanding the
    // to sample to include them.
    public void FetchPurchasedProducts()
    {
        IAP.GetViewerPurchases().OnComplete(GetViewerPurchasesCallback);
    }

    void GetViewerPurchasesCallback(Message<PurchaseList> msg)
    {
        if (msg.IsError)
        {
            PlatformManager.TerminateWithError(msg);
            return;
        }

        foreach (Purchase p in msg.GetPurchaseList())
        {
            Debug.LogFormat("Purchased: sku:{0} granttime:{1} id:{2}", p.Sku, p.GrantTime, p.ID);
        }
    }

    public void BuyPowerBallsPressed()
    {
#if UNITY_EDITOR
        m_gameController.AddPowerballs(1);
#else
        IAP.LaunchCheckoutFlow(CONSUMABLE_1).OnComplete(LaunchCheckoutFlowCallback);
#endif
    }

    private void LaunchCheckoutFlowCallback(Message<Purchase> msg)
    {
        if (msg.IsError)
        {
            PlatformManager.TerminateWithError(msg);
            return;
        }

        Purchase p = msg.GetPurchase();
        Debug.Log("purchased " + p.Sku);
        m_gameController.AddPowerballs(3);
    }
}

Server to Server APIs

For details on challenge server-to-server APIs, see IAP Server to Server APIs.