PokiSDK: HTML5 | Poki Documentation

1. Initialize the SDK

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

<script src="https://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, something went wrong, load your game anyway");
    // fire your function to continue to game
});

2. Implement the game loading logic

To provide an accurate conversion to play metric for your game, fire the following event when your loading has finished:

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

3. Implement the gameplay events

Use the gameplayStart() event to describe when players are playing your game (for example, level start and unpause).

Use the gameplayStop() event to describe when players aren't playing your game (for example, level finish, game over, pause, or 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 display video ads and should be triggered on natural breaks in your game. Throughout the rest of your game, we recommend calling commercialBreak() before every gameplayStart(), whenever the player has shown 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 Not every commercialBreak() triggers an ad. Poki's system decides when a player is ready for another ad, so feel free to signal as many commercial break opportunities as possible.

5. Implement rewardedBreak

Rewarded breaks let a player choose to watch a rewarded video ad in exchange for a benefit in the game (for example, more coins). When using rewardedBreak(), 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
});

Ad timing A rewardedBreak() affects the timing of commercialBreak(): when a player interacts with a rewarded break, our system's ad timer resets so they don't immediately see another ad.

Final steps

Disable sound and input during ads

Make sure that audio and keyboard input are disabled during commercial breaks, 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 });

Shareable URLs & URL manipulation

Creating shareable URLs and changing the Poki.com URL

You can create a shareable 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, 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

Moving the Poki Pill on mobile

On mobile, you can reposition the Poki Pill slightly to better fit your game UI using PokiSDK.movePill(topPercent, topPx).

topPercent is a number between 0 and 50 and sets the pill's vertical position as a percentage from the top of the game area.
topPx is an additional pixel offset applied on top of topPercent (positive moves it down, negative moves it up).

You can't move the pill lower than 50% of the game area (the game bar at the bottom is not included in this area).

The default position is PokiSDK.movePill(0, 24).

Poki Pill size

46px × 62px on screens narrower than 1211px.
92px × 64px on screens 1211px wide or wider.

// Move the pill 100 pixels above the center of the game.
PokiSDK.movePill(50, -100);

Upload and test your game in Poki for Developers

Congrats, you've successfully implemented the PokiSDK! Now upload your game to the Poki Inspector and test it there. 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.