Skip to content

Quick Start Guide: Unity

Install SDK

Balancy is available on OpenUPM.

  1. Open Unity Package Manager (Window ► Package Manager).
  2. Click the "+" button.
  3. Select "Add package from git URL".
  4. Enter: https://github.com/balancy-liveops/plugin_cpp_unity.git

Set Up the Project and Scene

  1. Open config and authenticate: Tools ► Balancy ► Config:

    Balancy Config

  2. Once authenticated, select your game and branch.

  3. Add Balancy Prefabs by clicking on the buttons Create Balancy Launcher... and Add Balancy UI in the Scene. This will add the necessary components to your Scene.

    Balancy Config Balancy Config Balancy Config

  4. Make sure there is an Event System on the scene to catch clicks. If you don't have it — right click in the hierarchy: UI ► Event System.

  5. Launch the scene and you should see the Balancy UI with active offers and events from the Starter Kit.

    Balancy UI

Initialize from Code

The steps above use the built-in Balancy Launcher prefab, which handles initialization automatically. If you prefer to initialize Balancy from your own code (recommended for production), here's how:

using Balancy;
using Balancy.Data;

public class BalancyInit : MonoBehaviour
{
    void Start()
    {
        var config = new AppConfig
        {
            ApiGameId = "<YOUR_GAME_ID>",
            PublicKey = "<YOUR_PUBLIC_KEY>",
            Environment = Constants.Environment.Development,
            OnProgressUpdateCallback = (fileName, progress) =>
            {
                Debug.Log($"Loading {(int)(progress * 100)}% - {fileName}");
            }
        };

        // Subscribe to callbacks BEFORE calling Init
        SubscribeToCallbacks();

        Balancy.Main.Init(config);
    }

    void SubscribeToCallbacks()
    {
        // Mandatory: fires multiple times during initialization.
        // Start the game on the FIRST callback (local cached data).
        // Refresh when cloud sync completes with the latest data.
        Balancy.Callbacks.OnDataUpdated += status =>
        {
            Debug.Log($"Data updated — Cloud: {status.IsCloudSynced}, CMS: {status.IsCMSUpdated}");

            // Always refresh game data on every callback
            ListActiveEvents();

            if (status.IsCloudSynced)
            {
                // Second callback - cloud sync complete
                if (status.IsCMSUpdated || status.IsProfileUpdated)
                {
                    Debug.Log("[Balancy] Cloud data synchronized!");
                    //OnBalancyRefreshed();
                }
            }
            else
            {
                // First callback - local data ready
                Debug.Log("[Balancy] Local data ready - Game can start!");
                //OnBalancyReady();
            }
        };

        // LiveOps: event activated
        Balancy.Callbacks.OnNewEventActivated += eventInfo =>
            Debug.Log($"Event started: {eventInfo?.GameEvent?.Name}");

        // LiveOps: event deactivated
        Balancy.Callbacks.OnEventDeactivated += eventInfo =>
            Debug.Log($"Event ended: {eventInfo?.GameEvent?.Name}");

        // LiveOps: offer activated
        Balancy.Callbacks.OnNewOfferActivated += offerInfo =>
            Debug.Log($"Offer started: {offerInfo?.GameOffer?.Name}");

        // LiveOps: offer deactivated
        Balancy.Callbacks.OnOfferDeactivated += (offerInfo, wasPurchased) =>
            Debug.Log($"Offer ended: {offerInfo?.GameOffer?.Name}, purchased: {wasPurchased}");

        // Error handling
        Balancy.Callbacks.OnAuthFailed += status =>
            Debug.LogError($"Auth failed: {status.Message}");
    }

    void ListActiveEvents()
    {
        var smartInfo = Balancy.Profiles.System.SmartInfo;

        // Active Game Events
        foreach (var eventInfo in smartInfo.GameEvents)
        {
            var secondsLeft = eventInfo.GetSecondsLeftBeforeDeactivation();
            Debug.Log($"Active event: {eventInfo.GameEvent?.Name} — {secondsLeft}s remaining");
        }

        // Active Offers
        foreach (var offerInfo in smartInfo.GameOffers)
        {
            Debug.Log($"Active offer: {offerInfo.GameOffer?.Name}");
        }
    }
}

You can find YOUR_GAME_ID and YOUR_PUBLIC_KEY in the Balancy dashboard under your game's settings.

Generate Code (Optional)

If you want typed access to your templates (instead of generic SmartObjects types), generate code:

  1. In Unity, select Tools ► Balancy ► Config.
  2. Click Generate Code.
  3. Generated classes will be placed in Assets/Balancy/AutoGeneratedCode.

This lets you use your own template types like Balancy.CMS.GetModels<YourCustomTemplate>(true) instead of generic types.

Next Steps