Skip to content



Before we start with how, here is a quick overview what we expect you to implement from 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. Adding the Poki SDK Extension

GameMaker 2

First add the extension to your library via the GameMaker Marketplace.

GameMaker Marketplace

  1. Open GameMaker
  2. Click in the menu on Marketplace
  3. Click Open Marketplace
  4. Search for poki
  5. Click on the Poki SDK
  6. Now press the green Add to Account button

Next we need to download it:

  1. Click in the menu on Marketplace
  2. Click My Library
  3. select the Poki SDK
  4. In the far right screen press Download

GameMaker 1

Download and install the PokiSDK:

  1. Download the Poki SDK extension from the GameMaker MarketPlace.
  2. Open Game Maker
  3. In the resource tree right-click Extensions and select Import Extension
  4. Select the downloaded PokiSDK.GMEZ.

2. Setting up the index.html template

The PokiSDK requires you to send information about the loading progress of your game. Because the loading experience happens before the actual game starts we need to make some changes to the index.html to make sure everything is set up correctly.

  1. If you don’t use an index.html template yet
    1. Run your game as HTML5
    2. Open page source (right click Inspect Source)
    3. Copy all of the contents into a new file named index.html
    4. In GM resource tree, right-click Included Files, pick Insert Included File, pick your index.html file.
    5. In resource tree, pick Options > HTML5 > General > Advanced > included file as index.html, and point it to your file. Don’t forget to click OK! (in GMS1, this is in Global Game Settings > HTML5 > General)
  2. Right-click index.html in Included Files, pick Show in Explorer / Show in Finder
  3. Open the file with a code editor, or, failing that, a plaintext editor
  4. Find the line on the bottom that says
<script>window.onload = GameMaker_Init;</script>

and replace it with

<!-- Poki start -->
<script src="//"></script>
<script>(function() {
    function fin(ok) {
        window.PokiSDK_OK = ok;
    window.addEventListener("load", function(_) {
        window.PokiSDK_loadState = 0;
        if (window.PokiSDK) {
            PokiSDK.init().then(function() {
        }).catch(function() {
        } else {
            window.PokiSDK = null;
        //PokiSDK.setDebug(true); <-- Uncomment this line for debugging
<!-- Poki end -->

3. Setting up the Loading Bar

I'm not using a Custom Loading Bar:

  1. In GM resource tree, pick Options > HTML5 > General > Loading bar extension, change to poki_loadbar. Don’t forget to click OK!
  2. Create a new script called gmcallback_poki_loadbar, paste the following in there:
/// gmcallback_poki_loadbar(context, current, total, width, height, img_width, img_height)
var r;
var pc = argument1; // progress current
var pt = argument2; // progress total
var cw = argument3; // canvas width
var ch = argument4; // canvas height
var iw = argument5; // image width
var ih = argument6; // image height

//All these arguments can be used to customize the full loading exprience.
//This example is very basic and only uses a few arguments

switch (argument0) {
    case "image_rect": // ([left, top, width, height] in pixels)
        r[0] = (current_time div 500) mod 4 * (iw div 4);
        r[1] = 0;
        r[2] = 0;
        r[3] = 0;
        return r;
    case "background_color": return "#79FEE7";
    case "bar_background_color": return "#79FEE7";
    case "bar_foreground_color": return "#009CFF";
    case "bar_border_color": return "#002B50";
    case "bar_width": return round(cw * 0.6); // (px)
    case "bar_height": return 20; // (px)
    case "bar_border_width": return 2; // (px)
    case "bar_offset": return 0; // (px from image)
return undefined;

Coloring the Loading Bar

Tweak the colors/parameters to your liking (see the linked blog post for reference)

I am using a Custom Loading Bar:

  1. Open your custom loading bar JS extension in a code editor, insert the following at the start of the loading bar function:
// current, total are your function arguments
if (window.PokiSDK) {
    if (window.PokiSDK_loadState == 0) {
        window.PokiSDK_isLoading = 1;

    PokiSDK.gameLoadingProgress({ percentageDone: current/total });
    if (current >= total && window.PokiSDK_loadState != 2) {
        window.PokiSDK_loadState = 2;


Phew, now that's out of the way lets continue with the fun stuff!

Next steps

1. Integrating the functions

We require you to implement the following functions:


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.


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.


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.


poki_commercial_break(callback_script, custom_value)

Example usage:

poki_commercial_break(my_callback_script, "CommercialBreak")

and then create a script called my_callback_script with the following code:

if (argument1 == "CommercialBreak") {
    show_message("Commercial Break done!");

You can reuse the my_callback_script for other callbacks as well. Based on argument1 you can decide to do different things. For example for a rewarded break you can decide to give the user a reward. See

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


poki_rewarded_break(callback_script, custom_value)

Example usage:

poki_rewarded_break(my_callback_script, "RewardedBreak")

and then create a script called my_callback_script with the following code:

if (argument1 == "RewardedBreak") {
        show_message("User should get a reward!");
        show_message("User cancelled or closed the ad, so no reward!");

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.

//<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)


2. Integrate game logic

Extra logic is required between triggering a commercialBreak and finishing it. Some things to keep in mind when triggering ads:

  1. All adds need to be triggered via user interaction, e.g. a click of a button or a keyboard key press
  2. All audio must be muted during advertisements
  3. Gameplay must be paused during advertisements

This is a basic example displaying this:

//First we mute audio
//Then we trigger the commercialBreak
poki_commercial_break(callback_script, "CommercialBreak")

and then this in the callback_script

if (argument1 == "CommercialBreak") {
    //Now the commercialBreak is done
    show_message("Commercial Break done!");
    //We unmute the audio

3. Sitelocking


Protecting your game from theft is very important to us.

In order to sitelock your game please include our sitelock code in the index.html of your game inside the function fin(ok){} as a seperate line. This line of code will auto-execute and bounce the page back to whenever the window.location doesn't equal, or localhost:.

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

4. Full example

You can download a full working GMZ sample of everything described here.

QA Tool - Testing your game

To test your implementation you must use our QA Tool tool to upload your game. This will not work offline or you must use a local server.

That's it

Congrats! You’ve now successfully implemented the Poki SDK. Please send the following to 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!

Big thanks to YellowAfterlife for helping us with this extension!