PokiSDK: Cocos

Integration outline

1. Set up the SDK for Cocos. Integrate the SDK in your Cocos Creator 3.x web build.
2. Signal loading: fire gameLoadingFinished() when your game is done loading, so conversion to play is measured correctly.
3. Gameplay events: fire gameplayStart() on the player's first input and every return to gameplay; gameplayStop() on every interruption (pause, level end, game over, menu).
4. Ads: implement commercialBreak() at natural breaks before returning to gameplay, and rewardedBreak() for opt-in rewards. Mute audio and disable input during ads.
5. Test with the Poki Inspector to verify the event flow.

Event rules and the full order-of-events reference live in the SDK overview.

Made by vkrishna.

This is a Poki plugin for the Cocos Creator engine. It works for Cocos Creator 3.4.0 and above only, and helps you integrate the PokiSDK into your Cocos Creator 3.x game. You can create custom build and preview templates and do the integration yourself, but the extension provides them ready to use.

What the plugin provides

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

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

In your component scripts, import CCPokiSDK and use it to interact with the PokiSDK. The functions available from your game scripts are below. See DemoScript.ts for example usage.

TypeScript API

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.rewardBreak() //-- in JS it's PokiSDK.rewardedBreak()
CCPokiSDK.shareableURL(params, callback) //-- in JS it's PokiSDK.shareableURL({}).then(url => {})
local value = CCPokiSDK.getURLParam(key) //-- in JS it's PokiSDK.getURLParam('id')

Install the SDK

There are two ways to download and install the extension:

• Cocos Store: search for and install the extension directly from the Cocos Store. This is the easiest way to get started.
• From source or 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 that's done, launch the extension manager in the Cocos Creator editor via Extension > Extension Manager. Switch to the Project tab and click the Import Extension (+) button. Browse to the zip file you downloaded and click open. When installation is done, go back to the Extension Manager and make sure the poki-build extension is enabled.

Gameplay events

Use gameplayStart() to mark when players are playing your game (for example level start and unpause). Use gameplayStop() to mark when they aren't (for example level finish, game over, pause, or quit to menu).

// first level loads, player clicks anywhere
CCPokiSDK.gameplayStart()
// player is playing
// player loses round
CCPokiSDK.gameplayStop()
// game over screen pops up

commercialBreak

Commercial breaks show video ads and should be triggered at natural breaks in your game. Throughout the game we recommend calling commercialBreak() before every gameplayStart(), that is, whenever the player has shown intent to continue playing.

// gameplay stops
CCPokiSDK.commercialBreak()

rewardedBreak

Rewarded breaks let a player choose to watch a rewarded video ad in exchange for a benefit in the game (more coins, for example). When using a rewarded break, make it clear to the player beforehand that they're about to watch an ad. To use one, follow these steps:

• Register a callback on cc.game for EVENT_REWARD_BREAK_DONE.
• If arguments[0] == true, give the player their reward; otherwise don't award the player.

Final steps

Disable sound and input during ads

Make sure audio and keyboard input are disabled during commercial breaks so 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 scroll. In a game you don't want that. It isn't noticeable in your development environment, where your game probably takes the full window, but on Poki your game sits inside a longer page that can scroll. Paste this snippet into your game to disable that 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

Congratulations, you've 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. If you get stuck, reach out via Discord or developersupport@poki.com.