Integrating Player Rewards in a Game

This guide will take you step by step through everything you need to know to integrate Bitcoin rewards using ZBD API into your game.

Here’s what’s in this guide:

Not into reading? Here’s a video tutorial taking you through the entire process of integrating time-based rewards into a Unity game. It literally only takes a bit over an hour.

​

Setting up your account

If you’ve already set up a ZBD API account, created a Project and put some Bitcoin into it, feel free to skip this section.

​

Step 1: Sign up and verify

Signing up as a developer on ZBD is super easy. Head over to the sign-up page by clicking here.

You will then have to do the following:

1. Verify your email
2. Verify your identity/business
   • If you’ve received an invite code from our BD team and signed up with that, then we will be in touch with some forms to verify your business
   • If you didn’t sign up with a code, that’s totally fine. Just complete the simple ID verification process in our platform

​

Step 2: Create and fund Project

There are two types of wallets inside the ZBD Dashboard:

1. Main wallet - this is very secure and should hold most of your Bitcoin
2. Projects - these are connected to API keys and should be topped up in small amounts regularly, to protect your funds from bots, hackers or simple mistakes.
   • RULE OF THUMB: Create one project per game. So basically ZBD Project = rewards wallet for your game. We recommend you give your project the same name as your game.
   • STATING THE OBVIOUS: If someone gets a hold of the API keys for your project wallet, they can drain all the Bitcoin inside that project.

Now, your project needs funds.

First, get some Bitcoin to your main wallet. You can do this by pressing the charge button on the wallet page and making a transfer from any Bitcoin Lightning wallet or exchange that supports the Lightning protocol.

If you don’t have access to an exchange account, our dashboard also features a Sandbox mode to get you started with testing payments. Just make sure you’re using our Sandbox APIs and keys, they’re separate from production ones!

More ways to top up your balance from the ZBD Dashboard are coming soon!

Second, transfer Bitcoin from your main wallet to your project wallet. On the main wallet page, simply press the transfer button. The rest should be obvious.

​

Under the hood

​

ZBD API in your game

Before you get started: Do you have a server?

We realize many games don’t require running any server-side code. For hypercasual and casual mobile games especially, it’s usually totally fine to run all code on the client. Unfortunately, this won’t work when you’re integrating any sort of real-money functionality.

You absolutely must store the following on a secure server, or you will get robbed.

1. Your ZBD Project API keys - this gives access to sending out rewards
2. User balances - how much a user has earned and not withdrawn yet

No server? No worries, we have a solution

We’ve partnered with Beamable to provide game devs without existing server infra with a simple yet powerful and safe solution. Sounds interesting? Sign up for a Beamable account here.

For a step by step guide on how to set up ZBD using Beamable for a Unity game:

​

Storing your API key

It is important to make sure that your ZBD API key is stored securely in your backend of choice. The API key should NOT be stored in the client.

​

Storing user balances

Rewards work best when the player sees them accumulating inside the game clearly. More on the UX/UI on this below (including templates), but for now, let’s talk about the server-side part of user balances.

You should always store how much a user has earned (and not yet withdrawn) on the server. If you store it on the client, bad actors can decompile your game, change that variable and pay themselves.

If you’re familiar with storing values on a backend, feel free to skip this next section.

There’s three parts to it:

1. Storing user balances on the server
   • You need a user identifier, such as Device ID or GAID
   • You need to store a value for rewards
2. Resetting the user balance when they withdraw rewards from the game to ZBD
3. Displaying all that inside your game

​

On to the ZBD API

There are a few different ways to integrate the ZBD API. These are the two we recommend for games:

1. Send to Email - easy to set up, very little friction for gamers.
   • Ideal for integrating fast, with minimal dev work
   • Gamers only need to enter their email to withdraw.
     • If they already have a ZBD account -> they get Bitcoin instantly
     • If they don’t have a ZBD account -> we send them an email with a voucher for the rewards and further instructions
2. Log in with ZBD - a bit more setup, but more powerful features and controls
   • Just like “Sign in with Google”, but for sending people Bitcoin
   • Ideal for games that want to build deeper integrations and have more insight into users/who is receiving rewards

​

The simple way: Send to Email

This is the easiest way to get started with player rewards using the ZBD API.

​

Using the Send to Email API

To send Bitcoin to a given email, all you need to do is call the Send to Email API with a POST call providing the following properties:

Header Your ZBD Project API key

Body

• The Email of the intended recipient (e.g. info@zebedee.io)
• The amount for the Payment -> in millisatoshis
• Note / description of this Payment (will be shown to recipient)

To learn more about using Send to Email, please check our docs here.

​

The advanced way: Log in with ZBD

Similar to Log in with Google/Apple/Facebook. But for moving money. Gives you access to more detail about your users, which enables advanced controls, like separate settings for ID verified users, querying a user’s balance and more.

​

Integrating Log in with ZBD

First, you need to integrate Log in with ZBD - this is built on the OAuth2 protocol, so it should be pretty standard.

If you are using Unity and Beamable (described above), we have a step-by-step guide and example projects for you here.

If you are using other engines or backends, we have a guide for you here.

​

Sending rewards with Log in with ZBD

Log in with ZBD is a way to get user data. You can use it to fetch a user’s ZBD Gamertag (basically their username on our system). To make payments, you just use our standard Send to Gamertag API.

It’s similar to sending to email. To learn how to Send to Gamertag, check our docs here.

​

The front-end

In-game UI/UX

This part of the guide will look at two things:

1. ZBD Withdrawal flow - how do users cash out from your game to their ZBD App?
2. Reward Mechanics - how do users actually get rewards in your game?

​

ZBD Withdrawal flow

Why are we starting with how users claim rewards and not with how they get them? Because this part is simple and we have established very clear best-practices and prototypes. So this should be a breeze!

The Components

This is what you’ll need to show inside your game:

1. Reward counter - how much the user has earned (and not withdrawn yet)
2. Withdrawal UI - a few simple screens that allow the user to withdraw

That’s it! You can check out a prototype of this here and it’ll all make sense.

You can find a Unity package with all required elements set up in a way that’s easy to customize here.

ZBD integrations come in all shapes and sizes - it’s really up to you what you want to build and how complex you want to go. But no matter what you’re building, the withdrawal UX will work the same way. And, hopefully, that part is super clear now!

​

Reward mechanics

Ok, now the fun part: deciding how users earn rewards in your game. Most ZBD games go custom and build custom mechanics inside the game. But there’s also a one size fits all solution.

​

One size fits all: time-based rewards

The simplest way to implement real-money rewards into a game is to simply say if a user plays for X amount of time, reward them with Y amount of Bitcoin.

Here’s a video tutorial that takes you through the entire process!

​

Messaging

It’s very important to clearly let the user know when they’ve earned a reward. We suggest showing a banner overlay every time a user earns a reward, that says: “You’ve just earned a bit of Bitcoin! Keep playing to earn more!”

​

How to not get scammed

Any system that gives out real money for playing a game will always attract exploiters. Luckily, there are powerful tools available that ensure only legitimate players can get rewards.

Security essential: Play Integrity We HIGHLY recommend you add Google Play Integrity and iOS Device Check to any game that gives out real-money rewards. This will ensure only users on legitimate devices (not emulators, not rooted) can get rewards. Firebase offers a convenient Wrapper called App Check for both services that you can integrate inside of Unity.

Here’s how you do it.

Validating gameplay: Quago

You should validate real gameplay before giving out any rewards. Because you don’t want to give rewards to users that just open a game and leave it running. You want them actually playing legitimately!

To do that, you need to run some sort of anti-cheat software. Otherwise, you will get scammed! We recommend Quago for this.

You can then make calls from your server or backend (PlayFab Cloud Script, Beamable micro service) to get the user’s “game play data” which will tell you if the user has cheated - used a bot, fake device, etc.

Quago.initialize(QuagoSettings
.create(appToken, QuagoSettings.QuagoFlavor.PRODUCTION).setLogLevel(QuagoSettings.LogLevel.INFO)

);
var userId = SystemInfo.deviceUniqueIdentifier;
Quago.beginTracking(userId);

API Endpoint to call on the server to get the Users playtime data
https://inference.quago.io/user/userId/?app_token=QUAGO_APP_TOKEN

Example Response

{
  "platforms": "Android",
  "last_seen_timestamp": "2023-10-29T18:49:00",
  "cnt_inauth_days": 0,
  "last_inauth_timestamp": null,
  "total_playtime_hours": 0.16,
  "total_motion_hours": 0.09109083333333333,
  "inauth_playtime_percentage": 0,
  "emu_playtime_percentage": 0,
  "emu_models": "[]",
  "input_devices_found": "[]",
  "avg_session_playtime_minutes": 1.36,
  "avg_daily_playtime_hours": 0.16,
  "cnt_device_ids": 1,
  "cnt_ips": 1,
  "countries": "GB",
  "device_model": "SM-S911B",
  "system_version": "13"
}

​

Advanced integration: custom mechanics

Every game is different, so we really can’t tell you exactly how to integrate rewards as a native part of gameplay. But here’s an example that should make it pretty clear how it works and give you some ideas!

Example: Bitcoin Miner by Fumb Games

This is a simple crypto mining simulation game. Check it out here: Android / iOS

Inside, players earn rewards by tapping on coins with an orange “satoshi icon” on top:

That’s it! Thanks for reading this guide, now go and create some super rewarding experiences for your players!