Unibill

Introducing Hosted Content for Unibill

One plugin, seven platforms

BUY NOW

Introduction Overview How it works How to use this document Cross platform guide Overview How it works Defining your in App purchases Updating Inventory at Runtime Virtual currencies Defining your virtual currencies Checking currency balance Spending currency Gifting currency Calling Unibill methods Initialising Unibill Checking for Unibill errors Receiving messages from Unibill Browsing available purchases Initiating purchases Retrieving transaction history Overriding identifiers Clearing transaction history Accessing purchase receipts The Unibill demo scene Google Play Configure your Google Play public key Uploading your purchase metadata to Google Play Testing on an Android device Amazon Appstore Entering your purchase metadata in the Amazon portal Testing using the Amazon test client Apple App Store Configuring your iOS SKU Price tiers Using the screenshot taker Uploading your purchase metadata using the Application loader Note for Unity iOS standard users Testing on device Mac App Store Intro Testing In App Purchasing Windows Phone 8 Intro Testing In App Purchasing Windows 8 Testing Samsung Apps Setup Testing Getting Support

Introduction

Overview

Unibill is a one stop solution for in App purchasing in Unity3D; a single plugin that works across the Apple App store, Mac App Store, Google Play, Amazon App store, Samsung Apps Store, Windows Phone 8 and Windows 8.1!

What’s more, Unibill now offers cross platform downloadable content via Unibill Hosted Content; we take care of hosting your content, verifying your customer’s purchase receipts and delivering the content. It’s fully integrated with Unibill and works seamlessly across platforms and even the Editor, just like Unibill does.

Unibill also features automatic virtual currencies; just tell Unibill what your currencies are called and how much users get when purchasing which consumable In App Purchases.

As a demonstration of how simple it is, the following code snippet initialises Unibill and makes a purchase, and works across all seven platforms

Unibiller.onBillerReady += (state) => {
    if (UnibillState.SUCCESS == state) {
        Unibiller.initiatePurchase(Unibiller.AllPurchasableItems[0]);
    }
};

Unibiller.Initialise();

What’s more, Unibill is brimming with features to get you up and running in record time, including tools to help you bulk upload your metadata to Apple and Google, and automatic integration with Amazon’s SDK tester and Microsoft’s mock IAP framework on both Windows Phone and Windows Desktop.

How it works

Instead of using the raw billing interfaces of Apple, Google, Amazon and Microsoft, your application uses the more abstract Unibill interface. Unibill is responsible for communicating with the underlying billing system on each platform, so your code remains simple and clean.

Unibill does a huge amount of work for you, such as verifying your product data with Apple and Amazon when your application launches, and maintaining a database of what a user has purchased.

Unibill automatically integrates with your project, generating and merging your AndroidManifest and XCode projects as required. Changing between Google Play and Amazon billing is as simple as changing a drop down; Unibill handles everything else for you!

How to use this document

Start with the Cross platform guide, which is applicable to all billing platforms, then work through each platform specific section for each platform you are targeting.

Cross platform guide

Defining your in App purchases

Once you’ve installed the Unibill unity package, the first step is to tell Unibill what purchasable items your application has; the coins, potions, planets or subscriptions that you will be selling to your users.

You define your purchases using the Inventory Editor, a Unity editor window which you can find in the ‘Window/Unibill’ toolbar menu. The inventory editor tracks these purchasable items in an JSON file located at Assets/Plugins/unibill/resources/unibillInventory.json.txt, which you can edit manually (or with your own tools) if you prefer.

Configuration settings

These are global Unibill settings, specific to the underlying billing platforms. See the platform specific sections for details of how to fill these in.

Purchasable items

This is where you define your in app purchases. Click the ‘+’ button to define a new in app purchase, and enter the following fields:

Purchase type

“Consumable”	Can be purchased repeatedly. Suitable for consumable items such as virtual currencies.
“Non-Consumable”	Can only be purchased once. Suitable for one off purchases such as extra levels.
“Subscription”	Has a finite window of validity once purchased

Id

This uniquely identifies each In App Purchase. This should be in the format of a bundle identifier; eg com.companyname.appname.purchasename. This must be unique across all your purchasable items.

Name

The name of the purchasable item, as you display it to users.

Description

A description of the purchasable item, as you display it to users.

Virtual currencies

Unibill features built in support for virtual currencies; Unibill will track the player’s balance, incrementing it when they buy more and providing methods to check, credit and debit their balance.

1. Defining your currencies

Virtual currencies are defined in the inventory editor.  Just tell Unibill what your currency is called, and then set up a series of ‘mappings’ to the consumable in app purchases you have defined.

You don’t need to worry about subscribing to events or incrementing balances when purchases are made, Unibill will do it for you.

In the example screenshot, our “gold” can be bought in two different increments of 100 and 250.

2. Checking currency balance

decimal balance = Unibiller.GetCurrencyBalance("gold");

3.  Spending currency

if (Unibiller.DebitBalance("gold", 100)) {
 // Spend was successful
} else {
 // Not enough cash!
}

4. Gifting currency

Unibiller.CreditBalance("gold", 100);

Updating Inventory at Runtime

To avoid having to update your app every time you change your inventory of products, Unibill can fetch an updated configuration file from a URL of your specification, and use it the next time your application boots.

Unibill stores your configuration in a JSON file at Assets/Plugins/unibill/resources/UnibillInventory.json.txt.

Simply check the ‘use hosted config’ box and enter the URL where you will be publishing your inventory.

Calling Unibill methods

The entire Unibill API is a series of static methods in the Unibiller class; any methods you see referred to hereonin are to be found in the Unibiller class, which you can browse at Assets/Plugins/unibill/src/impl/Unibiller.cs.

See the next section, Initialising Unibill, for some sample code demonstrating the use of static functions.

There are no prefabs or management MonoBehaviours to worry about.

Initialising Unibill

You should initialise Unibill as soon as possible, ideally in the first scene that Unity loads.

To initialise Unibill you must subscribe to Unibill’s onBillerReady event, then call Unibiller.Initialise():

Note that is is essential that you subscribe to Unibill’s onBillerReady method *before* calling initialise, to avoid a race condition.

class ExampleMonoBehaviourThatInitialisesUnibill : Monobehaviour {

    public void Start() {
        Unibiller.onBillerReady += onInitialised;
        Unibiller.Initialise();
    }

    private void onInitialised(UnibillState result) {
    ...
    }
}

When Unibill has finished initialising, the Unibiller.onBillerReady event will be fired, which in this case will result in onInitialised() being called.

The UnibillState parameter has three possible results:

SUCCESS	Unibill encountered no problems and is ready to make purchases.
SUCCESS_WITH_ERRORS	Unibill encountered one or more non critical errors and is ready to make purchases. Details of these errors will have been printed to the console, or you can retrieve the errors manually.
CRITICAL_ERROR	Unibill was unable to initialise. Details of the error will have been printed to the console, or you can retrieve them manually. You should not attempt to make any purchases.

Checking for Unibill errors

*Unibill will always print diagnostic information to the device console*

When Unibill encounters an error it will automatically print a brief help message and a URL to the console; if you visit the URL in a browser you can find full documentation for the specific error. You can view the console output of a device using adb on android and xcode on iOS.

You can also retrieve these errors manually from Unibill if you so choose, by checking the Unibiller.Errors property which returns an array of the UnibillError enumeration. Full documentation for each error is available at http://www.outlinegames.com/unibill/errors#%5Berror name]

Receiving messages from Unibill

Unibill provides a strongly typed interface for informing your application of billing events, which works identically across all billing platforms.

The API is asynchronous; your application receives messages from Unibill by subscribing to events, which may fire at any time. The Unibiller class exposes the following static events that you may subscribe to:

///
/// Occurs after a call to Unibiller.Initialise.
///
/// UnibillState.SUCCESS Unibill initialised successfully.
///
/// UnibillState.SUCCESS_WITH_ERRORS Unibill initialised successfully but with one
/// or more non critical errors. Check the console logs or Unibiller.Errors.
///
/// UnibillState.CRITICAL_ERROR Unibill encountered a critical error and cannot make
/// purchases. Check the console logs or Unibiller.Errors.
public static event Action onBillerReady;

///
/// Occurs when the user chose to cancel the specified purchase rather than buy it.
///
public static event Action onPurchaseCancelled;

///
/// Occurs when the specified item was purchases successfully.
///
public static event Action onPurchaseComplete;

///
/// Occurs when the specified purchase failed.
///
public static event Action onPurchaseFailed;

///
/// Occurs when the specified purchase was refunded.
/// Unibill will automatically update the transaction database for the PurchasableItem by
/// decrementing the purchase count.
///
public static event Action onPurchaseRefunded;

///
/// Occurs when a call to Unibiller.restoreTransactions completed.
/// The parameter indicates whether the restoration was successful.
///
public static event Action onTransactionsRestored;

Browsing available purchases

Once Unibill has initialised successfully, you can retrieve details of the In App Purchases that you have defined using the Inventory Editor.

Unibill features the ‘PurchasableItem’ class to represent your purchasable items:

///
/// Represents an item that may be purchased as an In App Purchase.
///
public class PurchasableItem : IEquatable {
    ///
    /// A platform independent unique identifier for this PurchasableItem.
    ///
    public string Id;

    ///
    /// The PurchaseType of this PurchasableItem; Consumable, Non-Consumable or Subscription.
    ///
    public PurchaseType PurchaseType;

    /// The following fields are retrieved from the underlying billing system,
    /// eg iTunes connect, the Google play Publisher interface, etc.
    /// NOTE: Since these fields are retrieved from the Apple, Google etc,
    /// they will be blank when running in Editor mode.

    /// The precise formatting of this string varies across platforms.
    /// On Google Play, formatting includes the currency symbol.
    /// On other platforms, this is simply a decimal number.
    /// The localized price string.
    public string localizedPriceString { get; private set; }

    ///
/// Gets the localized product title.
    ///
    public string localizedTitle { get; private set; }

    ///
/// Gets the localized product description.
    ///
    public string localizedDescription { get; private set; }

}

The following properties return your PurchasableItems by PurchasableType(Consumable, Non-Consumable, Subscription) or you can retrieve a PurchasableItem directly if you know its identifier.

///
/// Get all PurchasableItem that can be purchased including Consumable,
/// Non-Consumable and Subscriptions.
///
public static PurchasableItem[] AllPurchasableItems;

///
/// Get all PurchasableItem of type Non-Consumable.
///
public static PurchasableItem[] AllNonConsumablePurchasableItems;

///
/// Get all PurchasableItem of type Consumable.
///
public static PurchasableItem[] AllConsumablePurchasableItems;

///
/// Get all PurchasableItem of type Subscription.
///
public static PurchasableItem[] AllSubscriptions;

///
/// Get the specified PurchasableItem by its Unibill identifier,
/// eg "com.companyname.100goldcoins".
///
/// Unibill identifiers must be globally unique and can refer to Consumable,
/// Non-Consumable and Subscription purchasable items.
///
public static PurchasableItem GetPurchasableItemById(string unibillPurchasableId);

Initiating purchases

The following methods may be used to initiate a purchase:

///
/// Initiate purchasing of the specified PurchasableItem.
///
public static void initiatePurchase (PurchasableItem purchasable);

///
/// Initiate purchasing of the PurchasableItem with specified Id.
///
public static void initiatePurchase (string purchasableId);

Retrieving transaction history

Unibill maintains its own local database of which items a user has purchased. You may query it to find out whether a user has purchased a Non-Consumable item, or how many times a user has purchased a Consumable item.

///
/// Get the number of times this PurchasableItem has been purchased.
/// Returns 0 for unpurchased items, a maximum of 1 for Non-Consumable items.
///
public static int GetPurchaseCount (PurchasableItem item) {
    if (null != biller) {
        return biller.getPurchaseHistory(item);
    }
    return 0;
}

///
/// Get the number of times the PurchasableItem with specified Id has been purchased.
/// Returns 0 for unpurchased items, a maximum of 1 for Non-Consumable items.
///
public static int GetPurchaseCount (string purchasableId) {
    if (null != biller) {
        return biller.getPurchaseHistory(purchasableId);
    }
    return 0;
}

Overriding identifiers

Google, Amazon and Apple do not allow in App purchase identifiers to be changed or reused, which is a problem if you make a mistake submitting your in app purchase metadata.

Take, for example, some gold coins which you might define with an Id of “com.companyname.100goldcoins”. If you were to define these with a ‘Non-Consumable’ type in iTunes connect you cannot later change it to ‘Consumable’. “com.companyname.100goldcoins’ will forever refer to a ‘Non-Consumable’ as far as Apple is concerned.

The only way to work around this is to define an entirely new in app purchase with a different identifier and the correct type, eg “com.companyname.100goldcoins.v2”.

You must then tell Unibill that this purchase has a different identifier on the Apple App store, by overriding the identifier in the inventory editor:

Clearing Transaction History

You can clear Unibill’s local purchase database as follows, which you will typically want to do for testing purposes.

Unibiller.clearTransactions()

Accessing purchase receipts

Purchase receipts are available on all Platforms apart from the Mac App Store, currently. Simply call Unibiller.GetAllPurchaseReceipts(); passing in the purchasable item you wish to retrieve the receipt for.

The structure of the receipt differs on each platform, for which you should consult the relevant documentation of Apple, Google et al.

The Unibill demo scene

Unibill comes with a demonstration scene at Assets/Plugins/unibill/scenes/unibillDemo. The script that powers it is at Assets/script/UnibillDemo. Exploring this scene is a good way to understand how a Unibill application fits together.

The dropdown at the top of the screen lists all of the items that have been defined using the Inventory Editor. The ‘Buy’ button triggers a purchase request for the currently selected item.

The center of the screen is used to display the purchase counts for each item, as reported by Unibill.

You can test this scene immediately on an Android device using the Amazon SDK tester. To test it using Google Play or Apple App store billing you would need to upload your purchase metadata to Google and Apple.

Google Play

Configure your Google Play public key

You must enter your application’s public key in the ‘Google Play public key’ field of the inventory editor. To get your application’s public key you must first upload a draft APK to the publisher console. You can then find it’s public key under the ‘Services & APIs’ section for the application as the ‘Base64-encoded RSA public key’.

Bulk uploading purchase metadata to Google Play

There are two ways to upload your purchase metadata to Google Play:

1. Manually

Please note – as of Unibill 1.1.4, Unibill uses Google Play billing V3. With Google Play Billing V3, all the products that you create should be of type ‘managed’. Unibill will manage consumption of items for you; if you designate an item as being of type ‘Consumable’ within the inventory editor, Unibill will automatically consume the item before registering the purchase.

For details of how to manually define your purchases follow Google’s guide.

2. Automatically, using bulk upload

Note – subscriptions cannot be uploaded using this method, and must be created manually.

Unibill automatically generates a bulk upload CSV file for use with Google Play, located at Assets/Plugins/unibill/generated/googleplay/MassImportCSV.csv

To use bulk upload there are a couple of things you will need to configure in the inventory editor:

Default locale	You must select the default locale that your application uses.
Autotranslate	If checked, your item name and description will be automatically translated into all other locales.

For full details of the bulk upload process see Google’s guide.

Testing on an Android device

Before publishing your application, you must test your in App purchases on an Android device.

Note! You must publish your App as an Alpha or Beta distribution to test In App purchasing, testing from a draft published app is no longer supported by Google.

Your Alpha or Beta APK must be published to test your IAPs. This does not mean you have to make your App publicly available.

In order to perform a complete end to end test of your In App purchases, you must do so whilst signed into a device using a test account, because developers are prohibited from purchasing things from themselves.

For purchasing to work using a test account, note the following:

• You MUST upload a signed, release version of your APK to Google Play (you do NOT have to publish it).
• The version number of the APK that you upload MUST match the version number of the APK that you test with.
• After entering your purchase metadata into the Google Play publisher console, it may take up to 24 hours before you are able to purchase your In App purchases using a test account.

Amazon Appstore

Entering your purchase metadata in the Amazon portal

You must enter your purchase metadata into the Amazon developer portal manually; there is no bulk upload facility. To do this you should follow the guide.

Testing using the Amazon test client

The Amazon SDK features an SDK tester that assists you with testing your purchases before you submit your app for review, documented here.

The SDK tester is a separate Android application that must be installed onto a test device alongside your application; you can install it from the Amazon App Store.

You must then select the ‘Use sandbox environment’ checkbox in the Unibill Inventory Editor:

When this box is ticked Unibill will automatically generate a JSON metadata file describing your purchases and write it to your device’s SD card when initialising. Be sure to untick this box before building the release version of your application.

You can use the Amazon SDK tester to thoroughly test your application, covering such scenarios as in app purchasing being disabled or otherwise unavailable. Simple launch the Amazon SDK tester application on the device to configure your test scenarios.

Apple App Store

Configuring your iOS SKU

You must enter your Application’s ‘SKU’ into the ‘iOS SKU’ field of the inventory editor, as it is configured in iTunes Connect:

Price tiers

This field is only relevant if you will be using the Application Loader and bulk upload template to enter your purchase metadata into iTunes Connect.

On iOS, prices are structured in tiers. You can set a purchasable’s tier using the slider within its ‘Apple App Store’ section.

Using the screenshot taker

On iOS, every In App purchase has to have an associated screenshot when being submitted to Apple for review. Unibill can help you prepare and submit these screenshots when using the Application Loader.

When running your application you can take a screenshot using ‘Window/Unibill/Take Screenshot“; screenshots are written to Assets/Plugins/unibill/screenshots/. The screenshot is taken of your game view; be sure you are running with a supported iTunes Connect screenshot resolution, such as 480 x 320 or 960 x 640.

You can then associate these screenshots with your purchasable items by assigning them to the ‘Screenshot’ fields in the Inventory Editor:

Uploading your purchase metadata using the Application loader

Note – subscriptions cannot be created using this method – they must be created manually in iTunes Connect.

Apple’s Application Loader lets you upload various aspects of your application to Apple, including binaries and details of your In App Purchases.

Unibill automatically generates a tab delimited bulk upload file describing your purchases, suitable for use with the Application loader. You can find this file at Assets/Plugins/unibill/generated/storekit/MassImportTemplate.

You can read the complete guide to the Application Loader here.

Please note that it may take several minutes between uploading your metadata and the metadata appearing in iTunes Connect.

Note for Unity iOS Standard users

Unity iOS standard does not support the post processing events Unibill uses to configure your xcode project automatically. You will therefore need to add the ‘Storekit.framework’ library to your XCode project, as in the following screenshot.

Testing on device

Testing on the iOS simulator is not supported.

To test on an iOS device you must be using an iTunes connect test user account; you can create these accounts in iTunes connect, then sign out of the app store on the device. You will be prompted to log in when you attempt a purchase or restore transactions.

Do not verify the email address of your test iTunes connect account! Doing so will make the account invalid for testing with the Apple sandbox environment.

If your products are being returned as unavailable for purchase, follow this checklist.

Mac App Store

Intro

Mac App Store purchasing follows a similar flow to that on iOS. You must be a registered Mac developer, create your Mac App store application in iTunes connect along with your in app purchase metadata.

You cannot use the same product identifiers for both iOS and Mac App store apps. Therefore, you will need to use the ‘override id’ functionality in the Inventory editor to specify the unique Mac App store identifiers you have entered into iTunes connect.

Testing In App Purchasing

When building a desktop Mac build you must select ‘Mac App Store validation’ within Unity’s build settings.

Once you have built your App, you must update its info.plist file with your bundle identifier and version strings. Right click on the .app file and click ‘show package contents’, locate the info.plist file and make the following modifications:

<key>CFBundleShortVersionString</key>
<string>1.0.0</string>
<key>CFBundleIdentifier</key>
<string>[Your bundle identifier eg com.outlinegames.unibill]</string>
<key>CFBundleVersion</key>
<string>1.0.0</string>

You must then sign, package and install your application. You will need to run the following commands from an OSX terminal:

codesign -f  –deep -s “3rd Party Mac Developer Application: [Your developer certificate name]” your.app

productbuild –component your.app /Applications –sign “3rd Party Mac Developer Installer: [Your installer certificate name]” your.pkg

In order to install the package correctly you must delete the unpackaged .app file before running the newly created package.

You must then launch your App from the Applications folder. The first time you do so, you will be prompted to enter your iTunes account details, for which you should enter your iTunes Connect test user account login. You will then be able to make test purchases against the sandbox environment.

You must sign, package, install your App and launch it from the Applications folder. If you do not do this you will not be able to make purchases.

You must not sign into the main App Store application using your test account or the test account will become invalid.

Windows Phone 8

Intro

There are two ways to test on Windows Phone 8; using Unibill’s inbuilt support for the WP8 Mock IAP framework, and by creating a beta distribution of your app. Both methods require a Windows Phone 8 device.

Testing

To test using the mock IAP framework, simply check the “Use mock windows phone” checkbox in the inventory editor. When using the mock framework all purchases succeed. Be sure to uncheck this when publishing.

To test your App as a beta App, create it as a Beta distribution in the windows phone dev centre. You will need to configure the App ID of the visual studio project Unity generates.

Windows 8.1

Testing

To test using the mock IAP framework, simply check the “Use mock windows 8” checkbox in the inventory editor. Be sure to uncheck this when publishing.

Samsung Apps

Setup

You must have a Samsung device with the Samsung Apps market app for testing on device!

You must register for a Samsung Apps seller account at seller.samsungapps.com, and enter your Samsung Apps Item Group in the inventory editor.

On Samsung Apps, your product identifiers are assigned for you by Samsung. You must tell Unibill what these identifiers are, by overriding the platform identifiers on samsung apps to these values, within the inventory editor:

Testing

In the inventory editor there are three modes that Unibill can run Samsung Apps with:

PRODUCTION	Purchases are made against the live Samsung Apps service.You must select this mode to publish your APK
ALWAYS_SUCCEED	Purchases will always succeed and a developer popup will show
ALWAYS_FAIL	Purchases will always fail and a developer popup will show

Support

*For all technical problems please include a trace from a device (using adb/XCode/Visual studio etc)*

Please direct all support queries to support@outlinegames.com.

Telephone support is available via Skype on request.