Skip to content

HTML5

Checklist

Before we start with how, let’s quickly recap what we expect when implementing our SDK:

  1. Trigger a gameplayStart() when the user can actually control the game (e.g. start of a level) and a gamePlayStop() when the gameplay stops.

  2. Implement 2 commercialBreak() positions in the game.

  3. Implement at least 1 rewardedBreak() position in the game.

  4. Implement the loading events gameLoadingStart(), gameLoadingProgress(), gameLoadingFinished().

  5. Implement 1 happy moment in the game happyTime().

Common mistakes:

  • Remember to block gameplay and gameplay audio during a commercialBreak or rewardedBreak

  • Fire the gameplayStart and gameplayStop at the right moments

  • Make sure you are using the latest version of the SDK

Basic implementation

1. Include our Javascript SDK

Add the following HTML within the <head> tags of your game HTML:

<script src="//game-cdn.poki.com/scripts/v2/poki-sdk.js"></script>

2. Initialize the SDK

Initialize the SDK at the start of your game with the following Javascript:

PokiSDK.init().then(
    () => {
        // successfully initialized
        console.log("PokiSDK initialized");
        // continue to game
    }   
).catch(
    () => {
        // initialized but the user has an adblock
        console.log("Adblock enabled");
        // feel free to kindly ask the user to disable AdBlock, like forcing weird usernames or showing a sad face; be creative!
        // continue to the game
    }   
);
PokiSDK.setDebug(true);

Debug mode

We initialize the SDK with debug set to true, this is necessary for ads to be shown in a local environment, and will make sure debug logs are sent to the console. This parameter should be omitted or set to false for production builds.

3. Triggering your first commercial break

In order to display advertisements in your game, you need to tell us what the right moments are to display ads. Good moments are natural breaks in your game (e.g. entering a menu, a user clicking restart level, etc.). Please provide us with at least 2 of these moments.

PokiSDK.commercialBreak()
.then(
    () => { //you can also use a normal function here
        console.log('End of commercial break');
    }
);

Next steps

1. Integrating the functions

We require you to implement the following functions:

Gameplay

The gameplayStart event should be triggered when a level starts or when the user can interact with the actual game(i.e.not in a menu, unless the game is the menu for example in a clicker game).

The gameplayStop should be triggered every time the gameplay halts, like in the case of death, going back to a menu, etc.

Pause

Heads up! Don’t forget to trigger a gameplay stop when the user pauses the game and a gameplay start when they choose to resume.

PokiSDK.gameplayStart();
PokiSDK.gameplayStop();

Commercial break

As described earlier, commercial breaks are used to display advertisements and should be triggered on natural breaks in your game. We require you to implement at least 2 breaks. Generally, we recommend placing one commercial break in the beginning of the game (after a first selection screen for instance) and then after the first gameplay (on ‘Play Again’ or ‘Restart’ for example). Your Poki contact will also help with properly identifying these moments.

PokiSDK.commercialBreak().then(<function>);
//<function> is of type Function and will be triggered when the commercial break is finished.

//Example:
PokiSDK.commercialBreak().then(
    () => {
        console.log("Commercial Break finished");
    }
);

Rewarded break

Rewarded breaks allow for a user to choose to watch a rewarded video ad in exchange for a certain benefit in the game (e.g. more coins, etc.)..

PokiSDK.rewardedBreak().then(<function (bool)>);
//<function (bool)> is of type Function and requires one Bool parameter, this will trigger when the rewarded break is finished

//Example:
PokiSDK.rewardedBreak().then(
    (withReward) => {
        console.log(`Should the user get a reward? ${withReward}`)
    }
);

Loading

We would like to know when and what your game is loading and for this we ask you to implement the following 3 functions.

PokiSDK.gameLoadingStart();
PokiSDK.gameLoadingFinished();
PokiSDK.gameLoadingProgress(<data>);
/*<data> is of type Object and has the following properties:
percentageDone: <float between 0.0 - 1.0>,
kbLoaded: <int of the total of kb loaded>,
kbTotal: <int of the total size in kb>,
fileNameLoaded: <string the name of the file loaded>,
filesLoaded: <int of the number of files loaded>,
filesTotal: <int of the total number of files>,
*/

//Example:
var data = {};
data.percentageDone = sizeLoaded/sizeTotal;
PokiSDK.gameLoadingProgress(data);

Game Loading Progress

For gameLoadingProgress() the minimum requirement is to implement percentageDone OR kbLoaded & kbTotal.

Happy time

We would love to know what you believe to be the happy moments in your game. This could be the unlocking of a new car, or triggering a super combo in the game. We will use this in order to display cool animations on our portals. Please integrate at least one happy time.

PokiSDK.happyTime(<intensity>);
//<intensity> is of type float between 0.0 and 1.0 and allows us to scale the intensity of happiness. You can for instance on a small happy moment trigger a happyTime(0.1) and on an extremely happy moment trigger happyTime(1.0)

//Example:
PokiSDK.happyTime(0.5);

2. Integrate game logic

It's very likely that some extra logic is required between triggering a commercialBreak and finishing it. For example if your game has music, this should be muted during the break like so:

function triggerRestartGame() {
    muteMusic();
    PokiSDK.commercialBreak().then(restartGame);
}

function restartGame(){
    //reset game here
    unMuteMusic();
}

This extra logic not only applies to music. Please keep in mind that for the best possible user experience, nothing in your game should interfere with the ad.

3. Sitelocking

Sitelocking

Protecting your game from theft is very important to us.

In order to sitelock your game please include our sitelock code anywhere in the initialization of your game. This line of code will auto-execute and bounce the page back to Poki.com whenever the window.location doesn't equal qa.poki.com,qa-files.poki.com or localhost:.

Please request this piece of code from your Poki contact. If we make it public it’dbe easy for tech-savvy people to remove. :)

4. Full example

If your entire JS game would be contained in one file, the full implementation would look something like this:

var Init = function () {
   PokiSDK.init().then(StartLoading)
   .catch(
       () => {
           console.log(':( adblock');
            StartLoading();
       }
    );
   PokiSDK.setDebug(true); // remove this line when submitting to us
}

var StartLoading = function () {
   PokiSDK.gameLoadingStart();
   // Load the game!

   //[... do LoadingProgress()  ]

   // When all files are loaded
   LoadingComplete();
   // Loading complete
}
var LoadingProgress = function() {
   // This function does nothing but show how this function should be called
   PokiSDK.gameLoadingProgress({
       percentageDone: this.progress,
       kbLoaded: this.kbLoaded,
       kbTotal: this.totalFileSize,
       fileNameLoaded: this.fileName,
       filesLoaded: this.filesLoaded,
       filesTotal: this.totalFiles,
   });
}
var LoadingComplete = function() {
   // We're done loading!
   PokiSDK.gameLoadingFinished();
   // Lets open the menu
   openMainMenu();
}

var openMainMenu = function*(){
   //Opening the main menu is a nice natural break moment of the game, so let’s first call a break
   gamePause();
   PokiSDK.commercialBreak()
   .then(() => {
       //Show the menu
       //[.. user clicks on StartGame]
       continueGame();
       StartGame();
   });

}

var StartGame = function () {
   console.log("Starting a new round!");
   PokiSDK.gameplayStart();

    //[... do all the gameplay stuff];

    //Yes! We made a super combo!
   PokiSDK.happyTime(0.8); // scale is 0.0 to 1.0

    // We died but we can get one more shot by watching a rewarded video
    PokiSDK.rewardedBreak().then(
        (withReward) => {
            if(withReward){
                console.log("Revive!");
                //resume game
            }
        }

    )
    // ahh we died again, let’s restart
   RestartLevel();
}

var RestartLevel = function(){
   // we failed the level, let’s close this gameplay session and trigger a break
   gamePause();
   PokiSDK.gameplayStop();
   // we closed the gameplay now let’s trigger the break
   PokiSDK.commercialBreak();
   .then(() => {
       // we restart the level
       continueGame();
       StartGame();
   });
}

var gamePause = function () {
   console.log("Starting break");
   //muteMusic();
   //pauseGamePlay();
}

var continueGame = function () {
   console.log("Break completed");
   //unMuteMusic();
   //resumeGameplay();
}

You can find a full working sample of everything described here.

QA Tool - Testing your game

To test your implementation you can use our QA Tool.

That's it

Congrats! You’ve now successfully implemented the Poki SDK. Please send the following to creatorsupport@poki.com or to your Poki contact:

  • Final game build (Production Build)
  • Image assets:
  • Thumbnail (preferably 628x628 px, PNG-file)
  • Character-image (Large size, PNG-file)
  • Game-title (PNG-file)
  • Main background of the game (PNG-file)
  • 2 to 3 game-items (PNG-files)

We’ll then QA the game and let you know if there are any issues before putting it live!