SDK overview & events
The Poki SDK connects your game to the platform. It handles ad delivery, gameplay tracking, and the tools you need to test and optimize. This page gives you the big picture; integration details live in the SDK for HTML5 guide.
A handful of SDK events, fired at the right moments, give you the most important metrics of your game and power its monetization. Here's what they are and when to fire them.
What the events unlock
Thanks to our developer-friendly SDK, you can easily oversee the most important metrics of your game simply by firing a couple of SDK events during various moments in the game. This information includes, but is not limited to:
- Playing Users: The amount of page visitors and the percentage of users who are able to play the game.
- Engagement: Average time players spends in game. Also shows how much time is spent on loading or ads.
- Earnings: Ad-related metrics such as total earnings, or the distribution of impression types.
- Error Scanner: Details for all of errors of the past 24 hours, updated hourly.
- Player Feedback: Details on player rating and comments.
With events implemented, your dashboard shows daily playing users (visitors vs players), engagement (time in game, loading, and ads), earnings and impression types, an error scanner (past 24 hours, updated hourly), and player feedback.
The events
gameLoadingFinished(): fire when loading completes. Required to track loading and show your conversion to play.gameplayStart(): fire when the player starts interacting (first input, level start, unpause).gameplayStop(): fire when gameplay halts (pause, level complete, death, quit to menu).commercialBreak(): fire at natural stops, whenever the player is about to head back into gameplay. Not every call triggers an ad; our system decides when a player is ready, so signal as many opportunities as possible.rewardedBreak(): fire on the player's explicit choice to watch an ad for a reward. Make it clear beforehand that an ad is coming. A rewarded break resets the ad timer, so players won't immediately see another ad.- For full overview of our rewarded advertisement integration guidelines you can see our requirements and quality guidelines.
Order of events
| Moment | Sequence |
|---|---|
| Startup | gameLoadingFinished() → gameplayStart() |
| Death and restart | gameplayStop() → commercialBreak() → gameplayStart() |
| Death and revive | gameplayStop() → rewardedBreak() → gameplayStart() |
| Next level | gameplayStop() → commercialBreak() → gameplayStart() |
| Pause / unpause | gameplayStop() → commercialBreak() → gameplayStart() |
If an ad fires without interrupting gameplay (say, watching an ad to unlock a skin from a menu), no gameplayStop() or gameplayStart() is needed around it.
Testing your events
The Poki Inspector runs your game as if it were live: drag in your game folder (with an index.html), test on any device or browser, and watch the event log to verify everything fires correctly.
Uploading from the command line
The Poki for Developers CLI uploads builds straight from your terminal or CI pipeline. See the poki-cli repository on GitHub for installation.