Game Events

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

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.

For example, the start of level 1 can be measured like this:

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

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.
Ads	Commercial and rewarded ad analytics are tracked automatically through your existing ad SDK calls. No extra `measure()` calls are needed.
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 pairs should use the same category and what; only the action changes:

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

Interaction pairs should also use the same category and what; only the action changes:

PokiSDK.measure('button', 'reward-revive', 'visible');
PokiSDK.measure('button', 'reward-revive', 'interact');

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 breaks and rewarded breaks are tracked automatically through your existing ad SDK calls. You do not need to send extra measure() events for midroll or rewarded impressions.

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 breaks are rarely used	The reward may be too weak, unclear, or hard to find.
Rewarded breaks are used 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.