!!! THIS SDK IS UNMAINTENED PLEASE REFER TO THIS ONE INSTEAD https://github.com/D-Mobilelab/game-sdk/ !!!

GamifiveSDK 2.x.x

This is the how-to for game developers for integrating GamifiveSDK into their games.

Note: the SDK was previously called GamefiveSDK, now it has been aliased as GamifiveSDK so both names can be used.

Instructions

1) Including GamifiveSDK

Debug (use it while developing or to test the implementation on your own)

<script src="//static.newton.pm/js/v2.2.3/newton.min.js"></script> 
<script src="http://s.motime.com/js/wl/webstore_html5game/gfsdk/2.x.x/debug/gfsdk.js"></script>

(See https://github.com/BuongiornoMIP/GamifiveSDK/wiki/Debug-mode for further details;)

Prod (before sending us the package remove newton and switch to the production build)

Include the minified sdk within a SCRIPT tag with id 'gfsdk', inside HEAD tag of your HTML code game before sending us the package:

<script id="gfsdk" src="http://s.motime.com/js/wl/webstore_html5game/gfsdk/dist/gfsdk.min.js"></script>

2) Initializing the SDK

The SDK can be initialized calling its init method with a param object as a configuration parameter. Here's a brief description of the accepted configuration variables:

• lite (boolean): toggles lite mode, if true a reduced set of functionalities is used, in particular the GameOver screen is not loaded. Lite mode is useful for integrating the SDK into level-based games, so that the game's flow won't get interrupted by the gameover screen. Normal (non-lite) mode, instead, is meant to be used for other kind of games, i.e. those that feature an endless gameplay experience;
• moreGamesButtonStyle (object): defines the css style of the "more games" button. If present, the button will be displayed (you can pass an empty object for using the default style). If not present, the button won't be displayed.

Example

GamifiveSDK.init({ 
	lite: false,
	moreGamesButtonStyle: { } // shows more games button with default style
});

The init method will store the configuration parameters into the module and perform the operations needed for properly initializing the SDK (if you are not using the lite version).

Please note that the init method will not create a new instance of GamifiveSDK, but it will just reset its configuration; in fact you can have only one instance of GamifiveSDK because it's implemented as a singleton.

3) Starting a session

A session is a continued user activity like a game match. Ideally a session begins everytime the player starts playing a new game and his score is set to zero.

Lite Mode

For starting a session in lite mode you just have to call GamifiveSDK.startSession().

Normal (non-lite) Mode

For starting a session you have to:

1. move the start of the game into GamifiveSDK.onStartSession() method
2. call GamifiveSDK.startSession() method to start the game

Here's an example:

Before, without GamifiveSDK

// your method to start a game match
function startMatch(){ /* ... */ }

<!-- button to start a game match -->
<button onclick="startMatch()">START MATCH</button>

After, with GamifiveSDK

// your method to start a game match 
// (don't change it)
function startMatch(){ /* ... */ }

// onStartSession include startMatch() method
GamifiveSDK.onStartSession(function() {  
  startMatch();
});

// new method to call GamifiveSDK.startSession()
function playGame(){
  GamifiveSDK.startSession();
}

<!-- button to start a game match -->
<button onclick="playGame()">START MATCH</button>

Here's a simple schema:

4) Ending a session

Ideally a session ends when the player cannot go on with his match and must play again from the beginning. Usually - but not necessarily - endSession occurs in the 'Game Over' state.

Lite Mode

To end a session in lite mode, you have to:

1. call GamifiveSDK.endSession() method. You should call it passing an object as parameter - this object can contain:
   • an attribute score, which is the score realized by the player during the game session. This value must be a number (not string).
   • an attribute level, which is the level reached by the player during the game session. This value must be a number and it will be saved for later use in the sdk configuration (you can retrieve it into GamifiveSDK.getConfig().user.level).
   • No attributes at all: in this case the SDK will only save the game session (starting and ending time).

Here's a simple schema of the flow you have to follow for saving and retrieving the level reached by the player.

Normal (non-lite) Mode

To end a session in non-lite mode, you have to:

1. call GamifiveSDK.endSession() method. You should call it passing an object as parameter - this object can contain:
   • an attribute score, which is the score realized by the player during the game session. This value must be a number (not string).
   • No attributes at all: in this case the SDK will only save the game session (starting and ending time).
2. remove your game over screen - you have to remove your game over screen because the SDK also displays a game over screen. If you don't remove your game over screen, there will be two duplicate screens

// call this method when a user ends a game session
var scoreGame = 7888;
GamifiveSDK.endSession({
	score: scoreGame
});

Other methods

saveUserData

Saves an Object containing the player's progress.

// the structure of this object is just an example
var playerProgress = { 
    level1: { 
        unlocked: true, 
        stars: 3
    }, 
    level2: {
        unlocked: false, 
        stars: 0
    } 
};
  
// saves the object containing the player's progress
GamifiveSDK.saveUserData(playerProgress); 

GamifiveSDK.saveUserData internally uses JSON.stringify and actually saves the object as a string, but this is an internal procedure and you MUST pass an object, not a JSON string, as a parameter to GamifiveSDK.saveUserData.

loadUserData

Retrieves the JSON string containing the player's progress and returns it as a JavaScript Object. This method make a call to our server and **must be called AFTER GamifiveSDK.init();**

// returns an object containing the player's progress

GamifiveSDK.init();
var userProgressInGame = {};
GamifiveSDK.loadUserData(function(userProgressSaved){
    if(userProgressSaved){
        //else load userprogress in the game
        userProgressInGame = userProgressSaved;
    }
    //start the game with the userProgress loaded
});

clearUserData

Deletes the player's progress.

// the previously saved progress is deleted
GamifiveSDK.clearUserData(); 

showMoreGamesButton

Shows a built-in more games button. If no parameters are passed, the button is created with default style, otherwise the object passed as parameter will be used as a custom style.

// display the button with default style:
GamifiveSDK.showMoreGamesButton(); 

// display the button with custom style:
GamifiveSDK.showMoreGamesButton({left: '2px', height: '44px'}); 

hideMoreGamesButton

Hides the more games button (if it was previously shown).

GamifiveSDK.hideMoreGamesButton(); 

goToHome

Redirects to Gamifive's Homepage. Call this function when your more games button is clicked.

// perform a redirect to the homepage

GamifiveSDK.goToHome(); 

getAvatar

You can get the user's avatar by calling GamifiveSDK.getAvatar().

var avatar = GamifiveSDK.getAvatar();

It returns an object containing two fields:

• src: base64 of avatar
• name: name of avatar file

We recommend using a src field for showing the avatar in the game.

getNickname

You can get the user's nickname by calling GamifiveSDK.getNickname().

var avatar = GamifiveSDK.getNickname();

It returns a string equal to the nickname of the user.

Migrating apps featuring older versions of the SDK to v0.4

Migrating app using v0.3 to v0.4 of the SDK

Apps featuring v0.3 of the SDK can be migrated to v0.4 by explicitly adding a call to the Gamifive.init method before using any of the module's features.

Previously, the init method was called implicitly, now it must be called by the game developer for correctly configuring the SDK by passing a config object with the desired parameters.

Migrating app using v0.1 to v0.4 of the SDK

Apps featuring v0.1 of the SDK can be migrated to v0.4 by explicitly adding a call to the Gamifive.init method before using any of the module's features.

Previously, the init method was called implicitly, now it must be called by the game developer for correctly configuring the SDK by passing a config object with the desired parameters.

Moreover, since the functionalities implemented in v0.1 correspond to the "lite" version of v0.4, you must declare lite: true in the configuration parameters passed to the init method.

Example

GamifiveSDK.init({ 
	lite: true
});

Lite Mode

We remind you that in order to use GamifiveSDK in lite mode, you have to call Gamifive.init with lite: true in the configuration argument.

GamifiveSDK.init

GamifiveSDK.onStartSession

Register a callback function any time a session start

GamifiveSDK.onStartSession(function yourFunction(){ //do things everytime a session start });

GamifiveSDK.startSession

If GamifiveSDK.init function was called before calling GamifiveSDK.endSession, then the following debug message is displayed:

    ["GamifiveSDK", "OK", "init has been called correctly"]

Otherwise, the following error message is displayed, specifying that the error was due to a missing or unsuccessful call to init.

    GamifiveSDK,ERROR,init has not been called

GamifiveSDK.endSession

If GamifiveSDK.startSession function has been called before calling GamifiveSDK.endSession, then the following debug message is displayed:

    ["GamifiveSDK", "OK", "startSession has been called correctly"]

Otherwise, the following error message is displayed, specifying that the error was due to a missing or unsuccessful call to GamifiveSDK.startSession.

    GamifiveSDK,ERROR,startSession has not been called

If the score was passed in the proper way, then the following debug message is displayed:

    ["GamifiveSDK", "OK", "score has been set correctly"]

Otherwise, the following error message is displayed:

    GamifiveSDK,ERROR,missing score value

Normal (non-lite) mode

GamifiveSDK.init

No debug messages are displayed when calling GamifiveSDK.init.

GamifiveSDK.onStartSession

If the variable passed to onStartSession as an argument is a function, then the following debug message is displayed:

     ["GamifiveSDK", "OK", "callback function has been set correctly"]

If such argument is not passed or it is not a function, then the following error message is displayed:

    GamifiveSDK,ERROR,missing or illegal value for callback function

GamifiveSDK.startSession

If init and onStartSession were called before calling GamifiveSDK.startSession, then the SDK is now correctly configured to start a session and following debug messages are displayed:

    ["GamifiveSDK", "OK", "init has been called correctly"]
    ["GamifiveSDK", "OK", "onStartSession has been called correctly"]

Otherwise:

if init was not called, the following error message is displayed:

    GamifiveSDK,ERROR,init has not been called

if onStartSession was not called, the following error message is displayed:

    GamifiveSDK,ERROR,onStartSession has not been called

GamifiveSDK.endSession

If the startSession function has been called before calling GamifiveSDK.endSession, then the following debug message is displayed:

    ["GamifiveSDK", "OK", "startSession has been called correctly"]

Otherwise, the following error message is displayed, specifying that the error was due to a missing or unsuccessful call to startSession.

    GamifiveSDK,ERROR,startSession has not been called

If the score was passed in the proper way, then the following debug message is displayed:

    ["GamifiveSDK", "OK", "score has been set correctly"]

Otherwise, the following error message is displayed:

    GamifiveSDK,ERROR,missing score value

Full implementation example

GamifiveSDK.onStartSession(function(){
    // do somenthing everytime a session starts
});

// You can run this on body onload event or on document content load or as soon as you can
GamifiveSDK.init({ lite: true }); // could be an empty object: default lite = false

// your userData empty structure
var emptyStructure = {
    level1: { 
        unlocked: false, 
        stars: 0,
        score: 0
    }, 
    level2: {
        unlocked: false, 
        stars: 0,
        score: 0
    } 
}

var userProgressInGame = {};
GamifiveSDK.loadUserData(function(userProgressSaved){
    if(userProgressSaved){
        //else load userprogress in the game
        userProgressInGame = userProgressSaved;
    }
    //start the game with the userProgress loaded
});

GamifiveSDK.startSession();

// Persist user data when somenthing happens. Change in settings or end of the level
GamifiveSDK.saveUserData({ 
    level1: { 
        unlocked: true, 
        stars: 2,
        score: 300
    }, 
    level2: {
        unlocked: false, 
        stars: 0,
        score:0
    } 
});

GamifiveSDK.endSession({ score: 300, level: 1 });

Set the debug environment

1. Include the debug SDK version in your index.html do not forget to change debug with dist in the script tag before send the package

Debug (while testing on local)

    <script src="http://static.newton.pm/js/v2.2.3/newton.min.js"></script> 
    <script src="http://s.motime.com/js/wl/webstore_html5game/gfsdk/2.x.x/debug/gfsdk.js"></script>

Prod (Before sending us the package) without Newton script

    <script src="http://s.motime.com/js/wl/webstore_html5game/gfsdk/dist/gfsdk.min.js"></script>

2. Serve statically the game folder with appsworld.gamifive-app.com as origin

For the second point you need:

2.1 Install NodeJS and NPM in your system.

• Mac Users can follow this guide: http://blog.teamtreehouse.com/install-node-js-npm-mac
• Windows Users can follow this one: http://blog.teamtreehouse.com/install-node-js-npm-windows (Some other of billions guides on the web anyway will be ok)

2.2 Install http-server npm package globally

    npm install http-server -g

2.3 Edit your hosts file

Add this line

   127.0.0.1 local.appsworld.gamifive-app.com

into your hosts file

/private/etc/hosts file (Mac)
C:\Windows\System32\drivers\etc\hosts (Windows)

On Mac you can simply append this line at the end of the file in this way:

sudo -i # Enter the password
sudo echo '127.0.0.1 local.appsworld.gamifive-app.com' >> /private/etc/hosts;
exit

(Guide to edit hosts file on any platform http://www.howtogeek.com/howto/27350/beginner-geek-how-to-edit-your-hosts-file/)

2.4 Serve the gamepath

Serve the gamepath in this way from the cmd line

   http-server <myAwesomeGameFolder> -p 5050 -a local.appsworld.gamifive-app.com

Then open the browser to

    http://local.appsworld.gamifive-app.com:5050/index.html

That's it! Now you can test your implementation of the SDK. Open a issue on github if you encounter any issues