Skip navigation

Joy Monster Documentation v1.1.0

Updated 6/11/2019

Create Your Developer Account

Create your account at, and fill out the basic information.

Create a Game

Select the "Games" menu item

games nav menu

Then click "New" to access the "Add Game" form

new game button

Please fill out basic information on the game. The JoyMonster team will get to work on the approval process for your game. You will immediately be given the sandbox api key so that you can begin integrating the JoyMonster box into your Unity game. Once your game has been approved, you will be granted the production API key. Please see the Sandbox section for more information on how to use it.

You may be contacted directly at the email address you used to sign up to clarify any details on the game.

Download & Install the Plugin

Download and install the JoyMonster plugin from the Unity store. Once the download has completed, import the plugin into your project using the import button on the package in the unity store.

We recommend using the Unity store to download and install the plugin. If you are using a package that did not come through the Unity store, you may import the package by going to Assets > Import Package > Custom Package.


  • The plugin requires TextMesh Pro. If you are running Unity2018.2 or newer, you will be automatically prompted to install the package.

  • You may download and install TextMesh Pro directly from the Unity store if you are using an older version.

    unity textmesh pro plugin

Testing The Plugin in the SandBox

Defining the API Key

Get your Sandbox API Key, and set it inside the JoyMonster window.

game edit button

game editing ui

For that, simply open the Window -> JoyMonster Settings window...

unity settings nav

...and enter your API Key inside the Authentication section.

unity api key setting

Launching The Plugin With Production API Key

Defining the API Key

Once your game has been approved by the JoyMonster team, a production API key will be issued, and will be available on the "Edit Game" page, which you may then insert into your Unity settings.

Production API key

Platform-Specific Required Settings

iOS - Requires a Location Usage Description

  • Go to Edit > Project Settings > Player > [iOS Tab]
  • Under the iOS tab, enter a value for the "Location usage description".
  • Suggested Value: "We request your approximate location to serve you rewards from local merchants"

Android - Disable COURSE_LOCATION

  • Go to Edit > Project Settings > Player > [Android Tab]
  • Under the Android tab, Verify the "Low location accuracy" checkbox is UNCHECKED.
  • We rely on the FINE_LOCATION permission; if this box is left checked, we will only have the COARSE_LOCATION permission, which prevents us from receiving location updates

Initializing The Plugin

The plugin will automatically initialize itself whenever the first call to any part of the API is made (usually this would either be when checking for offers in the wallet for a button in a menu, or when JoyMonsterPlugin.ResetBoxCollectedStatus() is called upon level start

Displaying The Wallet

The wallet screen

You'll need to add a button called "Wallet" somewhere in your game that users can click on to display the list of offers available to them. We recommend adding this to the game menu so that the user can easily access the wallet to redeem their rewards and it does not interfere with gameplay.

In order to display the wallet, simply call JoyMonsterPlugin.ShowWallet() when the user clicks on this button.


Displaying offers available

If you want to highlight the wallet button, make it flash or anything, to alert the user that some offers are available in the wallet, you can use the JoyMonsterPlugin.GetOfferCount() method as follows:

    // The user has offers! Do what you want here with that information
}).Catch(exception => {
    // An error occurred checking if the wallet has offers
    // You can use exception.Message to see what is error is

The JoyMonster Box

Attaching the Box

The JoyMonster Box is called from the JoyMonster.World method. You may want to include this as a using statement at the top of your script. The examples below include the full call.

In order to attach a JoyMonster box to an object of your choice in your game, you'll just have to attach the JoyMonsterBox component at the root of this object. And inside your own script (attached to the object), you'll just have to call the AttachBox method of the JoyMonsterBox component, as such:

void OnEnable(){

This will automatically attach the JoyMonsterBox on top of your object in the game, if one is available. If none are available, nothing will happen, so you don't have to worry about anything.

As each game is a bit different, this is also the place where you can define your own rules, such as only calling AttachBox once in a game, or once every x minutes etc…

When JoyMonster is initialized by the user, the plugin will ask the server if there are any rewards available to that user. The plugin will either return the number of engagements in the area or not.

If there is an engagement available, then JoyMonster will attach the box to the object. If the player is throttled, then the box will not attach to the object.

Destroying the box

Once the player collected/destroyed/touched your object and it is now "collected", you'll also need to trigger the "collect" of the JoyMonsterBox. In order to do that, simply call the CollectBox method on the JoyMonsterBox component, as such:


This will trigger the animation of the JoyMonsterBox being destroyed, and add a reward to the wallet of the user.

Releasing the box

In some cases, the player will miss your object thus will not collect the JoyMonsterBox. In this scenario, you want to "release" the JoyMonsterBox once it's out of screen, to be able to reuse it later in the game, when another call to AttachBox will be made. In order to do that, just call the ReleaseBox method on the JoyMonsterBox component.

In most cases, you already destroy your object when it's out of screen, if that's the case, just add the ReleaseBox call inside the OnDestroy callback of your script, so when your object is destroyed, it will also release the JoyMonsterBox.

void OnDestroy(){

The Reward Screen

Finally, at the end of the game, you'll want to display what is the reward the user collected during the game when he collected a JoyMonsterBox. In order to do that, when you display your game over screen, you'll just need to call the following:


Calling this method will display the reward the user won in fullscreen. The user will dismiss the screen and will be brought back to your game over screen.