API KIZ10 INSTRUCTIONS

IMPORTANT NOTES



API SETUP


For Unity-WebGL and other HTML5 games, add this script to the "index.html" file of your game and jump to the "INITIALIZE THE API" section:

<script type="text/javascript">
var Kiz10API = {
    apiObject: function() {},
    init: function (id, apikey) { 
            apiObject = false;
            try {
                apiObject = parent.document.getElementById("Kiz10API");
                if (!apiObject) apiObject = parent.parent.document.getElementById("Kiz10API");
            } catch(err) { }
            if (apiObject) apiObject.init(id, apikey);
          }, 
    submitStat: function (stat, value) { if (apiObject) apiObject.submitStat(stat, value) },
    submitAchievProgress: function (cod_achiev, progress) { if (apiObject) apiObject.submitAchievProgress(cod_achiev, progress) },
    apiLoaded: function () { return (apiObject ? true : false) }
}
</script>
	

(In Unity, you'll need to add this manually to the web build, once generated).


For AS2, AS3, Haxe or Stencil, download the apropiate version for your environment:


Then add the file com/kiz10/Kiz10API.??? to your flash project, and import the api class this way:

import com.kiz10.*;

If you are using the as2 version, add this line too:
var Kiz10API = new com.kiz10.Kiz10API();
And make sure this Kiz10API variable is visible all over your game.


INITIALIZE THE API


You'll need to know the identifier of your game on the portal and also an "api-key" to be able to use the api in your game. Both things are shown in the game profile. If you don't have an api-key, you can create one by clicking on "Generate api-key". At the start of the game (tipically before entering main menu), use the next sentence, replacing the first argument with the identifier of your game, and the second one with your actual game's api-key:

Kiz10API.init(8378, "1bd294bef3403da33dddf4d7f88f1Xa1");

The api then starts loading. You can know when it's ready for use this way:


if (Kiz10API.apiLoaded) {
	// Use the api
}

Or, alternativelly, you can provide a callback function to the init method that will be called when the api is loaded (option not available on Unity/HTML5):

Kiz10API.init(8378, "bbd294bef3403daaedddf4d7f88f1ba1", onApiLoaded);
function onApiLoaded(response:Object):void {
	// The api is ready
}


In Unity and HTML5 games, you don't need to wait for initialization.


In Unity, use the "ExternalCall" method to call the api. For example, for the previous initialization call, type:


Application.ExternalCall("Kiz10API.init", 8378, "bbd294bef3403daaedddf4d7f88f1ba1");


SUBMIT SCORES


We need some score on ALL our games. If your game doesn't have score, please think on some formula appropiated for your game (something like 100*levels_passed + enemies_killed), and submit the result as score.
You'll first need to create a "named stat" on the portal. Use the developer console to create it with the next data:


Once you've created the score stat, add this line to the relevant part of your code:

Kiz10API.submitStat("score", value);

Where "value" is the actual value (integer number) of the score. Please, keep low the number of calls to the api. Good places to make this call are usually the level complete screen and when player dies.

If your game needs more than one scoreboard, create aditional stats, and use the "SCOREBOARD" field to sort them.


UNLOCK ACHIEVEMENTS


We ask you to implement at least 15 achievements for the game.
You'll first need to create the achievements using the developer console.

There are two types of achievements:


For the first case, you just need to create the achivement with this information:


And add this line to the part of code where the event occurs:

Kiz10API.submitAchievProgress(ACHIEV_CODE, 1);


NOTE: For the "points" field, use this rule:


Please keep the total points arround 500.

The second case of achievements are the "progresive" ones. You can implement these the same way that the previous ones (just unlock when the goal is reached), but it looks better if the portal can show the player progression. To do this, you should set the number to reach in the GOAL field of the achievement. You'll also need to store a variable in your game with the current number to send it when applies.
IMPORTANT: the portal does NOT add the values you send, the game must allways send the current amount.

You may even want to create more than one achievement regarding the same stat. If this is the case (for example "kill 20 enemies", "kill 100 enemies", ...) create also a stat for them, similar to the "score" one, but with type=1, scoreboard=0 and a proper code, and indicate this stat code in the STAT field of every achievement which uses it.

Then you'll just need to put this line in the relevant part of your code:

Kiz10API.submitStat(STAT_CODE, stat_value);

And the portal will check automatically all the achievements regarding that stat code.
Note: you can use the "score" stat to set achievements too.
For the achievements which don't share stat with others you don't need to create any stat, just create the achievement like in the previous case (STAT field empty), and use this code to send the progress:

Kiz10API.submitAchievProgress(ACHIEV_CODE, achiev_progress);

Please, again keep low the number of calls. For example, dont call submitAchievProgress("killed_enemies", killed) every time the player kills an enemy if he/she will kill one of them every second. You can call it once every 10 times, for example, depending how fast it can be.