New SDK Preview

This section is a preview of the new SDK. The new SDK is still in development, and we are actively working on improving it. We value your feedback, so if you have any questions or suggestions, please reach out to us. If you are not using the new SDK, please refer to another documentation section.

API¶

After Balancy is initialized, a wide range of functions and methods are available to interact with the Balancy SDK.

Balancy Status¶

The GetStatus method returns the current status of the Balancy SDK.

C#TypeScript

var status = Balancy.API.GetStatus();

const status = Balancy.API.getStatus();

Don't cache the status object because it can change after each call.

Parameter	Description
BranchName	The name of the branch the SDK is connected to.
Deploy	The unique number of the Deploy. You can the version of configs, that's being used
LastCloudConfigsUpdate	The unix time (seconds) of the last successful synchronization of the game configs during this session.
ServerTime	The server time in seconds since 1970.
GameTime	The game time in seconds since 1970. The Game time is used for all the conditions and can be changed in the Balancy Dashboard.
ServerTimeMs	The server time in milliseconds.
GameTimeMs	The game time in milliseconds.

Ads¶

You can use Balancy SDK to track Ad revenue, this data can later be used for segmentation.

C#TypeScript

Balancy.API.TrackAdRevenue(<AdType>, <revenue>, <placement>);

Balancy.API.trackAdRevenue(<AdType>, <revenue>, <placement>);

Purchasing¶

Balancy provides robust purchasing methods that integrate seamlessly with the inventory system. After a successful purchase:

Items are automatically added to the inventory.
If the price is in soft currency, the amount is deducted from the inventory.
If there are insufficient items in the inventory, the purchase still proceeds because using Balancy’s inventory is optional. However, the inventory amount can go negative in such cases.

For Unity there are 2 ways to work with payments, we recommend using the High Level one. For Type Script you can only use Low Level for now only.

High Level (Recommended for Unity)¶

Make sure you have installed the Unity's In App Purchasing package version 4.12+.

After you complete the setup below, you can use the following methods to make purchases:

Balancy.API.InitPurchase(storeItem, (success, error) => Debug.Log("Purchase complete: " + success + " error = " + error));
Balancy.API.InitPurchaseOffer(offerInfo, (success, error) => Debug.Log("Purchase complete: " + success + " error = " + error));
Balancy.API.InitPurchaseOffer(offerGroupInfo, storeItem, (success, error) => Debug.Log("Purchase complete: " + success + " error = " + error));

Using Balancy Package¶

Install the latest Balancy Payments package:
To avoid conflicts, make sure you are not invoking UnityPurchasing.Initialize in your code.

How it works under the hood:

When Balancy.Callbacks.OnDataUpdated is invoked, Balancy automatically grabs all Products you defined in the Balancy dashboard and calls UnityPurchasing.Initialize with them.
After you Init the purchase using one of the methods above, Balancy automatically defined the Price type, does the required checks and invokes all the required methods.
The purchase result is returned via the callback you provided.

Balancy also automatically caches the purchase receipt, in case the app crashes or looses connection during the purchase process. The receipt is sent to the server when the app reconnects. For this case, please subscribe to the following callbacks to be notified:

Balancy.Callbacks.OnHardPurchasedStoreItem += (paymentInfo, storeItem) => Debug.Log(" => Balancy.OnHardPurchasedStoreItem: " + storeItem?.Name + " UnnyId = " + storeItem?.UnnyId);
Balancy.Callbacks.OnHardPurchasedOffer += (paymentInfo, gameOffer) => Debug.Log(" => Balancy.OnHardPurchasedOffer: " + gameOffer?.Name + " UnnyId = " + gameOffer?.UnnyId);
Balancy.Callbacks.OnHardPurchasedOfferGroup += (paymentInfo, gameOfferGroup, storeItem) => Debug.Log(" => Balancy.OnHardPurchasedOfferGroup: " + gameOfferGroup?.Name + " UnnyId = " + gameOfferGroup?.UnnyId);

Using custom UnityPurchasing¶

In the case you are using your own implementation of UnityPurchasing, you have to connect with Balancy SDK:

Let Balancy know, which method to use for hard purchases:

Balancy.Actions.Purchasing.SetHardPurchaseCallback(TryToHardPurchase);

Balancy SDK will invoke the TryToHardPurchase method inside of the Balancy.API.Init<> method if case the price is in hard currency.

Once the purchase is completed, you have to call the following method:

Balancy.API.FinalizedHardPurchase(Balancy.Actions.PurchaseResult.Success, productInfo, purchaseInfo, (validationSuccess, removeFromPending) =>
{
    Debug.Log("Validation result = " + validationSuccess);
});

Make sure to define all the parameters of purchaseInfo object, otherwise the purchase will be marked as failed.

public class PurchaseInfo
{
   public string Receipt { get; set; }
   public string ProductId { get; set; }
   public string TransactionId { get; set; }
   public string ErrorMessage { get; set; }
   public string CurrencyCode { get; set; }
   public float Price { get; set; }
}

If something goes wrong, you can call the following method to notify Balancy about the error:

Balancy.API.FinalizedHardPurchase(Actions.PurchaseResult.Failed, productInfo, new Actions.PurchaseInfo
{
    ErrorMessage = "Product ID is null or empty"
}, null);

In both methods productInfo is the product you are trying to purchase. It was sent to you via the SetHardPurchaseCallback callback.

Low Level (Recommended for TypeScript)¶

Soft Purchasing¶

Soft purchasing methods return a bool value indicating whether the purchase was successful.

C#TypeScript

Balancy.API.SoftPurchaseStoreItem(storeItem);
Balancy.API.SoftPurchaseGameOffer(offerInfo);
Balancy.API.SoftPurchaseGameOfferGroup(offerGroupInfo, storeItem);

Balancy.API.softPurchaseStoreItem(storeItem);
Balancy.API.softPurchaseGameOffer(offerInfo);
Balancy.API.softPurchaseGameOfferGroup(offerGroupInfo, storeItem);

Hard Purchasing¶

Hard purchasing methods require a PaymentInfo object containing payment details. This object is used for validation and segmentation purposes. The purchase result is returned via a callback.

C#TypeScript

var paymentInfo = new Balancy.Core.PaymentInfo
{
    Receipt = unityProduct.receipt,
    Price = (float)unityProduct.metadata.localizedPrice,
    Currency = unityProduct.metadata.isoCurrencyCode,
    ProductId = unityProduct.definition.id,
    OrderId = unityProduct.transactionID
};

void PurchaseCompleted(Balancy.Core.Responses.PurchaseProductResponseData responseData) {
    Debug.Log("Success = " + responseData.Success);
    Debug.Log("ErrorCode = " + responseData.ErrorCode);
    Debug.Log("ErrorMessage = " + responseData.ErrorMessage);
    Debug.Log("ProductId = " + responseData.ProductId);
}

Balancy.API.HardPurchaseStoreItem(storeItem, paymentInfo, PurchaseCompleted, requireValidation);
Balancy.API.HardPurchaseGameOffer(offerInfo, paymentInfo, PurchaseCompleted, requireValidation);
Balancy.API.HardPurchaseGameOfferGroup(offerGroupInfo, storeItem, paymentInfo, PurchaseCompleted, requireValidation);

import {Balancy, BalancyPaymentInfo} from '@balancy/core';    
import {BalancyPurchaseProductResponseData} from "@balancy/wasm";

function purchaseCompleted(response: BalancyPurchaseProductResponseData): void {
    console.log("Response received:");
    console.log("Success:", response.success);
    console.log("Error Code:", response.errorCode);
    console.log("Error Message:", response.errorMessage);
    console.log("ProductId: ", response.productId);
}

let paymentInfo = new BalancyPaymentInfo(...);

Balancy.API.hardPurchaseStoreItem(storeItem, paymentInfo, purchaseCompleted, requireValidation);
Balancy.API.hardPurchaseGameOffer(offerInfo, paymentInfo, purchaseCompleted, requireValidation);
Balancy.API.hardPurchaseGameOfferGroup(offerGroupInfo, storeItem, paymentInfo, purchaseCompleted, requireValidation);