Integrate the Skillz SDK

Now that your game has been migrated to Cordova, the desired platforms have been added, and the Skillz Cordova plugin has been installed, it’s time to add multiplayer tournaments to the game using the Skillz API.

After following these steps, you will be able to enter the Skillz portal from your game, join and play in tournaments, finish those games, and return to the Skillz portal while reporting scores to our server.

Step 1: Load required Javascript files

The Skillz Cordova plugin has two Javascript files that need to be loaded in index.html: SkillzCordova.js and SkillzDelegateCordova.js. These files are copied to the platform_www/ folder for each platform when the plugin is installed. Add the following lines in index.html to load them:

<script src="SkillzCordova.js"></script>
<script src="SkillzDelegateCordova.js"></script>

Step 2: Lock your game's orientation

Due to certain features of the SDK, your app must stick with a single orientation – either Portrait or Landscape. Refer to Cordova's documentation for instructions on how to do this globally.

Step 3: Initialize and launch Skillz

Next, Skillz will need to be initialized. In the relevant portion of your game, add:

SkillzCordova.skillzInit('12345', 'SkillzSandbox');

The first argument is a string representation of your game's ID on the Developer Console, while the second argument is a string to specify the environment Skillz will run in. Possible values are 'SkillzSandbox' and 'SkillzProduction'. Pass in the former as you are developing and testing your integration, and pass in the latter when your game is ready to go live.

Now, launch Skillz to let it take over:

SkillzCordova.launchSkillz();

Step 4: Handle a match start

Skillz will notify your game before a match will begin. When that happens, your game should load any necessary data, state, etc. To do so, you will need to modify the platform_www/SkillzDelegateCordova.js class under each platform. It will look similar to:

class SkillzDelegateCordova {
constructor() {
this.matchInfo=null;
}

// void
static onMatchWillBegin(matchInfoString) {
// This block of code will be called when the user is about to begin a match.
// You can use this match object to instantiate variables in your game.

const matchInfoObject=JSON.parse(matchInfoString);

const message='SkillzDelegateCordova: onMatchWillBegin was called. Here is the match information:'.concat(
JSON.stringify(matchInfoObject)
);

console.log(message);

this.matchInfo=matchInfoObject;
}

// void
staticonSkillzWillExit() {
// This block of code will be called when the user exits out of the Skillz UI.
console.log('SkillzDelegateCordova: onSkillzWillExit was called');
}

staticgetMatchInfo() {
return this.matchInfo;
}
}
You will need to display your game from the onMatchWillBegin method. The matchInfoString parameter is a JSON object that will contain the match parameters that are specified in the Developer Console for the tournament type being played. These game parameters can change the experience of each tournament since you can pass these parameters onto your code and use them to diversify the gaming experience.

For more information on match parameters, see this article.

warning.png Warning

Cordova treats the Android Studio and Xcode projects as build artifacts - they will be regenerated any time you modify the Cordova project and push those changes. When this happens, the Skillz Cordova Plugin will copy SkillzDelegateCordova.js to the platform_www/ folder for each platform. In turn, all changes made that you have made to this file will be lost.
 
To mitigate this issue, it is recommended that you keep a copy of this file with your changes in a safe location in your project, and copy it to platform_www/ every time a platform project is regenerated. Furthermore, you can automate this by writing a script that is run in Cordova's before_compile hook. See the documentation on Cordova Hooks for more information.

Step 5: Implementing Skillz Random for fairness

Skillz matches must be fair for all players. To this end, randomly-generated levels and game conditions should be synced across all participants. All players within a match must start with the same game state. For example, in a game of bubble shooter, the starting board and the sequence of bubbles must be identical for both players.

Bubble_Shooter.png

To facilitate this, use either one of the following methods:

SkillzCordova.getRandomFloat(completion)
SkillzCordova.getRandomNumberWithRange(min, max, completion)
 
The completion parameter is a function (that has a single parameter representing the returned random number) that you must pass in as an argument. Cordova is asynchronous by nature so the function will be called at a later time.

Step 6: Reporting the match score

In order to prevent cheating, Skillz requires the user’s current score be reported back on a regular basis within your game loop. To do this, call the following method when the user’s score is updated:

SkillzCordova.updatePlayersCurrentScore(score, matchId)
 NOTE: You can get the current match ID via SkillzDelegateCordova:
SkillzDelegateCordova.getMatchInfo().id

This should be called fairly often. Once per game loop cycle is a good rule.

When the match ends, you can report the player’s final score to Skillz and bring them back inside the Skillz UI by using the following method:

SkillzCordova.reportScore(score, matchId)

Be sure to do any required cleanup in your game before reporting the final score.

Step 7: Aborting a match

There are instances in which a player might want to voluntarily “abort” (forfeit) a match in progress. If you decide to allow this, use the following method to record an aborted score for the match:

SkillzCordova.abortMatch(matchId)

Next Steps

Congratulations! After completing the above steps, the Skillz SDK should be properly integrated into your project.

The next steps are to test in Sandbox, then move to Production!