Game Events

Use the measure() function to track game-specific events that help you understand how players move through your game.

Suggested Game Event Implementation

These HTML5 examples cover the most useful patterns. Call each event at the moment it happens in your game—the lines below show possible paths, not calls to run one after another. For another engine, use the equivalent call from the engine examples.

Drop-off Funnel

How far do players progress? What is the highest level they reach?

Use one category for the whole progression funnel and a stable value for each step. For a single attempt, send either complete or fail, never both. A start event for the next level shows that the gameplay reached that level.

// When the tutorial starts:
PokiSDK.measure('level', 'tutorial', 'start');

// Later, send one outcome for that attempt:
PokiSDK.measure('level', 'tutorial', 'complete');
PokiSDK.measure('level', 'tutorial', 'fail');

// Repeat the same pattern for each level:
PokiSDK.measure('level', '1', 'start');
PokiSDK.measure('level', '1', 'complete');
PokiSDK.measure('level', '1', 'fail');
PokiSDK.measure('level', '2', 'start');

Rewarded Video Placement Usage

Which rewarded video placement drives the most engagement?

Send visible when an offer becomes visible and interact when the player chooses it. These events measure your in-game offer UI. The SDK automatically tracks the actual rewardedBreak() playback and outcome.

PokiSDK.measure('rewarded', 'treasure-chest', 'visible');
PokiSDK.measure('rewarded', 'treasure-chest', 'interact');
PokiSDK.measure('rewarded', 'multiply-xp', 'visible');
PokiSDK.measure('rewarded', 'multiply-xp', 'interact');
PokiSDK.measure('rewarded', 'vip', 'visible');
PokiSDK.measure('rewarded', 'vip', 'interact');

UI and Shop Usage

What percentage of gameplays open the shop? Which items attract the most engagement? How often do players choose the rewarded shop refresh?

Use the same visible and interact pair for each element to compare exposure with engagement.

PokiSDK.measure('button', 'shop', 'visible');
PokiSDK.measure('button', 'shop', 'interact');
PokiSDK.measure('shop-item', 'extra-coins', 'visible');
PokiSDK.measure('shop-item', 'extra-coins', 'interact');
PokiSDK.measure('rewarded', 'shop-refresh', 'visible');
PokiSDK.measure('rewarded', 'shop-refresh', 'interact');

Meta Game and Cosmetics

How many customization items are unlocked during a gameplay? Which item types are unlocked?

Send a count milestone when the total reaches that number. Send a separate item-specific event when a particular type is unlocked.

PokiSDK.measure('cosmetic', 'items', 'unlock-1');
PokiSDK.measure('cosmetic', 'items', 'unlock-2');
PokiSDK.measure('cosmetic', 'items', 'unlock-3');
PokiSDK.measure('cosmetic', 'hat', 'unlocked');
PokiSDK.measure('cosmetic', 'skin', 'unlocked');
PokiSDK.measure('cosmetic', 'glasses', 'unlocked');

How measure() Works

Game events work like analytics checkpoints: when something meaningful happens in your game, an event is logged. This helps you understand where players drop off, which levels or features are most engaging, whether upgrades are being used, and how your ad placements fit into the experience.

Choose values that are stable and easy to compare across versions of your game:

category: the broad group, such as level, tutorial, drawing, button, or difficulty.
what: the specific thing being measured, such as 1, de_dust, reward-revive, or hard.
action: the event state. Any value is accepted, but some values have special analytical meaning.

Event Types

Track the events that explain important player behavior. The more meaningful events you send, the more useful the analytics become.

Event type	When to use it
Progress events	Track player progression checkpoints with `start`, `complete`, and `fail`. Best for levels, quests, missions, rounds, and tutorial steps.
Interaction events	Compare UI exposure and engagement with `visible` and `interact`. Best for buttons, upgrades, shops, power-ups, and popups.
Ad playback	Commercial and rewarded break playback and outcomes are tracked automatically through your existing ad SDK calls. Use interaction events to measure the in-game placements that lead to those calls.
Custom events	Track unique game systems with any custom action value. Best for difficulty choices, VIP access, currency, crafting, and first-time milestones.

Engine Examples

HTML5UnityGameMakerPhaser 3GodotCocosConstruct 3GDevelopDefold

PokiSDK.measure('level', '1', 'start');

PokiUnitySDK.Instance.measure("level", "1", "start");

poki_measure("level", "1", "start");

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

poki.measure('level', '1', 'start')

PokiSDK.measure("level", "1", "start")

CCPokiSDK.measure('level', '1', 'start')

Action:   Poki SDK > Send Event
Category: level
What:     1
Action:   start

Action:   Poki Games SDK > Measure event
Category: level
What:     1
Action:   start

poki_sdk.measure("level", "1", "start")

Special Action Values

The action value is not restricted to the values below. Use any custom value when you want to track that a gameplay reached a specific event.

These special values are interpreted by Poki for richer analytics. They determine whether an event appears in progress, interaction, or other event reporting.

Action value	Reporting	Meaning
start	Progress events	Starts a progress funnel, such as a level, tutorial, or drawing. Example: `measure('level', '1', 'start')`.
complete	Progress events	Marks that progress as completed. Use the same category and what as the matching `start` event. Example: `measure('level', '1', 'complete')`.
fail	Progress events	Marks that progress as failed. Use the same category and what as the matching `start` event. Example: `measure('level', '1', 'fail')`.
visible	Interaction events	Tracks when something becomes visible, such as a rewarded break button or tutorial hint. Example: `measure('button', 'reward-revive', 'visible')`.
interact	Interaction events	Tracks when something is interacted with. Use the same category and what as the matching `visible` event. Example: `measure('button', 'reward-revive', 'interact')`.
<action>	Other events	Tracks any other event. Custom actions show the percentage of gameplays that reached the event. Example: `measure('difficulty', 'hard', 'selected')`.

Choosing Event Values

For category, choose a short group name such as level, tutorial, drawing, button, or difficulty.

For what, choose the value that identifies the specific thing you are measuring. For levels, this could be 1, 2, or de_dust. For buttons, this could be skip-level or extra-points.

For action, use a special value when the event fits one of the progress or interaction patterns above. Use a custom action for one-off events, choices, or milestones that should appear in other event reporting.

Progress and interaction pairs should use the same category and what; only the action changes. For a progress attempt, send start and then either complete or fail. For an interaction, send visible and then interact when the player uses it.

Progress Events

Progress events are useful for games with levels, rounds, quests, tutorials, or any other milestone structure. Even when your game does not have fixed levels, progress can mean that a puzzle was solved, a round was completed, a chapter was reached, a boss was defeated, or a challenge was failed.

Use progress events to find drop-off points, detect difficulty spikes, validate onboarding, and tune pacing or content.

Game type	Useful progress events
Level games	`level-1-start`, `level-1-complete`, `level-1-fail`
Open world	`quest-mainline-start`, `quest-side-complete`, `biome-desert-start`
Puzzle	`puzzle-45-complete`, `streak-current-fail`
Action or shooter	`wave-5-start`, `boss-2-fail`, `checkpoint-3-complete`
Dress-up	`theme-winter-start`, `collection-shoes-complete`
Solitaire or card	`round-1-start`, `round-1-fail`

Interaction Events

Interaction events help you compare what players see with what they actually use. They are especially useful for buttons, shops, upgrades, boosters, power-ups, unlocks, and tutorial hints.

If visibility is high but interaction is low, the feature may be unclear, poorly placed, or unappealing. If interaction is strong, the feature may be a good candidate for stronger rewards, more content, or monetization tuning.

Game feature	Events to send
Booster button	`booster-x-visible`, `booster-x-interact`
Shop open	`shop-main-visible`, `shop-main-interact`
Character unlock	`skin-gold-visible`, `skin-gold-interact`
Power-up	`powerup-freeze-visible`, `powerup-freeze-interact`
Hint	`hint-default-visible`, `hint-default-interact`

Custom Events

Use custom events for game-specific behavior that does not fit the progress or interaction patterns. Good examples include difficulty choices, crafting, resource economy actions, VIP states, seasonal content, battle passes, power-ups without a UI button, and first-time milestones.

PokiSDK.measure('difficulty', 'hard', 'selected');
PokiSDK.measure('vip', 'access', 'granted');
PokiSDK.measure('currency', 'gold', 'spent');
PokiSDK.measure('crafting', 'sword', 'finished');
PokiSDK.measure('speedrun', 'mode', 'enabled');
PokiSDK.measure('milestone', 'first-upgrade', 'reached');

Custom events tell deeper stories about player behavior beyond UI clicks, wins, and losses.

Automatic Ad Events

Commercial and rewarded break playback and outcomes are tracked automatically through your existing ad SDK calls. Do not send measure() events that duplicate ad impressions or completions.

You can still use measure() for the in-game placement that leads to a rewarded break. Pair visible and interact with a stable placement name, as shown in the rewarded video placement examples. This measures exposure and engagement with the offer, while rewardedBreak() tracks the ad itself.

Ad analytics can help you understand whether ads are placed at good moments in the experience:

Signal	What it can mean
Many early commercial breaks	Ads may appear before players are ready, which can hurt retention.
Rewarded offers are often visible but rarely interacted with	The reward may be too weak, unclear, or hard to find.
Rewarded offers are interacted with often	The reward has strong value and may need more reward sinks or balancing.
Commercial breaks are frequent	Ad pacing may be affecting session length or satisfaction.