Skip to content

cocos-banner

PokiSDK - Cocos Creator 3.x

Made by vkrishna 

Introduction & Features

This is a Poki Plugin made for the Cocos Creator Engine. It works for CocosCreator3.4.0 and above only. It was designed to help the integration of the PokiSDK into your Cocos Creator(3.x) game. You can create a custom build and preview templates to do the integration by yourself, but the extension provides them ready to use.

Features
  • A preview template
  • A web-mobile build template
  • PokiSDK abstraction
  • A demo scene showcasing usage

Once you install and enable the extension, you will be able to test the PokiSDK integration in preview mode (in browser) and be able to make builds (web-mobile) that can be uploaded to Poki platform.

In your component scripts, you will be able to import CCPokiSDK and use it to interact with the PokiSDK. The following are the functions that are available for you to use from your game scripts. Check out the DemoScript.ts for example usage.

CCPokiSDK.gameLoadingFinished() //-- in JS it's PokiSDK.gameLoadingFinished()
CCPokiSDK.gameplayStart() //-- in JS it's PokiSDK.gameplayStart()
CCPokiSDK.gameplayStop() //-- in JS it's PokiSDK.gameplayStop()
CCPokiSDK.commercialBreak() //-- in JS it's PokiSDK.commercialBreak()
CCPokiSDK.rewardedBreak() //-- in JS it's PokiSDK.rewardedBreak()
CCPokiSDK.rewardBreak() //-- legacy alias for PokiSDK.rewardedBreak()
CCPokiSDK.shareableURL(params) //-- in JS it's PokiSDK.shareableURL({}).then(url => {})
const value = CCPokiSDK.getURLParam(key) //-- in JS it's PokiSDK.getURLParam('id')
CCPokiSDK.movePill(topPercent, topPx) //-- in JS it's PokiSDK.movePill(topPercent, topPx)

1. Initialize the SDK

There are two ways to download and install the extension.

  • Cocos Store: You can search and install the extension directly from the Cocos Store. This is the easiest way to get started.
  • From Source/Release: Download the extension archive poki-sdk-v1.2.zip.

Or download the source code as a zip file.

git clone https://github.com/vkbsb/cocos-creator-poki-sdk

Once this is done, you can launch the extension manager in Cocos creator editor via Extension > Extension Manager. Switch to the Project tab and click on Import Extension (+) button:

Screenshot

extension-add

Browse to the zip file you’ve downloaded and click open. Once the installation is done, go to the Extension Manager and ensure that the poki-build extension is enabled.

extension-enable

The preview and web-mobile templates initialize the browser Poki SDK for you. Use CCPokiSDK from your component scripts; there is no public CCPokiSDK.init() call.


2. Implement the game loading logic

The web-mobile build template automatically calls PokiSDK.gameLoadingStart() when the engine starts and PokiSDK.gameLoadingFinished() when Cocos finishes starting the game.

The wrapper also exposes gameLoadingFinished() for custom templates or projects that bypass the provided loading flow:

CCPokiSDK.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
CCPokiSDK.gameplayStart()
// player is playing
// player loses round
CCPokiSDK.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
CCPokiSDK.commercialBreak()

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.

In order to use a rewarded break in your game, please follow the steps below:

  • Register for a call back on cc.game for EVENT_REWARD_BREAK_DONE
  • if arguments[0] == true we can give player their reward, otherwise don’t award the player. 
import { game } from 'cc'
import { CCPokiSDK } from '../poki-api/PokiPlatform'

game.on(CCPokiSDK.EVENT_REWARD_BREAK_DONE, (withReward: boolean) => {
    if (withReward) {
        // Give the player their reward.
    }

    CCPokiSDK.gameplayStart()
})

CCPokiSDK.gameplayStop()
CCPokiSDK.rewardBreak()

You can also call CCPokiSDK.rewardedBreak() directly if you want to use the promise returned by the browser SDK:

CCPokiSDK.rewardedBreak({ size: 'medium' }).then((withReward) => {
    if (withReward) {
        // Give the player their reward.
    }
})

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
CCPokiSDK.commercialBreak().then(
    () => {
        console.log("Commercial break finished, proceeding to game");
        // fire your unmute audio function
        // fire your enable keyboard input function
        CCPokiSDK.gameplayStart();
        // fire your function to continue to game
    }
);


Shareable URLs & URL manipulation

You can create a shareable URL with custom parameters and read values back from the Poki URL:

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

const id = CCPokiSDK.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).
CCPokiSDK.movePill(50, -100)


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


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