If you need to add in-app purchases or subscriptions to your game, then you've come to the right place. Zalance is the best way to add monetization without the hassle of worrying about payment systems, refunds, fraud, or creating product management from scratch. The Zalance Addon simplifies querying products, displaying prices, and handling purchases.
REQUIREMENTS
This tutorial assumes you already have a Zalance account and have set up a project. If you haven't, go ahead and do that now. You can also use the Quickstart guide in our documentation if you need help. The example project uses both the Zalance API and PlayFab API addons.
Addons
SEE A WORKING EXAMPLE
It's helpful to know what we're heading towards. Click here to open the working example. The working example demonstrates a store and product catalog using the PlayFab service as a backend. However, Zalance will work with any backend service that you like.
When you're done, close the preview and press reload in your browser so Construct 3 restarts. This allows us to start the tutorial from a clean slate.
ASKING FOR HELP
If you need help or have a question, please contact us. Comments are enabled for this tutorial, but they're easily missed. You're more likely to get a response from an email.
GETTING STARTED
INSTALL THE ADDON
Either open your existing project or click the New Project button. Next, you will need the Zalance API Addon either available from the Construct Addons page or the Zalance website. Click the download button and save the file to your computer. Install the addon through the Addon manager. The Addon manager can be accessed from the Construct editor from Menu ► View ► Addon manager.
Click the Install new addon button at the next screen's bottom.
Install the addon by selecting the Zalance.c3addon file you downloaded to your computer.
SETUP THE PLUGIN
We need to add the Zalance plugin object type to your object’s list. Right-click the Object types in the Project view and choose Add new object type.
Then choose the Zalance plugin.
Select the Zalance object that was created in the Object types menu.
In the Properties panel, enter your PlayFab Project ID.
If you don’t know your project ID, you can find it in your Zalance dashboard under Project > Details.
STORE LAYOUT
In your store layout, add a new HTML element and call it PriceList. This will contain a grid of your products and prices. So, make sure its size fills most of the page. In the PriceList Properties, set the Tag to div and Content to:
<div id="priceListInner"></div>
It should look similar to this:
STORE EVENT SHEET
Let's create a store screen for displaying your products and prices. Start by creating a new Layout and name it Store. Then, add a new event Sheet called StoreCode.
SET THE ACCOUNT
Before you can request a checkout session for a user, you need to supply Zalance with the user’s account Id. Add a System event for “On start of layout” and choose the ZalanceAPI plugin for the action. Then choose Set account id.
Then, add the player’s account Id field according to your server management.
GET PRICES
First, we need to get the products from our catalog list. Add a System event for On start of layout and choose the ZalanceAPI plugin for the action.
We will select Get prices which should give you an event that looks like the following.
Then, we need to add an event to handle the returned prices. Select a new event and choose the ZalanceAPI’s “On prices received” event. For actions, choose the JSON object and then parse. Then, choose the ZalanceAPI.GetLastPrices.
We’ll rename the JSON object to PricesJSON for clarity. The final event should look like this:
Next, add a sub-event to display the prices and select the PricesJSON we just created. Using the For each entry, we’ll be able to loop through each price in the object. We can then select an HTML action to create the price list. Use the following HTML code snippet.
<div class=""price-item"">
<img src=" & PricesJSON.Get(".image.url") & " alt=""item image"" class=""price-item-img"" width=""auto"" height=""auto"">
<h3 style=""color: white; font-size: 1.6em; font-family: Roboto, sans-serif;"">" & PricesJSON.Get(".name") & "</h3>
<button id=" & PricesJSON.Get(".price_id") & " type=""button"" class=""price-btn"">"
& PricesJSON.Get(".display_amount")&
"</button>
</div>
The parameters for the action should also place the Selector as #priceListInner. When done, it should look like this:
Then, we should wait for this System action to complete before adding our button-click action. For the action, let’s write a bit of code using a script. Right-click on +Add action and choose Add script.
Then paste the following javascript code into the script box.
.function AddOnClickEvent() {
const list = document.getElementsByClassName('price-btn');
Array.from(list).forEach((item) => {
item.onclick = () => {
console.log('item', item);
const inst = runtime.objects.ZalanceAPI.getFirstInstance();
inst.StartCheckout(item.id, 1, false);
}
})
}
AddOnClickEvent();
That action should look like this.
This script will trigger the ZalanceAPI call to start a checkout when an item is clicked. The API will automatically create a purchase iFrame element for your user to enter their payment information and complete the transaction.
If you have set up Webhooks correctly in your Zalance project. Then, your game server will be notified upon payment.
STYLING
Finally, let's add a bit of styling to dress our store up. We're using a CSS sheet called store.css. We'll load this file during the On start of layout event. See the C3 project store.css for reference. If you are using the free version, you can apply styles to individual HTML elements through either events or the style attribute.
#priceListOuter {
overflow-y: auto;
overflow-x: hidden;
padding: 1em 2em 1em 1em;
background-color: rgba(0,0,0,0.4)
}
#priceListInner {
height: 7em;
width: 100%;
display: grid;
grid-template-columns: repeat(4, 1fr);
gap: 1em;
}
.price-item {
padding: 0.5em;
display: flex;
flex-direction: column;
align-items: center;
justify-content: center;
background-color: rgba(0,0,0,0.9);
border: 1px solid #FFD700;
border-radius: 6px;
}
.price-item:hover {
transform: scale(1.02, 1.02);
background-color: rgba(96, 2, 238, 0.4);
}
.price-item-img {
min-height: 5em;
max-height: 7.8em;
width: auto;
height: auto;
}
.price-btn {
width: 80%;
height: 2em;
background: #FFD700;
border: 1px solid #FFD700;
border-radius: 6px;
color: black;
font-size: 1.4em;
font-family: Roboto, Helvetica, Arial, sans-serif,
sans-serif;
font-weight: 500;
}
.price-btn:hover {
background: #ffc000;
border: 1px solid #ffc000;
cursor: pointer;
}
CONCLUSION
You should now be able to begin testing your application and making purchases. We highly recommend setting your Zalance project to test by turning the livemode option off. Feel free to test your game until you are satisfied with your store, prices, and settings.
Remember you can download a working example of this tutorial on the Zalance download page.