Skip to content

HTML5

Getting started

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(
    () => {
        console.log("Poki SDK successfully initialized");
        // your code to continue to game
        continueToGame();
    }   
).catch(
    () => {
        console.log("Initialized, but the user likely has adblock");
        // your code to continue to game
        continueToGame();
    }   
);
PokiSDK.setDebug(true);

Debug mode

The above example initializes 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. Implement gameLoadingStart and gameLoadingFinished

In order to provide accurate stats, we'd like to know when your game has started to load:

PokiSDK.gameLoadingStart();
// loading
PokiSDK.gameLoadingFinished();

4. Implement gameplayStart and gameplayStop

Use the gameplayStart() event to describe when users are playing your game.

Do: Trigger the first gameplayStart() event when a user first starts playing (e.g. tap, swipe, mouse click, key stroke).

Do: Always trigger gameplayStart() when a user returns to playing after a break (e.g. after game over screen, succes screen, unpause, start of a new level)

Don't: Never call this function in a menu

The gameplayStop() should be triggered every time the gameplay halts, like in the case of a level finish, game over or when going back to a menu, pausing the game, etc:

// menu
PokiSDK.gameplayStart();
// gameplay
PokiSDK.gameplayStop();
// menu

Don't forget to re-trigger gameplayStart

In order to enable accurate stats, don't forget to trigger a gameplayStart again after triggering a gameplayStop, i.e. after a 'pause'.

5. Implement commercialBreak

Commercial breaks are used to display video ads and should be triggered on natural breaks in your game.

As it is mandatory to implement the first commercialBreak() in the beginning of the game right before the first gameplayStart(), please add the following code at the beginning of your game:

PokiSDK.gameplayStop();
PokiSDK.commercialBreak().then(
    () => {
        console.log("Commercial break finished, proceeding to game");
        PokiSDK.gameplayStart();
        // your code to continue to game
    }
);

Throughout the rest of your game, we recommend you implement the commercialBreak() before every gameplayStart(), ie. whenever the user has shown an intent to continue playing (for example on play, restart, level select buttons).

Add as many commercial breaks as you like

Not every single commercialBreak() will trigger an ad. Poki's system will determine when a user is ready for another ad, so feel free to signal as many commercial break opportunities as possible.

About the first commercial break

Remember that the default gameplay state is technically gameplayStop(). Therefore, you don't need to implement a gameplayStop() before the first commercialBreak() event.

Disabling keyboard input and audio during commercial breaks

Make sure that audio and keyboard input are disabled during commercialBreaks, so that the game doesn't interfere with the ad:

muteAudio();
disableKeyboardInput();
PokiSDK.gameplayStop();
PokiSDK.commercialBreak().then(
    () => {
        console.log("Commercial break finished, proceeding to game");
        unMuteAudio();
        enableKeyboardInput();
        PokiSDK.gameplayStart();
        // your code to continue to game
        continueToGame();
    }
);

6. Implement rewardedBreak

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.gameplayStop();
// show menu
// when users selects rewarded option, trigger rewarded break
PokiSDK.rewardedBreak().then(
    (success) => {
        if(success) {
          // video was displayed, give reward
        }
        else {
          // video not displayed, should probably not give reward
        }

        PokiSDK.gameplayStart();
        // your code to continue to game
        continueToGame();
    }
);

7. Prevent page jump

When a player presses space or the arrow keys, the default browser behavior is to emulate scroll. But in a game, we don't want that. It's not noticeable in your development environment because your game is (probably) taking the full window. But on Poki, it will be inside a longer page that can scroll.

Here is a snippet that you can paste in your game to disable this behavior.

window.addEventListener('keydown', ev => {
    if (['ArrowDown', 'ArrowUp', ' '].includes(ev.key)) {
        ev.preventDefault();
    }
});
window.addEventListener('wheel', ev => ev.preventDefault(), { passive: false });

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();
       }
    );

   // remove this line in your production build
   PokiSDK.setDebug(true); 
}

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

   // When all files are loaded
   loadingComplete();
}

var loadingComplete = function() {
   // We're done loading!
   PokiSDK.gameLoadingFinished();

   // Lets start playing
   PokiSDK.commercialBreak()
   .then(() => {
       PokiSDK.gameplayStart();
       startGame();
   });
}

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

    //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.gameplayStop();
    PokiSDK.rewardedBreak().then(
        (success) => {
            if(success){
                console.log("Revive!");
                PokiSDK.gameplayStart();
                revive();
            }
        }

    )
    // 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
   pauseGame();
   PokiSDK.gameplayStop();
   // we closed the gameplay now let’s trigger the break
   PokiSDK.commercialBreak()
   .then(() => {
       // we restart the level
       unPauseGame();
       PokiSDK.gameplayStart();
       startGame();
   });
}

var pauseGame = function () {
   console.log("Starting break");
   museAudio();
   disableKeyboardInput();
}

var unPauseGame = function () {
   console.log("Break completed");
   unMuteAudio();
   enableKeyboardInput();
}

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

QA Tool - Testing your game

Now test your SDK implementation via our QA tool. Make sure to send us the log of your QA session by downloading it at the bottom of the page and sending it to developersupport@poki.com along with the build.

Final deliverables

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

  • Final game build (Production Build, so no debug-version)
  • QA log
  • Image assets:
    • Thumbnail (preferably 628x628 px, PNG)
    • Important: your thumbnail is an important factor in generating traffic. Thumbnails will show in 94x94px, 204x204px and 314x314 px. Please make sure your thumbnail sparks interest and is a good reflection of your game in all three sizes.
  • Marketing assets:
    • Character image (Large size, PNG)
    • Game title (PNG)
    • Main background of the game (PNG)
    • 2 to 3 game items (PNG)

Protecting your game from theft

In order to sitelock your game you may 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:. For security reasons, this piece of code is not public, so please request it from your Poki contact.

That's it

We’ll check your QA report and if all good, you'll be notified that your game can go live!