Skip navigation

Joy Monster Documentation v1.1.0

Updated 8/21/2019

Getting Started

This section will guide you through obtaining your API keys and configuring Unity.

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.

A note on our demo game: We include a demo game in the plugin so you can see how integration is handled; TextMeshPro is a requirement that Unity will download when the scene in the demo is loaded. On first run, there may be some small bugs in the display; this is due to TextMeshPro importing TMP Essentials while the demo scene is loading. If it happens, wait till the import completes, then, without saving, re-open the scene.

Running Unity 2018.2 or older? Unity 2018.3 minimum is required to be able to request permissions to use location. It is highly recommended that you use the 2018.3 or newer. This version uses run-time permissions, which will prompt the user for their location when either the first offer is displayed or when the wallet is opened.

With any Unity version before 2018.3:

  • If the device is running > Android 6: The user will have a pop-up asking for location permission at the start of the game. If this is dismissed, you will not get another chance to ask for player location permissions again. JoyMonster runs best with location turned on so we can give the users local offers.
  • If the device is running < Android 6: you directly have location data. It’s asked for on application install.
  • If the device is running Android 6: you may need to add unityplayer.SkipPermissionsDialog meta-data to the Android manifest. More info in the Unity Manual under "Runtime permissions in Android 6.0 (Marshmallow)" — Unity Manual: Android Manifest .

Building for Android: when building for Android, the build system must be Gradle.


  • The plugin requires TextMesh Pro. If you are running Unity 2018.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.

    You may need to re-import the JoyMonster plugin after you have downloaded TextMesh Pro.

    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"

Integrating JoyMonster With Your Game

To properly integrate JoyMonster into your game, you must successfully add each of these functions to your game:

  • Initialize the Plugin:
  • Display the Wallet:
  • Attach the JoyMonster Box:
    void OnEnable(){ 
  • Destroy the JoyMonster Box:
  • Release the JoyMonster Box:
  • Show the Carousel:

Please see below to learn more about each of these functions.

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

A real-world example, taken from our demo game's "Update the Wallet" button:

private void UpdateWalletButton()
    .Then(offerCount =>
        M_WalletButton.GetComponentInChildren().text = "Open Wallet" + (offerCount > 0 ? " (Offers Available)" : " (No Offers)");
    }).Catch(exception =>
        Debug.LogError("An error occurred checking if the wallet has offers: " + exception.Message);

The JoyMonster Box

Attaching the Box

TL;DR — You'll need to attach the JoyMonsterBox script to every type of object in the scene where you will want to display a JoyMonster Box. Then, simply call AttachBox whenever you want a box to appear. The basic solution is to call it whenever the object is created (OnEnable), so a box is on the object as soon as that object is available. However, in most cases, developers will probably have their own logic to determine when and where JoyMonster Boxes are attached, in which case, AttachBox would be called somewhere other than OnEnable.

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.

Logging & Debugging

In JoyMonster/Data/Resources/JoyMonsterSettings (this can also be opened from Top Menu > Window > JoyMonster > Settings ) there is an option to enable logging for JoyMonster-related functions. Be sure to also enable 'Development Build' and 'Script Debugging' in the Unity player settings and toggling the logging/stack trace options to 'Full' in Player Settings > Project Settings > Other Settings .

This should provide some information about the API calls (success/failure and some other info for engagement/wallet requests).

Join the in-game advertising revolution Start Now
Which best describes you? I'm an Advertiser I'm a Developer