Skip to content

html5-banner

PokiSDK - HTML5

1. Initialize the 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>

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

PokiSDK.init().then(() => {
    console.log("Poki SDK successfully initialized");
    // fire your function to continue to game
}).catch(() => {
    console.log("Initialized, but the user likely has adblock");
    // fire your function to continue to game
});


2. Implement the game loading logic

In order to provide an accurate conversion to play metric for your game, please fire the following events when your loading has finished:

// fire loading function here
PokiSDK.gameLoadingFinished();


3. Implement the gameplay events

Use the  ๐ŸŽฎ gameplayStart()  event to describe when users are playing your game (e.g. level start and unpause).

Use the  โ›” gameplayStop()  event to describe when users aren’t playing your game (e.g. level finish, game over, pause, quit to menu).

// first level loads, player clicks anywhere
PokiSDK.gameplayStart();
// player is playing
// player loses round
PokiSDK.gameplayStop();
// game over screen pops up


4. Implement commercialBreak

Commercial breaks are used to display video ads and should be triggered on natural breaks in your game. Throughout the rest of your game, we recommend you implement the  ๐ŸŽž commercialBreak()  before every  ๐ŸŽฎ gameplayStart() , i.e. whenever the user has shown an intent to continue playing.

// pause your game here if it isn't already
PokiSDK.commercialBreak(() => {
  // you can pause any background music or other audio here
}).then(() => {
  console.log("Commercial break finished, proceeding to game");
  // if the audio was paused you can resume it here (keep in mind that the function above to pause it might not always get called)
  // continue your game here
});

Important information about commercialBreaks

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.


5. 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.). When using  ๐ŸŽฌ rewardedBreak() , please make it clear to the player beforehand that they’re about to watch an ad.

// pause your game here if it isn't already
PokiSDK.rewardedBreak(() => {
  // you can pause any background music or other audio here
}).then((success) => {
    if(success) {
        // video was displayed, give reward
    } else {
        // video not displayed, should not give reward
    }
    // if the audio was paused you can resume it here (keep in mind that the function above to pause it might not always get called)
    console.log("Rewarded break finished, proceeding to game");
    // continue your game here
});

About the rewardedBreak timer

 ๐ŸŽฌ rewardedBreak()  affects the timing of  ๐ŸŽž commercialBreak()  - When a user interacts with a rewarded break, our systemโ€™s ad timer is reset to ensure the user does not immediately see another ad.


Final Steps

Disable sound and input during ads

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

// gameplay stops (don't forget to fire gameplayStop)
// fire your mute audio function
// fire your disable keyboard input function
PokiSDK.commercialBreak().then(() => {
    console.log("Commercial break finished, proceeding to game");
    // fire your unmute audio function
    // fire your enable keyboard input function
    PokiSDK.gameplayStart();
    // fire your function to continue to game
});


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


Sharable URLs & URL manipulation

Creating sharable urls and changing the Poki.com url

You can create a sharable url with the following function:

PokiSDK.shareableURL({}).then(url => {});

// example
const params = {
    id: 'myid',
    type: 'mytype',
    // ... any other param
}

PokiSDK.shareableURL(params).then(url => {
    console.log(url);
    // if run on e.g. https://poki.com/en/g/my-awesome-game it will return https://poki.com/en/g/my-awesome-game?gdid=myid&gdtype=mytype
});

// read further to see how to fetch these params easily from within your game
Reading Poki.com url params

As you might have noticed in the previous topic, the PokiSDK.shareableURL creates a url with parameters that are prefixed with gd. We have created a simple helper function that will easily allow you to read the params.

PokiSDK.getURLParam('<param name>');

// example
const id = PokiSDK.getURLParam('id');
// this will return either the gdid param set on poki.com or the id param on the current url


Upload and test your game in Poki for Developers

Congrats, youโ€™ve successfully implemented the PokiSDK! Now upload your game to Poki for Developers and test it in our QA Tool. When you’re happy with the implementation, send us a review request and we’ll play the game. Feel free to contact us via Discord or developersupport@poki.com if you’re stuck.