Micro-Transaction System

Overview

Micro-transactions allow for items (bonus content, extra levels, etc.) to be purchased directly from within the game, i.e. using in-app purchasing on iOS.

Note: Micro-transaction functionality is currently limited to games running on the iOS platform.

MicroTransactionBase

The MicroTransactionBase class is the base class containing the functionality for performing micro-transactions. It inherits from the PlatformInterfaceBase and makes use of the delegate system contained in that class. Each platform (PC, iOS, etc.) has its own subclass extending from CloudStorageBase that provides the implementation specific to that platform.

Properties

• AvailableProducts - Holds the list of products available to be purchased, populated by QueryForAvailablePurchases() after the MTD_PurchaseQueryComplete callback is complete.
• LastError - Holds a description (string) of the most recent error if an error occurs during the purchase process.
• LastErrorSolution - Holds a description (string) of the possible solutions (if any) to the most recent erro if one occurs during the purchase process.

Functions

• Init - Event called by the engine to initialize the micro-transaction system.
• QueryForAvailablePurchases - Queries the system for what purchases are available and returns whether the query was initiated successfully.
• IsAllowedToMakePurchase - Returns whether the user is allowed to make purchases.
• BeginPurchase [Index] - Initiates the process of purchasing a product from the AvailableProducts list and returns whether the purchase was initiated successfully.
  • Index - The Int specifying the index into the AvailableProducts array of the product to purchase.

Delegates

The EMicroTransactionDelegate enum defines the IDs for the types of delegates that can receive callbacks. Delegates can be assigned to each of these using the Platform Interface Delegates system.

• MTD_PurchaseQueryComplete - Delegates assigned to this ID are executed when a query for available products is completed via QueryForAvailablePurchases().
  • bSuccessful - TRUE.
  • Data - Contains no data.
• MTD_PurchaseComplete - Delegates assigned to this ID are executed when an attempt to purchase a product is completed.
  • bSuccessful - TRUE.
  • Data - The IntValue will contain one of the enums in EMicroTransactionResult, and StringValue will have the Identifier from the PurchaseInfo that was bought with BeginPurchase. If MTR_Failed was returned, then LastError and LastErrorSolution should be filled out with the most recent localized and possible resolutions.

Products

Each available product is stored in the AvailableProducts array in the form of a PurchaseInfo. This struct contains all of the information about the product necessary to dsiplay it to the user and allow it to be purchased.

• Identifier - A string representing the unique identifier for the product.
• DisplayName - A string holding the name of the product to display to the user.
• DisplayDescription - A string holding the description of the product to display to the user.
• DisplayPrice - A string holding the price of the product to display to the user.

Implementation Details

The general workflow for setting up and using the In-App purchases for Unreal Engine 3 iOS games is outlined below:

1. Make sure your game is set up for micro-transactions in the iOS Provisioning Portal and set up available products for your game through the iTunes Connect application. For more information, see the Apple Developer Site.
2. Get a reference to the MicroTransactionBase object by calling the static GetMicroTransactionInterface() of the PlatformInterfaceBase class and set up your delegates for the product query and purchase callbacks, usually in PostBeginPlay() or some other initialization function depending on where you are placing the micro-transaction functionality.

      var MicroTransactionBase MicroTrans;
   
      ...
   
      MicroTrans = class'PlatformInterfaceBase'.static.GetMicroTransactionInterface();
      MicroTrans.AddDelegate(MTD_PurchaseQueryComplete, OnProductQueryComplete);
      MicroTrans.AddDelegate(MTD_PurchaseComplete, OnProductPurchaseComplete);
      

   OnProductQueryComplete and OnProductPurchaseComplete are just examples. These can be the names of any function matching the signature of the PlatformInterfaceDelegate delegate.

      delegate PlatformInterfaceDelegate(const out PlatformInterfaceDelegateResult Result);
      

3. To obtain the list of available products for the game, call QueryForAvailablePurchases() on the MicroTransactionBase object and wait for the MTD_PurchaseQueryComplete callback where you can handle the list of AvailableProducts to display them to the user in any way you desire (most likely in a menu of some sort.

      MicroTrans.QueryForAvailablePurchases();
      

4. Once the list of products is obtained, purchases can be made by calling BeginPurchase() on the MicroTransactionBase object, passing it the index of the product to purchase. This would most likely be the result of the user tapping a button in a menu.

      MicroTrans.BeginPurchase(0);
      

   This will attempt to purchase the first product (index 0) in the list of AvailableProducts.

A basic implementation can be found in the CloudMenuMicroTransaction.uc script of the UDKBase\Classes directory.