Skip to content

Quick Start Guide: TypeScript

Initialize SDK

  1. Install the Balancy SDK packages:

    npm install --save @balancy/core@latest
npm install --save @balancy/utils@latest

  2. Download React example components:

  3. Import and use in your project:

    import { BalancySimpleIntegration, SimpleBalancyConfig } from './components/BalancySimpleIntegration';
import { Environment } from '@balancy/core';

const config: SimpleBalancyConfig = {
  apiGameId: 'your_game_id',
  publicKey: 'your_public_key',
  environment: Environment.Development
};

function App() {
  return (
    <div>
      {/* Your app content */}
      <BalancySimpleIntegration
        config={config}
        onReady={() => console.log('Balancy is ready!')}
        onError={(error) => console.error('Balancy error:', error)}
      />
    </div>
  );
}

  4. Launch your React app:

After Balancy loads, you'll see icons for all active offers and events. Click any icon to open its associated view. A red "Reset" button in the top-right corner allows you to reset Balancy profiles for testing.

TypeScript Integration UI

Payments

The example includes a preparePayments() function that sets up the mandatory Balancy payment callbacks:

function createTestPaymentInfo(price: SmartObjectsPrice): BalancyPaymentInfo {
   const orderId = generateGuid();
   const productId = price.product?.productId || "";
   const productPrice = price.product?.price || 0;

   const paymentInfo: BalancyPaymentInfo = {
      price: productPrice,
      currency: "USD",
      orderId: orderId,
      productId: productId,
      receipt: `<receipt>` // Placeholder for receipt
   };

   // Below is the testing receipt, it's not designed for production
   paymentInfo.receipt = JSON.stringify({
      Payload: JSON.stringify({
         json: JSON.stringify({
            orderId: paymentInfo.orderId,
            productId: paymentInfo.productId
         }),
         signature: "bypass"
      })
   });

   return paymentInfo;
}

function preparePayments() {
   Balancy.Actions.Ads.setAdWatchCallback((storeItem : SmartObjectsStoreItem) => {
      console.log('Fake ad watched for:', storeItem?.name);
      //TODO Implement your ad watch logic here
      storeItem?.adWasWatched();
   });

   Balancy.Actions.Purchasing.setHardPurchaseCallback((productInfo) => {
      console.log('Starting Purchase: ', productInfo?.productId);
      const price = productInfo?.getStoreItem()?.price;

      // Implement your hard purchase logic here
      if (price) {
         const paymentInfo = createTestPaymentInfo(price);
         //Tell Balancy that payment was successful
         Balancy.API.finalizedHardPurchase(true, productInfo, paymentInfo);
      } else {
         console.warn('No price information available for the product:', productInfo?.productId);
         Balancy.API.finalizedHardPurchase(false, productInfo, null);
      }
   });

   Balancy.Actions.Purchasing.setGetHardPurchaseInfoCallback((productId) => {
      const allStoreItems = Balancy.CMS.getModels(SmartObjectsStoreItem, true);
      let price = 0.01;
      for (const storeItem of allStoreItems) {
         if (storeItem?.price?.product?.productId === productId) {
            price = storeItem.price.product.price;
            break;
         }
      }
      return new BalancyHardProductInfo(
              "Test Purchase",
              "Test Purchase Description",
              `$${Number(price).toFixed(2)}`,
              price,
              "USD");
   });
}

Payment Callbacks Explained:

  1. setAdWatchCallback - Called when a user wants to watch an ad
  2. setHardPurchaseCallback - Called when a user initiates a real money purchase
  3. setGetHardPurchaseInfoCallback - Used by Balancy UI to get product information (pricing, descriptions)

For more details about the payment system, see the Payments Guide.

Demo

Clone a complete working example from our public GitHub project: Balancy TypeScript Example.

You can also access the Live Demo.

Next Steps

To learn more about Balancy methods and callbacks: