In-App Purchases

👍

Reminder - Keep Daily Backups

When working on a strategy game with a kit as big as the Complete Kit - always keep a working daily backup! Save yourself the trouble of rolling-back changes and losing work.

What are in-app purchases?

In-App Purchases allow your game players to spend real currency to get in-game resources such as virtual rare currency (gems, for example) or filling their resources (gold, for example). The Game Kit is setup to support In-App Purchases using either Unity IAP or your own IAP asset.

636

Click to view larger.

740

Click to view larger.

You can choose whatever currency type you want to use for your game. The demo uses two - gold and liquid mana plus one rare currency (gems), however these names, images, and all settings can be changed.

For example, some developers may want to add additional currencies in their game such as wood and stone. This can be done by duplicating existing resource references. (Make sure to keep backups!)

Where to find this IAP store menu in Unity?

Open the game scene hierarchy and locate the ScrollView in Canvas > ModalsWindows > ShopWindow > ShopGroup > StorePanel > BottomGroup > Content > Content. Look at the below screenshot.

403

UIAnchor. Click to view larger.

How can players access the In-App Purchase menu?

Either through the shop menu button as seen in the screenshots above, or by clicking the (+) button located next to the crystal stats.

298

Crystal IAP screen access button

What can you sell in your game?

The Complete Strategy Kit comes with a demo of different purchasable crystal item sets. Using these crystals, you can purchase all the special functions in the gameplay like extra in-game resources or finishing construction or troop training earlier.

Hard Currency (Crystal Gems)Game starts with 5 free crystal gems. (Can edit this number in GameManager > Stats Inspector) Must use real world currency to buy. Also awarded in random amounts (1-3 crystals) when destroying removable terrain to expand your base. See Terrain > Player Removable Objects documentation for details about the only free way gems are awarded in your game.
Soft Currency #1 (Gold)Default is Gold. The first of two currencies generated in the game. You can change this to whatever you wish.
Soft Currency #2 (Mana)Default is Liquid Mana. The second of two currencies generated in the game. You can change this to whatever you wish.
Builders (called Dobbits)Default is 1. To create two buildings at once, at least 2 builders are required. See Shop Menu > Extra Builders documentaiton for details

You could technically sell more, as the full source code is included so developers can edit the game to sell any sort of additional bonuses or sets. What we'll talk about in the rest of this documentation page is what's already included, and prescripted for you.

Rare Gem In-App Purchases ScriptableObject (StoreCategory.asset)

Inside Assets/CityBuildingKit/Resources/Assets/StoreCategory.asset you'll find the text behind the IAP store menu. To customize any item in the menu, you simply change the values in this SO(ScriptableObject) file, save, and run the Game scene.

145

XML Example image

For the above example image of a Handful of gems seen in the kit's UI, below is the SO behind this seen in StoreCategory.asset:

403

As you can see above, customizing these values is simple. Specify the name, a quantity, the price of your rare currency, etc...

IAP Store Menu Initization

The Scripts/Menus/Shop/ShopController.cs controls everything in the Shop menu. For example, the above data from the SO file is loaded with OnStoreCategoryHandler()

public void OnStoreCategoryHandler(int categoryIndex)
{
    OnOpenShop();
    IEnumerable<DrawCategoryData> drawCategoryData;
    object category;
    switch (categoryIndex)
    {
        case 0:
          category = ShopData.Instance.StoreCategoryData;
          drawCategoryData = ((StoreCategoryData) 			category).Category.Select(item =>
                                                                                  new DrawCategoryData {BaseItemData = item, Id = item, 	Name = item}); 
          DrawCategory(drawCategoryData, ShopCategoryType.Store);
          break;
                
                
.  .  .

After the SO data is loaded from - the interface is updated with InitUIStoreItems() (Store.cs) that sets each of the rare currency items for sale in the menu with the data from SO.

public void InitUIStoreItems()
    {
        UpdateResources();
        UpdateUI(6, Stats.Instance.maxGold, existingGold, 4, false);
        UpdateUI(7, Stats.Instance.maxGold, existingGold, 2, false);
        UpdateUI(8, Stats.Instance.maxGold, existingGold, 1, false);
        UpdateUI(9, Stats.Instance.maxMana, existingMana, 4, false);
        UpdateUI(10, Stats.Instance.maxMana, existingMana, 2, false);
        UpdateUI(11, Stats.Instance.maxMana, existingMana, 1, false);
    }

Where to integrate your in-app purchase solution:

By default, the kit is setup to initiate purchases (menu and scripting provided). Purchases are delivered instantaneously for testing. The following excerpt from Scripts/Menus/Shop/Store.cs. shows where you can initiate your IAP scripting:

// Please see:
// https://bitbucket.org/Unity-Technologies/unity-iap-samples
//
	public void BuyStoreItem(DrawCategoryData data)
	{
		var itemData = data.BaseItemData as StoreCategory;
		if (itemData == null)
		{
			return;
		}

		switch (itemData.purchasableResource)
		{
				case GameResourceType.Crystal:
					BuyCrystal(itemData);
					break;
				case GameResourceType.Gold:
                    if (itemData.GetId() == 6)
                    {
                        goldSelection = 0;
                    }
                    else if (itemData.GetId() == 7)
                    {
                        goldSelection = 1;
                    }
                    else if (itemData.GetId() == 8)
                    {
                        goldSelection = 2;
                    }
                UpdateResources ();
					BuyGold(itemData);
                    break;
				case GameResourceType.Mana:
                    if (itemData.GetId() == 9)
                    {
                        manaSelection = 0;
                    }
                    else if (itemData.GetId() == 10)
                    {
                        manaSelection = 1;
                    }
                    else if (itemData.GetId() == 11)
                    {
                        manaSelection = 2;
                    }
                UpdateResources ();
					BuyMana(itemData);
                    break;
		}
		
		Stats.Instance.UpdateUI();
		Stats.Instance.UpdateCreatorMenus();
	}

In-Game Resource Filling

In addition to purchasing rare currencies like gems with real currency - you can offer the option for game users to fill their resources with gems. These are not paid with real currency but instead gems so you can change the values dynamically.

Here's a screenshot from the IAP store menu to fill in-game currency #1 (gold, in this case) by 25%, 50%, and 100%.

443

IAP to fill player resources

to

Unity In-App Purchase Sample Code

For actually processing real money transactions you'll need an Apple Developer account or Google Publisher account. Then, use Unity's built-in IAP solution for connecting and processing transactions. Reference code and documentation is available here: https://bitbucket.org/Unity-Technologies/unity-iap-samples

Initiate the purchase in the functions listed above.

Video: Unity In-App Purchasing Demonstration

Other Recommended IAP Assets?

If you're looking to integrate IAP into your game, we recommend using the Unity IAP demo source code mentioned above (available here) -- but otherwise if you need an alternative - the Simple IAP Unity asset available for download from the Unity Asset Store is a good second choice.

Where can I edit the crystal price for unit training time?

The following excerpt from Scripts/Units/MenuUnit.cs shows the game settings for how the total price is computed in crystals based on the total minutes remaining in the production queue.

435

Unit crystal finish now cost. Click to view closer.

For example, if time remaining is less than 30 minutes then it only costs one crystal gem to finish production of all units. Once the total time remaining exceeds 30 minutes but is less than 60 minutes the price increases to 3 crystal gems, and so on.

You can adjust these settings in MenuUnit.cs. Look for the following source code:

if (timeRemaining >= 4320)	priceInCrystals = 150;
		else if (timeRemaining >= 2880)	priceInCrystals = 70;
		else if (timeRemaining >= 1440)	priceInCrystals = 45;
		else if (timeRemaining >= 600)	priceInCrystals = 30;
		else if (timeRemaining >= 180)	priceInCrystals = 15;
		else if (timeRemaining >= 60)	priceInCrystals = 7;
		else if (timeRemaining >= 30)	priceInCrystals = 3;
		else if (timeRemaining >= 0)	priceInCrystals = 1;

Where can I edit the crystal price for building construction time?

Like the unit training excerpt above, another way to use crystal gems is to accelerate construction times rather than wait the time remaining. Pressing the crystal button finishes the construction instantly.

570

Building crystal finish now cost. Click to view closer.

Look at the Scripts/Creators/ConstructionSelector.cs UpdatePrice function which updates the crystal price label on construction projects.

// Scripts/Creators/ConstructionSelector.cs
//update the price label on the button, based on remaining time		

private void UpdatePrice(int remainingTime)					
{
	/*
  Summary of Gem Prices
  
  Minute Range		Cost in Gems
	0		-	30				1
	30	-	60				3
	60	-	180				7
	180	-	600				15
	600	-	1440			30
	1440-	2880			45
	2880-	4320			70
	4320+						150
	 */

	if (remainingTime >= 4320) { priceno = 150; }
	else if (remainingTime >= 2880) { priceno = 70; }
	else if (remainingTime >= 1440) { priceno = 45;	}
	else if (remainingTime >= 600)	{ priceno = 30;	}
	else if (remainingTime >= 180) { priceno = 15; }
	else if (remainingTime >= 60) { priceno = 7; }
	else if (remainingTime >= 30) {	priceno = 3; }
	else if(remainingTime >= 0) { priceno = 1; }

	((tk2dTextMesh)Price.GetComponent("tk2dTextMesh")).text = priceno.ToString();
}

Can I also sell ad unlocks as an In-App Purchase?

Yes, you can sell pay for an ad-free game experience options. A good example to look at is the fill resource options in the In-App Purchase store and the Store.cs script.

The easiest way to do this is to setup ads in your application that display only if a new Stats variable like AdFree boolean is set to false.

Add the Pay to Unlock item into the In-App Purchase store menu with a crystal price like how the refill resources use crystals to change the resource stats. Then when the button is triggered, deduct the crystal currency and update the Stats AdFree boolean to true. The Stats are carried between save and loads so your players will never see the ads again.

675

Screenshot example from other iPhone games

Before starting to add new features like this - please get comfortable with the scripting first. Read the functions in the Store.cs script and use Ctrl+F in the Scripts folder to locate how functions work between scripts. The kit is a huge package of interconnected features and scripts, so it's better to get comfortable first with the scripting before adding new features that might affect other gameplay elements.