Offers & Items¶

Item¶

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

Parameter	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 package Merge Game, which can teach you how to do that and how to operate with complicated item systems.

Store Items¶

Store Items section contains everything you can sell directly through the in-game Shop or via Game Offers.

Screenshot

Parameter	Description
Sprite	The image associated with this Store Item. Read more about Sprites
Name	The name of the Store Item
Price	Price can be set up as product, game items, free, or amount of Ads watched
Reward	Detailed information about the items player will get
Dynamic Reward	An optional 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 pass the StoreItem document into the 'Input' port, so you can access all its parameters, and from 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.
The player is playing for 3 days and didn’t make a single purchase -> offer them a time-limited pack with a considerable discount to convert them to paying users.
The player lost 3 matches in a row -> offer them a Power Booster.
The 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

Parameter	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 will get. 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.

Game Offer events¶

All the events about Game Offers 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);
        }

        ...
    }
}

Game Offer methods¶

You can run through all active Game Offers 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 has to purchase or accept as a gift one offer in the chain 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 as a gift one offer in the chain 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.

Game Offer Group events¶

All the events about Game Offer 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);
        }

        ...
    }
}

Game Offer 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.