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


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 started and finished:

PokiSDK.gameLoadingStart();
// 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.

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

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.

// gameplay stops
// show rewarded menu
// when user 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();
    // fire your function to continue to game
});

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.