Migrating from the Old Balancy Unity Plugin¶

This guide walks you through upgrading from the old Balancy Unity SDK to the new one, step by step. If you already have the old plugin integrated and working, follow these steps to switch over.

Why Migrate?¶

The new SDK is a complete rewrite in C++, bringing major improvements across the board:

Performance & Architecture¶

Significantly faster — the new SDK uses less memory and CPU, resulting in a smoother experience for your players.
Cross-platform core — the C++ core runs natively on every platform, so you get consistent behavior everywhere.
Simpler API — the SDK is easier to integrate, with a unified callback system instead of scattered listeners and event interfaces.
Offline-first — the game starts instantly from cached data, with cloud sync happening in the background.

New Features (New SDK Only)¶

UI Builder — a visual drag-and-drop tool for creating game UI directly in the Balancy dashboard, with a prefab & component system similar to Unity's GameObject/MonoBehaviour pattern. Build shops, offers, season passes, and more without writing native UI code. See the UI Builder documentation for details.
LiveOps Starter Kit — a library of production-ready templates inspired by top-grossing games, including Season Pass, Chain Deals, mini-games, winstreak events, racing challenges, and a full Game Shop. Install the package and customize to your needs. See the LiveOps Starter Kit documentation for details.
AI Assistant — coming soon. An AI assistant trained on the new SDK that can help you create and manage game content, events, and offers through natural language.

Support & Updates¶

The old SDK is in maintenance mode — it receives critical bug fixes only. All new features, improvements, and active development happen exclusively on the new SDK. Migrating now means you'll benefit from ongoing updates and new capabilities as they ship.

Before You Start¶

Work in a separate Git branch. The migration will temporarily break compilation, so keep your main branch clean until everything is tested and working.

git checkout -b balancy-migration

Step 1: Install the New Plugin¶

Add the new Balancy package via Unity Package Manager:

Open Window ► Package Manager.
Click the "+" button.
Select Add package from git URL.
Enter: https://github.com/balancy-liveops/plugin_cpp_unity.git

Do not remove the old plugin yet — you'll need it as a reference while updating your code.

Step 2: Remove the Old Plugin¶

Once the new plugin is installed, remove the old Balancy plugin from your project. This will cause compilation errors — that's expected. You'll fix them in the next steps.

Step 3: Re-generate Code¶

The new SDK generates code with an updated structure. You need to regenerate it:

Open Tools ► Balancy ► Config.
Authenticate with your Balancy account.
Select your game and branch.
Click Generate Code.
Generated classes will appear in Assets/Balancy/AutoGeneratedCode.

After removing the old plugin, your project may have too many errors for Unity to compile, which means the Balancy menu won't appear. In that case:

Create a temporary empty Unity project.
Add the new Balancy plugin to it (same git URL as Step 1).
Open Tools ► Balancy ► Config, authenticate, select your game.
Click Generate Code.
Copy the entire Assets/Balancy/AutoGeneratedCode folder from the temporary project into your main project, replacing the old generated code.

This will resolve most compilation errors related to generated types.

Step 4: Update Data Access¶

The old SDK accessed data through DataEditor and DataManager. The new SDK uses Balancy.CMS.

Old SDK¶

// Accessing lists of documents
var items = Balancy.DataManager.SmartObjects.Items;
var storeItems = Balancy.DataManager.SmartObjects.StoreItems;

// Accessing custom templates
var myItems = Balancy.DataEditor.MyItems;

// Accessing singletons
var gameConfig = Balancy.DataEditor.GameConfig.Get();

New SDK¶

// Accessing lists of documents
var items = Balancy.CMS.GetModels<Balancy.Models.SmartObjects.Item>(false);
var storeItems = Balancy.CMS.GetModels<Balancy.Models.SmartObjects.StoreItem>(false);

// Accessing custom templates
var myItems = Balancy.CMS.GetModels<Balancy.Models.MyItem>(false);

// Accessing a document by ID
var item = Balancy.CMS.GetModelByUnnyId<Balancy.Models.SmartObjects.Item>("26");

The includeChildren parameter (second argument) controls whether child templates are included. Set to true if you want documents from inherited templates as well.

Search your codebase for all occurrences of DataEditor and DataManager and replace them with the corresponding Balancy.CMS calls.

Step 5: Update Profile Access¶

Old SDK¶

Balancy.Data.SmartStorage.LoadSmartObject<Profile>(responseData =>
{
    var profile = responseData.Data;
});

New SDK¶

var profile = Balancy.Profiles.Get<Profile>();

The system profile is accessed via Balancy.Profiles.System.

Step 6: Update Initialization¶

This is the most important change. The old SDK required managing multiple callbacks:

Old SDK¶

var config = new AppConfig
{
    ApiGameId = "<GAME_ID>",
    PublicKey = "<PUBLIC_KEY>",
    Environment = Constants.Environment.Development,
    OnInitProgress = progress =>
    {
        // Handle different init stages
    },
    OnReadyCallback = response =>
    {
        // Everything is ready, cloud synced
    }
};
Balancy.Main.Init(config);

// Plus: ISmartObjectsEvents.OnSmartObjectsInitialized()
// Plus: ExternalEvents.RegisterSmartObjectsListener(...)

New SDK¶

var config = new AppConfig
{
    ApiGameId = "<GAME_ID>",
    PublicKey = "<PUBLIC_KEY>",
    Environment = Constants.Environment.Development
};

Balancy.Callbacks.OnDataUpdated += status =>
{
    // Always refresh your game data here
    RefreshGameData();

    if (status.IsCloudSynced)
    {
        if (status.IsCMSUpdated || status.IsProfileUpdated)
        {
            // Cloud data changed — update UI if needed
            Debug.Log("[Balancy] Cloud data synchronized!");
        }
    }
    else
    {
        // First callback — local data ready, start the game
        Debug.Log("[Balancy] Local data ready — game can start!");
    }
};

Balancy.Main.Init(config);

Key differences:

No more OnInitProgress, OnReadyCallback, or ISmartObjectsEvents — everything goes through OnDataUpdated.
No more ExternalEvents.RegisterSmartObjectsListener(...).
OnDataUpdated fires multiple times: first with local/cached data, then again when cloud sync completes.

Step 7: Update LiveOps Callbacks¶

If you were using ISmartObjectsEvents, replace those methods with the new callback system:

Old SDK¶

public class SmartObjectsEventsExample : ISmartObjectsEvents
{
    public void OnSmartObjectsInitialized() { ... }
    public void OnNewEventActivated(...) { ... }
    public void OnEventDeactivated(...) { ... }
    public void OnNewOfferActivated(...) { ... }
    // etc.
}

ExternalEvents.RegisterSmartObjectsListener(new SmartObjectsEventsExample());

New SDK¶

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

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

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

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

Subscribe to these callbacks before calling Balancy.Main.Init(config).

Find the list of all callbacks here

Step 8: Understand the Offline-First Model¶

The new SDK always starts in offline mode first. This is a fundamental change from the old SDK.

How it works¶

On launch, the SDK loads locally cached data (configs + profile) and fires OnDataUpdated immediately.
Your game should start right away using this local data — don't wait for cloud sync.
In the background, the SDK checks the cloud for updates. If anything changed, it fires OnDataUpdated again with IsCloudSynced = true.
At that point, you can refresh your UI to reflect any changes.

Why this is the right approach¶

In practice, most of the player sessions will have no changes since the last launch. Players open your game far more often than you push updates. Starting from cached data means:

Instant game start — no loading screen waiting for network.
Works offline — the game runs perfectly without internet.
Seamless updates — when you do push changes, they arrive in the background and you get a callback.

LaunchType is no longer relevant¶

The old SDK had a LaunchType parameter in AppConfig that controlled whether to use local data, cloud data, or both. You no longer need this parameter. The new SDK always starts with local data and syncs with the cloud automatically. Simply remove any LaunchType configuration from your code.

Step 9: Other Changes¶

Game Shop¶

You can now have multiple shops active at the same time. The access pattern changed — see the Shop documentation for details.

Daily Bonus¶

Like shops, you can now have multiple daily bonuses active at the same time. Daily Bonus now works directly with the inventory system — rewards are automatically added to the player's inventory upon claiming. See the Daily Bonus documentation for details.

Step 10: Test Everything¶

Before merging your migration branch:

Build and run — verify no compilation errors remain.
Check initialization — confirm OnDataUpdated fires and your game starts correctly.
Verify data access — make sure all your CMS data loads properly.
Test LiveOps — confirm events, offers, and callbacks work as expected.
Test offline — disconnect from the internet and verify the game starts from cached data.
Test updates — make a change in the Balancy dashboard, relaunch, and verify the update arrives via OnDataUpdated with IsCloudSynced = true.

Once everything works, merge into your main branch:

git checkout main
git merge balancy-migration

Need Help?¶

If you run into issues during migration, we're happy to help. Schedule a call with the Balancy team and we'll walk through the migration together.

Migrating from the Old Balancy Unity Plugin¶

Why Migrate?¶

Performance & Architecture¶

New Features (New SDK Only)¶

Support & Updates¶

Before You Start¶

Step 1: Install the New Plugin¶

Step 2: Remove the Old Plugin¶

Step 3: Re-generate Code¶

If Unity Won't Compile (Code Generation Menu Unavailable)¶

Step 4: Update Data Access¶

Old SDK¶

New SDK¶

Step 5: Update Profile Access¶

Old SDK¶

New SDK¶

Step 6: Update Initialization¶

Old SDK¶

New SDK¶

Step 7: Update LiveOps Callbacks¶

Old SDK¶

New SDK¶

Step 8: Understand the Offline-First Model¶

How it works¶

Why this is the right approach¶

LaunchType is no longer relevant¶

Step 9: Other Changes¶

Game Shop¶

Daily Bonus¶

Step 10: Test Everything¶

Need Help?¶