Using the API with Unity3D

It is possible to access the API from a Unity3D game uploaded to Kongregate using the Application.externalCall and Application.externalEval functions from within your Unity application. The following documentation assumes you are using Javascript for your Unity scripting, but can easily be adapted for other languages. Also note that if you are attempting to use the API from an iframe-hosted Unity project, you will need to load and initialize the Javascript API manually.

Loading the API

In order to load/initialize the Kongregate API object, you need to make an external call to a Javascript object which will be automatically created for you. This object will be available before your Unity application begins running, so it is safe to use at any time. The following is an example of how to use the kongregateUnitySupport object to load the Konregate API and notify your Unity application when the loading is completed.

initAPI(unityObjectName, callbackFunctionName)
  • unityObjectName:String - The name of the object to perform the callback on.
  • callbackFunctionName:String - The name of the function to call on the given object.

Example: Initialize the API, and call the OnKongregateAPILoaded function on the MyUnityObject Unity entity when loading is done.

// Begin the API loading process if it is available
Application.ExternalEval(
  "if(typeof(kongregateUnitySupport) != 'undefined'){" +
  " kongregateUnitySupport.initAPI('MyUnityObject', 'OnKongregateAPILoaded');" +
  "};"
);

Note the use of the Application.ExternalEval function to call out to the kongregateUnitySupport Javascript object if it exists. When the API completes loading, it will use Unity's SendMessage function to call the given function on the Unity game object with the name passed in. Also, make sure you do not load the API more than once - this will cause the API connection to completely break.

The callback will be invoked with a single String argument which contains tokenized user information.
  • userInfo:String - A pipe-delimited (|) string containing the user id, username, and game_auth_token.

Example: A simple OnKongregateAPILoaded function: 

var isKongregate = false;
var userId = 0;
var username = "Guest";
var gameAuthToken = "";

function OnKongregateAPILoaded(userInfoString){
  // We now know we're on Kongregate
  isKongregate = true;

  // Split the user info up into tokens
  var params = userInfoString.Split("|"[0]);
  userId = parseInt(params[0]);
  username = params[1];
  gameAuthToken = params[2];
}

Submitting a Statistic

Now that the API has been initialized, you are able to use any of the Javascript API functionality from within your Unity script by referencing the kongregate object that exists in Javascript. Functions which don't require a callback are relatively simple, such as submitting a statistic. (Note that you will also need to set up Statistics for your game, as described in our Statistics documentation)

Example: Submit a statistic named "Score" with a value of 1000.

// Begin the API loading process if it is available
Application.ExternalCall("kongregate.stats.submit","Score",1000);

Callbacks

Many Kongregate API functions (such as the user sign-in event) require you to define a callback in order to properly function. Due to the fact that the Unity SendMessage function can only send a single argument, it is often easier to create a temporary function in Javascript to handle the callback, and then have that function call your Unity object in whatever fashion you find convenient. Below is an example of how to handle the user sign-in event callback using Unity.

Example: Register a listener for the user sign-in event.

// Called when the Kongregate user signs in, parse the tokenized user-info string that we
// generate below using Javascript.
function OnKongregateUserSignedIn(userInfoString){
  var params = userInfoString.Split("|"[0]);
  userId = parseInt(params[0]);
  username = params[1];
  gameAuthToken = params[2];
}

// Register a sign in handler to let us know if the user signs in to Kongregate. Notice how we are using the 
// Javascript API along with Application.ExternalEval, and then calling back into our app using SendMessage.
// We deliver the new user information as a simple pipe-delimited string, which we can easily parse using String.Split. 
Application.ExternalEval(
	"kongregate.services.addEventListener('login', function(){" +
	"	var services = kongregate.services;" +
	"	var params=[services.getUserId(), services.getUsername(), services.getGameAuthToken()].join('|');" +
	"	kongregateUnitySupport.getUnityObject().SendMessage('MyUnityObject', 'OnKongregateUserSignedIn', params);" + 
	"});"
);