PokiSDK - Phaser 3

Made with  at Poki.

Introduction & Features

This is the official Poki Phaser Plugin for Phaser 3. This plugin will automate most of implementing the Poki SDK when making a game with Phaser. You can also check the example in the /example directory.

Features

• Inject & load the Poki SDK for you (asynchronously)
• Trigger the gameLoadingFinished event when loading
• gameplayStart/gameplayStop events fire automatically when your game scene starts and stops
• commercialBreak is requested before gameplayStart is fired
• Disable input and audio during video ads
• Give you easy/global access to the SDK using scene.plugins.get('poki') so you can:
• request a rewardedBreak
• manually make gameplayStart/gameplayStop
• create shareable URLs and move the Poki Pill

1. Initialize the plugin

First, make sure to add the @poki/phaser-3 plugin as a dependency to your project:

$ npm install --save-dev @poki/phaser-3
# or
$ yarn add --dev @poki/phaser-3

Now add the plugin to the Plugins section of your Phaser configuration, for example:

import { PokiPlugin } from '@poki/phaser-3'
// ...
const config = {
  // ...
  plugins: {
    global: [
      {
        plugin: PokiPlugin,
        key: 'poki',
        start: true, // must be true, in order to load
        data: {
          // This must be the key/name of your loading scene
          loadingSceneKey: 'LoadingScene',
          // This must be the key/name of your game (gameplay) scene
          gameplaySceneKey: 'PlayScene',
          // This will always request a commercialBreak when gameplay starts,
          // set to false to disable this behaviour (recommended to have true,
          // see Poki SDK docs for more details).
          autoCommercialBreak: true
        }
      }
    ]
  }
}
// ...
var game = new Phaser.Game(config)

(more info on Phaser’s configuration here)

2. Implement the game loading logic

The Poki Phaser plugin will automatically call   gameLoadingFinished()  if the loadingSceneKey is configured. Please make sure your loading scene is included in the config object.

const config = {
  // ...
  plugins: {
    global: [
      {
        data: {
          loadingSceneKey: 'LoadingScene'
        }
      }
    ]
  }
}

If you do not use a dedicated loading scene, you can also call the event manually after your assets are ready:

const poki = scene.plugins.get('poki')

poki.gameLoadingFinished()

3. Implement the gameplay events

The Poki Phaser plugin will automatically call   gameplayStart()  and   gameplayStop()  if the gameplaySceneKey is configured. Please make sure your gameplay scene is included in the config object.

const config = {
  // ...
  plugins: {
    global: [
      {
        data: {
          gameplaySceneKey: 'PlayScene'
        }
      }
    ]
  }
}

4. Implement commercialBreak

If autoCommercialBreak is enabled, the plugin automatically requests a commercial break before it fires gameplayStart() for your gameplay scene. If your game handles scenes differently, you can request one manually:

const poki = scene.plugins.get('poki')

poki.gameplayStop()
poki.commercialBreak(() => {
  // Optional: ad playback started, pause extra systems if needed.
}).then(() => {
  poki.gameplayStart()
})

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.

const poki = scene.plugins.get('poki')

poki.gameplayStop()
poki.rewardedBreak({
  size: 'medium',
  onStart: () => {
    // Optional: rewarded ad playback started.
  }
}).then((withReward) => {
  if (withReward) {
    // Give the player their reward.
  }

  poki.gameplayStart()
})

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

Additional helpful methods

Execute a function only on initialization

To run code only when the PokiSDK is initialized, you can use the following interface:

const poki = scene.plugins.get('poki') // get the plugin from the Phaser PluginManager

poki.runWhenInitialized((poki) => {
  // This is called after the PokiSDK is fully initialized, or immediately if
  // the PokiSDK has already been initialized.
})

Fire SDK events manually

If your game doesn’t use multiple scenes for gameplay, you can manually call the events like so:

const poki = scene.plugins.get('poki') // get the plugin from the Phaser PluginManager

poki.gameplayStart()
// ... start gameplay ...
scene.on('player_died', () => {
  poki.gameplayStop()
})

Shareable URLs and URL params

You can create a shareable URL and read values back with the plugin:

const poki = scene.plugins.get('poki')

poki.shareableURL({
  id: 'myid',
  type: 'mytype',
  score: 28
}).then((url) => {
  console.log(url)
})

const id = poki.getURLParam('id')

Moving the Poki Pill on mobile

On mobile, you can reposition the Poki Pill slightly to better fit your game UI using 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).

const poki = scene.plugins.get('poki')

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