Beamable Integration

​

Why use Beamable with ZBD?

To ensure the security of your game integration with the ZBD API, it is crucial to safeguard your ZBD API Key and avoid exposing it within any client-side code.

By leveraging Beamable’s Microservices and Realm (environment) configurations, you can secure your ZBD API Key by moving it from the game client to a server.

A microservice architecture, or “microservice”, is a solution of developing software systems that focuses on building single-function modules with well-defined interfaces and operations.

https://docs.beamable.com/docs/microservices-feature-overview

This provides you a path for a seamless integration solution that powers easy and safe incorporation of ZBD functionalities into your game.

​

ZBD Unity Package Overview

The ZBD Unity Package is a great starting point/reference package to safely integrate the ZBD API into your game using Beamable Microservices. See instructions to download the ZBD Unity Package here.

The ZBD Unity Package contains the following:

​

Microservice Demo

This demo showcases how you can use a Beamable Microservice to integrate with the ZBD API safely. You can utilize the fully functional Microservice in your project, or use this as a guide to create your own Microservices.

​

ZBD Login Demo

This demo showcases a working implementation of ZBD Login (OAuth2) using Beamable Microservices on an Android device, enabling you to quickly achieve secure login to your game.

​

UI Kit Demo

This demo showcases how you can integrate ZBD reward balances and reward withdrawal flows into your game, including a playable scene to visualize the look and feel of the UI. Note: There is no functionality in this demo; this simply showcases UI elements that can be used in your project(s).

To integrate this package into your game, you’ll need to set up Unity, set up Beamable, run Beamable Microservices locally, then [publish Microservices on the Beamable platform](#publish-microservices-on-beamable-platform).

​

Unity Setup

You can begin with a new Unity project, or work from an existing one.

​

1. Install Newtonsoft JSON

1. In Unity, go to the Package Manager -> Add package by name -> input com.unity.nuget.newtonsoft-json.
2. Click Add.

​

2. Install Beamable

Follow the instructions here.

​

3. Download ZBD Unity Package

1. Go to the GitHub repository and download the latest release .unitypackage file.

2. Drag and drop the file into the Unity project explorer to install the package.

​

4. Install Docker Desktop

Docker Desktop is needed to run and test the Microservice locally.

​

Beamable Setup

​

1. Obtain ZBD API Key

To interact with the ZBD API, you must obtain an API Key from your ZBD Dev Dashboard account. If you are unsure about the process, see this guide for step-by-step instructions.

​

2. Add ZBD API Key to your Beamable Project

You need to add the ZBD API Key to your project’s Realm Configuration on Beamable. Please refer to this guide, which explains how to log in to Beamable and create a game. If you are utilizing the ZBD / Beamable starter project, you can skip the installation steps and proceed directly to logging in and creating a game.

1. In the Beamable Portal in the left side menu go to Operate -> Config

2. Add a new config by clicking + Add Config

3. Add two Config Values:

Here is an example of how your Realm configuration should look:

💡 Note: To use the provided sample Microservice, you must use these exact namespace and key values.

​

Run Microservices Locally

By leveraging Microservices, we are securing our ZBD API Key by moving it from the game client to a server.

Before testing the Microservices, we need to run it locally.

​

1. Open Microservices Manager

In Unity, go to Window -> Beamable -> Open Microservices Manager

💡 Note: Here you will see the ZebedeeMicroservice

💡 Note: If you see this warning, make sure you have Docker installed.

​

2. Run Microservice

Hit the Play button.

​

Publish Microservices on Beamable Platform

When you are ready to test on other devices (outside of Unity editor), you will need to publish your Microservice to Beamable.

​

1. Open Beamable Publish Window

In the Microservices Manager tab in Unity, click Publish.

​

2. Publish Select Microservices

In the Publish window, toggle on which Microservice(s) you want published, then click Publish. This will deploy your Microservice(s) to Beamable’s platform.

​

3. View Microservices Status

Validate the applicable Microservice(s) are running by viewing the Microservices tab in the Beamable Portal.

💡 For more details on publishing Microservices, check out the Beamable documentation here.

At this point, your game can now connect the published Beamable Microservice(s), which protects your ZBD API Key from the game client!

​

Integrating the Microservices

To see sample code for how to integrate Beamable Microservices, view the MyController.cs file in the scripts directory of the ZBD Unity Package within Unity. Insert this code in applicable area(s) of your game; e.g. when you’re Sending sats to a ZBD Gamertag.

To get data that needs to be secure from Beamable (as we do for the apikey and clientsecret), you can reference the code in Config.cs and the GetAPIKey function in ZebedeeMicroservice.cs.

// This code ensures that the Beamable Microservice is ready
var ctx = BeamContext.Default;
await ctx.OnReady;

// This line makes the call to the Microservice
var result = await ctx.Microservices().ZebedeeMicroservice().GetWallet();

// Here we take the string and convert it to a response object
// The ZBD sdk has a response object for all responses.
// This allows you to easily get the data you need.
var jsonObject = JsonConvert.DeserializeObject<GetWalletDetails_Response>(result);

// If needed for custom Microservice integration...
// This code gets the value stored at the given key from Beamable
public string ApiKey => _settings.GetSetting("ZebedeeAPI", "apikey");
public string ClientSecret => _settings.GetSetting("ZebedeeAPI", "clientsecret");

​

ZBD Login Example Scene

This scene shows how you can integrate ZBD Login with an Android build.

This uses the Microservice to communicate with ZBD to let your users log in securely.

To see how to integrate ZBD Login (OAuth2 flow) you can check out the LoginController.cs script. This handles the initial start of the login flow and the deep link functionality.

​

1. Get ZBD OAuth2 Client ID

Add your Client ID from the ZBD Dev Dashboard and add it to the LoginController in the ZBD Login demo scene.

​

2. Ensure Microservices are Published

If you haven’t already, you will need to publish your Microservice(s) to Beamable. Once your Microservice(s) are published, you will be able to use it from anywhere. See Publish Select Microservices for more details.

​

3. Build for Android

You can now build your game for Android. Learn more here.

​

Troubleshooting

​

General Issues

If you are experiencing any issues here are a few things to check:

• Make sure you are logged in to Beamable in the Unity Editor

• Make sure you have the correct game selected in the Beamable plugin within Unity

• Ensure you are in the correct Beamable Realm (environment) in Unity

​

403 Errors

These issues are usually caused by an improper Docker or Microservice setup.

A few things to check:

• Docker is installed correctly and running

• The Microservice is running locally when developing (this can be checked by the play button being highlighted in the Microservices tab in Unity)

• If you are expecting a Published Microservice, ensure the Microservice is published and deployed to the correct Realm from the Beamable Portal.