Warning! This version of the API is deprecated. You should use version 2 instead!

1 - Setting up your game on Game Jolt website

Make Mama Proud

I’ll start with the assumption that you already have an account on Game Jolt. Otherwise, create a new one here.

On your dashboard, hit the Add a Game (make mama proud!) button on the top right corner. Read and accept the rules. Then you can name your game, add a description and so on. Don’t worry too much for now, you can change everything later on.

Your are now given a list of things to do before you can make your game public. Take your time to look around and get use to the Game Dashboard.

Trophies and Leaderboards

Go to Achievements from the main menu. The Achievements page has three tabs: Game Trophiesand High Scores and Data Storage. However, we will only talk about the first two ones in this tutorial. It also has a Game Info box on the right with your Game ID and Private Key. We will need them later.

Within the Game Trophies tab, add two of them. It’s pretty straight forward, you shouldn’t need my help. Just note the visible checkbox, it will make the trophy visible to everybody or just. It’s pretty useful when you created your game long ago to share some dev news but you don’t want to reveal your trophies yet.

Once you’re done, note that each trophy has an identifier. This is what we will be using to refer to them within our code.

Now go to the High Score tab. One had already been created for you and it has an identifier as well. Like trophies, this is what we will be using to refer to them within our code.
Also, note that this table is your primary table. It means that if you submit a score without specifying which table it belongs to, it will use that one.

Finally, create another table for the need of the tutorial.

2 - Setting up the API in Unity

Import

First, download the Unity Game Jolt API 1.2 package.

Open your Unity project. In the Project pane, right-clic and select Import Package then Custom Package…
Locate the package on hard-drive and press Open then Import.

3 - Using the API

I’ll now assume that you have a basic knowledge of Unity and C#, thus I won’t tell you how to create a game object or attach a script to it or what is a function. This is beyond the aim of this tutorial.

Build the base

Create a new C# Script and call it GameJoltAPIManager. Then, create an empty game object, name it _GameJoltAPIManager and attach the script it.

If you open the script with your favorite code editor, it should look like this:

		
			using UnityEngine;  
using System.Collections;

public class GameJoltAPIManager : MonoBehaviour {

    // Use this for initialization  
    void Start () {

    }

    // Update is called once per frame  
    void Update () {

    }
}
		
	

You can remove the Start and Update functions, we won’t need them. However, we will need some variables to store our Game ID, Private Key, etc so let’s create them. We will also make them public so they show up in the inspector.

		
			using UnityEngine;  
using System.Collections;

 public class GameJoltAPIManager : MonoBehaviour {

    public int gameID;
    public string privateKey;  
    public string userName;  
    public string userToken;

}
		
	

Go back to Unity, your variables should show up. Fill the Game ID and Private Key with the corresponding values. For testing purpose, fill the user details with your own. Make sure that in the release build of your game, you ask the user to provide his own details and you do not use yours!

Don’t destroy on load

The Game Jolt API is set not to destroy on load which means it will survive even if you load a new level but because it will call methods through callbacks (more on this later) on our script, it needs to survive level loads as well. In the Awake function, we will tell Unity not to destroy our script on load.

		
			using UnityEngine;  
using System.Collections; 

public class GameJoltAPIManager : MonoBehaviour { 

    public int gameID;  
    public string privateKey;  
    public string userName;  
    public string userToken;

    void Awake () {
         DontDestroyOnLoad ( gameObject );
   }

}
		
	

Initialize first

Another characteristic of the Unity Game Jolt API, is that is use a Singleton Pattern which means you don’t need a reference to it to call one of its method. Just call the method. Pretty handy.

To initialize the API, just call Init. It takes up to 4 parameters:

• Your Game Identifier. Refer to the first part of this tutorial to know where to find it.

• Your Game Private Key. Refer to the first part of this tutorial to know where to find it.

• Whether you want the API to be verbose (i.e. print messages to the console). Optional. Default to true.

• The version of the API to use. Optional. Default to 1.

		
			using UnityEngine;  
using System.Collections;

public class GameJoltAPIManager : MonoBehaviour {

    public int gameID;  
    public string privateKey;  
    public string userName;  
    public string userToken;

    void Awake () {  
        DontDestroyOnLoad ( gameObject );  
        GJAPI.Init ( gameID, privateKey );
    }
}
		
	

Hit the Play button in Unity. You should see the message GJAPI: Initialisation complete in theConsole.

Who are you?

In your game, you may prompt the user to give you his username and token. For the tutorial, we will use yours that you should have filled in the inspector.

To verify a user, just call VerifyUser. It takes 2 parameters:

• The user username.

• The user token.

		
			using UnityEngine;  
using System.Collections; 

public class GameJoltAPIManager : MonoBehaviour {

    public int gameID;  
    public string privateKey;  
    public string userName;  
    public string userToken;

    void Awake () {  
       DontDestroyOnLoad ( gameObject );  
       GJAPI.Init ( gameID, privateKey );  
       GJAPI.Users.Verify ( userName, userToken );
    }

}
		
	

Hit the Play button again. You should see the message GJAPI: Verifying user then GJAPI: Opening URL: https://very.long.url/ and finally GJAPI: User successfully verified in the Console.

Please call me back

Great, things print to the console but how do you know within your code that the user was successfully verified? Say hi to callbacks! A callback is a function you’ll tell the API to call when it’s done so you can know about it.

First, we will need a method to callback so let’s create it. The VerifyUser Callback has to be of typevoid and accept a boolean as parameter.

		
			using UnityEngine;  
using System.Collections; 

public class GameJoltAPIManager : MonoBehaviour {

    public int gameID;  
    public string privateKey;  
    public string userName;  
    public string userToken;

    void Awake () {  
       DontDestroyOnLoad ( gameObject );  
       GJAPI.Init ( gameID, privateKey );  
       GJAPI.Users.Verify ( userName, userToken );  
    }

     void OnVerifyUser ( bool success ) {
         if ( success ) {
              Debug.Log ( "Yepee!" );  
         }
        else {  
             Debug.Log ( "Um... Something went wrong." );  
        }  
     }

}
		
	

Now we need to register our callback.

		
			using UnityEngine;  
using System.Collections; 

public class GameJoltAPIManager : MonoBehaviour {

    public int gameID;  
    public string privateKey;  
    public string userName;  
    public string userToken;

    void Awake () {  
       DontDestroyOnLoad ( gameObject );  
       GJAPI.Init ( gameID, privateKey );  
       GJAPI.Users.Verify ( userName, userToken );  
       GJAPI.Users.VerifyCallback += OnVerifyUser;

    }

    void OnVerifyUser ( bool success ) {  
        if ( success ) {  
             Debug.Log ( "Yepee!" );  
        }  
       else {  
            Debug.Log ( "Um... Something went wrong." );  
       }  
    }

}
		
	

It should be working but we can do a little bit better. Indeed, what happens if the script get disabled (or removed for whatever reason)? The game will crash because the API will call a method that doesn’t exist. Obviously we don’t want such a thing to happen but there is an easy fix. We can de-register our callback in OnDisable (Unity call this method on every Monobehaviour objects before disabling them). However doing that create another problem. Awake only get called once in the lifetime of the object. It means when the object will be enabled again, it won’t register its callback again but it’s very easy to fix, just move our callback registration to the OnEnable function (you got it, Unity call this method on every Monobehaviour objects before enabling them).

		
			using UnityEngine;  
using System.Collections; 

public class GameJoltAPIManager : MonoBehaviour {

    public int gameID;  
    public string privateKey;  
    public string userName;  
    public string userToken;

    void Awake () {  
       DontDestroyOnLoad ( gameObject );  
       GJAPI.Init ( gameID, privateKey );  
       GJAPI.Users.Verify ( userName, userToken );  
    }

     void OnEnable () {
         GJAPI.Users.VerifyCallback += OnVerifyUser;
     }

     void OnDisable () {  
        // Use this if you use the API v1.2.x
         GJAPI.Users.VerifyCallback -= OnVerifyUser;

        // Use this if you use the API v1.3.x
        if (GJAPI.Instance != null)
        {
            GJAPI.Users.VerifyCallback -= OnVerifyUser;  
       }  
   }

    void OnVerifyUser ( bool success ) {  
        if ( success ) {  
             Debug.Log ( "Yepee!" );  
        }  
       else {  
            Debug.Log ( "Um... Something went wrong." );  
       }  
    }

}
		
	

Other methods

To learn about every API Methods and their corresponding Callbacks, you can open the GJAPI.csfile (every method is commented) but it may be easier to start with the online demo.

Conclusion

The API was made with simplicity in mind but like everything, it will still need some practice. Just don’t give up!

Make sure to read the Helper tutorial as well.