Offers & Items¶

Item¶

An Item Document represents one entity within your game. It can be a sword, shield, wood, stone - anything from your game.

Name	Description
Name	The name of the Item
MaxStack	The maximum amount of Item, which can be put in one Slot

We want to keep this structure as universal as possible. Thus we only added a few parameters. However, your game needs much more parameters than we provide. Just create a new Template inherited from Item and add as many parameters as you need. We have a great template Merge Game, which can teach you how to do that and how to operate with complicated Item Systems.

Store Items¶

StoreItems section holds everything you can sell directly through the in-game Shop or via Game Offers.

Screenshot

Name	Description
Sprite	The image associated with this Store Item. Read more about Sprites
Name	The name of the Store Item
Price	Price can be in Hard Currency, Soft Currency, or watching Ads
Reward	Detailed information about the items player gets
Dynamic Reward	A Script, which is used to calculate the dynamic reward at runtime

var reward = storeItem.Reward;//You can read the static Reward

storeItem.GetDynamicReward(dynamicReward => {
    //You can read the dynamic Reward, the method is asynchronous
});

When making Script with Dynamic reward, it's important to mention that such Script has to have 2 ports:

Input port called 'Input', type 'Document'
Output port called 'Output', type 'Document'

The naming is super important if you want it to work. Balancy will path the StoreItem document into the 'Input' port, so you can access all its parameters, and in the 'Output' port Balancy expects to receive the Reward document.

Game Offers¶

Game offers (aka Personalised Offers) can make your company the most money and bring your customers the most significant value. Besides making money, they can also serve other purposes, like pushing players to make their first purchase or retaining a player who is about to churn.

New player completes the first level -> offer them a Starter Pack.
Player is playing for 3 days and doesn’t make a single purchase-> Offer them a time-limited pack with a considerable discount to convert them to paying users.
Player lost 3 matches in a row -> Offer them a Power Booster.
Player pays a lot -> hide all cheap offers and show more expensive ones.

Such a list is limited only by your imagination. You shall be testing a lot of such offers during LiveOps. Personalised offers are tough to implement and require much knowledge from the team, but this is the gaming industry's future.

Thanks to Balancy, you already have all the tools you need to start your experiments.

Screenshot

Name	Description
Sprite	The image associated with this Offer. Read more about Sprites
Name	The name of the Offer
Duration	How long will the offer be available to a user after the initial offering? (In seconds)
Store Item	Defines what you are selling in this offer. Read more about Store Item
Description	Detailed information about the offer
Reward	Detailed information about the items player gets. You can edit them here or on a separate page Store Item
Limit	Maximum amount of items the player can get
Wait for activation	Set this value to True if you don't want to start the timer manually. For example, you want to make sure the player saw this offer first.

GameOffer events¶

All the events about GameOffers are delivered to ISmartObjectsEvents. You can find more information here.

namespace Balancy
{
    public class SmartObjectsEventsExample : ISmartObjectsEvents
    {
        ...

        public void OnNewOfferActivated(OfferInfo offerInfo)
        {
            Debug.Log("=> OnNewOfferActivated: " + offerInfo?.GameOffer?.Name + " ; Price = " + offerInfo?.PriceUSD + " ; Discount = " + offerInfo?.Discount);
        }

        public void OnOfferDeactivated(OfferInfo offerInfo, bool wasPurchased)
        {
            Debug.Log("=> OnOfferDeactivated: " + offerInfo?.GameOffer?.Name + " ; wasPurchased = " + wasPurchased);
        }

        ...
    }
}

GameOffer methods¶

You can run through all active GameOffers and access different data:

foreach (var offerInfo in Balancy.LiveOps.GameOffers.GetActiveOffers())
{
    var offerDiscount = offerInfo.Discount;
    var offerStatus = offerInfo.Status;
    var theEventActivatedThisOffer = offerInfo.GameEvent;
    var balancyOfferData = offerInfo.GameOffer;//Access to the name, icon, price, etc...
    var productIdToPurchase = offerInfo.ProductId;
    var purchasesCount = offerInfo.PurchasesCount;//It's relevant for offers, which can be purchased multiply times
    var startTime = offerInfo.StartTime;//Timestamp when the offer was activated
    var canPurchase = offerInfo.CanPurchaseAgain;
    var timeLeft = offerInfo.GetSecondsLeftBeforeDeactivation();//Timeleft before offer will be deactivated
    offerInfo.Activate();//Activates offer with offerStatus = OfferStatus.Waiting. Only relevat for GameOffers with 'Wait for activation' flag set TRUE

    //To purchase offer use this method
    Balancy.LiveOps.GameOffers.PurchaseOffer(offerInfo, response =>
    {
        Debug.Log($"PurchaseOffer {response.Success}");
    });

    //If you have your own methods for purchasing, use one of those methods:
    //Balancy.LiveOps.GameOffers.OfferWasPurchased(...);//Balancy validates the receipt, protecting you from the fraud
    //Balancy.LiveOps.GameOffers.OfferWasPurchasedAndValidated(...);//Balancy ignores the receipt
}

Offer Groups¶

There are several types of Offer Groups, and the most popular is the Chain Deal - a series of offers presented to a user in a sequence. A player must purchase or accept one offer in the chain as a gift before moving on to the next one. Offers in a chain deal can be versatile: from currencies and in-game items to bundles and loot boxes.

Type	Description
Unlimited Purchases	Players can purchase any Store Item in such group without limits while the Offer Group is active.
Chain Deals	A player has to purchase or accept one offer in the chain as a gift before moving on to the next one.
Only One Purchase	A player can purchase only one Store Item from the available list. After purchase, the Offer Group disappears.
Purchase Each Offer Once	A player can purchase all the Store Items in a random order, but only once.
Wait for activation	Set this value to True if you don't want to start the timer manually. For example, you want to make sure the player saw this offer first.

GameOffer Group events¶

All the events about GameOffer Groups are delivered to ISmartObjectsEvents. You can find more information here.

namespace Balancy
{
    public class SmartObjectsEventsExample : ISmartObjectsEvents
    {
        ...

        public void OnNewOfferGroupActivated(OfferGroupInfo offerInfo)
        {
            Debug.Log("=> OnNewOfferGroupActivated: " + offerInfo?.GameOfferGroup?.Name);
        }

        public void OnOfferGroupDeactivated(OfferGroupInfo offerInfo, bool wasPurchased)
        {
            Debug.Log("=> OnOfferGroupDeactivated: " + offerInfo?.GameOfferGroup?.Name + " ; wasPurchased = " + wasPurchased);
        }

        ...
    }
}

GameOffer Group methods¶

You can run through all active GameOffer Groups and access different data:

foreach (var offerInfo in Balancy.LiveOps.GameOffers.GetActiveOfferGroups())
{
    var offerStatus = offerInfo.Status;
    var theEventActivatedThisOffer = offerInfo.GameEvent;
    var balancyOfferData = offerInfo.GameOfferGroup;//Access to name, icon, price, type, etc...

    //Run through all the StoreItems in this Group Offer
    foreach (var storeItem in offerInfo.GameOfferGroup.StoreItems)
    {
        var canPurchaseStoreItem = offerInfo.CanPurchase(storeItem);
    }

    var startTime = offerInfo.StartTime;//Timestamp when the offer was activated
    var canPurchase = offerInfo.CanPurchaseAgain;
    var timeLeft = offerInfo.GetSecondsLeftBeforeDeactivation();//Timeleft before offer will be deactivated
    offerInfo.Activate();//Activates offer with offerStatus = OfferStatus.Waiting. Only relevat for GameOffers with 'Wait for activation' flag set TRUE

    //To purchase store item at index i of this offer group use this method:
    Balancy.LiveOps.GameOffers.PurchaseOffer(offerInfo, offerInfo.GameOfferGroup.StoreItems[i], response =>
    {
        Debug.Log($"PurchaseOffer {response.Success}");
    });

    //If you have your own methods for purchasing, use one of those methods:
    //Balancy.LiveOps.GameOffers.OfferWasPurchased(...);//Balancy validates the receipt, protecting you from the fraud
    //Balancy.LiveOps.GameOffers.OfferWasPurchasedAndValidated(...);//Balancy ignores the receipt
}

Extension¶

If your game requires additional parameters, you should inherit a new Template from 🎁 Game Offer and add as many parameters as needed. Screenshot

When you create a new Offer, make sure to select the new Template you just created, and then you'll get something like this: Screenshot

You can use the same trick for any structure in Balancy: GameOffer, GameOfferGroup, StoreItem, or Item.

Section for programmers¶

You can request all active offers. Call this method only after OnSmartObjectsInitialized is invoked.

var activeOffers = Balancy.LiveOps.GameOffers.GetActiveOffers();
var activeOfferGroups = Balancy.LiveOps.GameOffers.GetActiveOfferGroups();

Visit the Payments section to learn how to purchase Offers and Store Items.

Visit the Programmers Section and learn how to subscribe for important events.