Analytics
Viewing Analytics

Viewing Analytics Data

Learn how to use Hyperstone's Analytics dashboard to understand player behavior and track your game's performance.

Accessing Analytics

  1. Open your project in Hyperstone
  2. Click on the Analytics tab in the sidebar
  3. The analytics dashboard will load with your project's data

Note: You must have at least one build with analytics enabled and some player activity before data appears.

Dashboard Overview

The Analytics dashboard is divided into several sections:

Date Range Selector

At the top of the dashboard, you'll find date range controls:

Date Inputs:

  • Start Date: Beginning of the date range
  • End Date: End of the date range

Quick Range Buttons:

  • Last 7 days: View the past week
  • Last 30 days: View the past month (default)
  • Last 90 days: View the past quarter

Usage:

  1. Click on a date input to select a custom range
  2. Or click a quick range button for preset ranges
  3. Data updates automatically when you change the range

Metrics Overview

The top section displays key metrics for your selected date range:

Total Events

The total number of events tracked across all sessions.

What it means:

  • Higher numbers indicate more player activity
  • Includes both automatic and custom events
  • Useful for measuring overall engagement

Example:

  • 10,000 events = Very active player base
  • 1,000 events = Moderate activity
  • 100 events = Early testing phase

Unique Sessions

The number of unique game sessions (based on game_start events).

What it means:

  • Each game launch counts as one session
  • Indicates how many times players started your game
  • Useful for measuring player retention

Example:

  • 500 sessions from 10,000 events = ~20 events per session
  • High events-per-session = Engaged players
  • Low events-per-session = Players quitting early

Verified Purchases

The number of sessions with a valid itch.io download key.

What it means:

  • Players who purchased your game legitimately
  • Tracked automatically via verified_purchase event
  • Percentage shows verified vs. total launches

Example:

  • 80% verified = Most players purchased legitimately
  • 20% verified = High piracy rate

Unverified Launches

The number of sessions without an itch.io download key.

What it means:

  • Potential pirated copies
  • Could also be demo versions or DRM-free builds
  • Percentage shows unverified vs. total launches

Note: Not all unverified launches are piracy - some players may have DRM-free versions or be playing demos.

Charts

Events Over Time

A line chart showing event frequency over your selected date range.

What it shows:

  • X-axis: Dates
  • Y-axis: Number of events
  • Line: Event count per day

How to use:

  • Identify peak activity days
  • Spot trends (increasing/decreasing engagement)
  • Correlate with marketing campaigns or updates

Example insights:

  • Spike on release day
  • Drop-off after first week
  • Increase after major update

Top Events

A horizontal bar chart showing the most frequent events.

What it shows:

  • Y-axis: Event names
  • X-axis: Event count
  • Bars: Frequency of each event

How to use:

  • See which events fire most often
  • Identify popular features or actions
  • Spot unexpected patterns

Example insights:

  • level_complete is top event = Players progressing well
  • player_death is top event = Game might be too hard
  • tutorial_skipped is high = Tutorial might be too long

Recent Events Table

A detailed table of the most recent events (last 50).

Columns:

  • Event Name: The name of the event
  • Event Data: JSON data attached to the event
  • Created At: Timestamp when the event occurred

How to use:

  • Debug custom events
  • Verify event data is correct
  • See real-time player activity

Example:

Event Name: level_complete
Event Data: {"level": 3, "time_taken": 120.5, "score": 1000}
Created At: 2026-05-10 14:32:15

Interpreting Data

Engagement Metrics

High Engagement:

  • Many events per session
  • Long session durations (check game_close event data)
  • Frequent return visits

Low Engagement:

  • Few events per session
  • Short session durations
  • Infrequent return visits

Player Progression

Healthy Progression:

  • level_started and level_completed events are balanced
  • Low level_failed rate
  • Increasing difficulty levels in event data

Stuck Players:

  • High level_failed rate on specific levels
  • Many player_death events in one area
  • Low progression to higher levels

Purchase Verification

High Verification Rate (>70%):

  • Most players purchased legitimately
  • Good sign for revenue
  • Consider rewarding verified players

Low Verification Rate (<30%):

  • High piracy rate
  • Consider DRM or anti-piracy measures
  • Or embrace it as free marketing

Custom Event Analysis

Look at your custom events to understand:

Player Behavior:

  • Which features are used most
  • Which items are purchased
  • Which abilities are popular

Pain Points:

  • Where players die most
  • Which levels are failed most
  • Which tutorials are skipped

Success Metrics:

  • Achievement unlock rates
  • Tutorial completion rates
  • Level completion times

Filtering & Analysis

Date Range Filtering

Use date ranges to:

Compare Time Periods:

  • Week 1 vs. Week 2 after launch
  • Before vs. after an update
  • Seasonal trends

Identify Trends:

  • Is engagement increasing or decreasing?
  • Are players progressing faster over time?
  • Is piracy rate changing?

Measure Impact:

  • Did a marketing campaign increase sessions?
  • Did a balance patch affect player deaths?
  • Did a new feature increase engagement?

Event-Specific Analysis

Focus on specific events:

  1. Look at the Top Events chart
  2. Identify the event you want to analyze
  3. Check the Recent Events table for that event
  4. Examine the event data for patterns

Example:

  • Event: player_death
  • Data: {"level": 3, "cause": "enemy"}
  • Insight: Most deaths on level 3 from enemies
  • Action: Balance level 3 enemy difficulty

Exporting Data

Currently, data export is not available in the UI. To export data:

  1. Use the Supabase dashboard to query the game_events table
  2. Filter by your project_id
  3. Export to CSV or JSON

Future Feature: Built-in data export will be added in a future update.

Data Retention

Analytics data is retained based on your plan:

  • Free Tier: 90 days
  • Pro Tier: 1 year

After the retention period, data is automatically deleted.

Troubleshooting

No Data Appearing

Possible Causes:

  • No builds with analytics enabled
  • No player activity yet
  • Events haven't been sent yet (15-minute batch delay)

Solutions:

  • Export a build with analytics enabled
  • Play the game yourself to generate test data
  • Wait 15-20 minutes for events to be sent

Data Seems Incorrect

Possible Causes:

  • Wrong date range selected
  • Cached events from old sessions
  • Multiple game instances running

Solutions:

  • Check the date range selector
  • Clear cached events: Delete user://hyperstone_cache.log in game
  • Ensure only one game instance is running

Missing Custom Events

Possible Causes:

  • Events not tracked in code
  • Event names misspelled
  • Events filtered out by date range

Solutions:

  • Verify Hyperstone.track() is called in your code
  • Check event names for typos
  • Expand date range to include all events

Charts Not Loading

Possible Causes:

  • Network connection issues
  • Browser cache issues
  • Supabase connection problems

Solutions:

  • Check your internet connection
  • Refresh the page (Ctrl+R or Cmd+R)
  • Clear browser cache
  • Try a different browser

Best Practices

Regular Monitoring

Check analytics regularly to:

  • Spot issues early
  • Measure impact of updates
  • Understand player behavior

Recommended frequency:

  • Daily during launch week
  • Weekly during active development
  • Monthly for stable releases

Set Baselines

Establish baseline metrics:

  • Average session duration
  • Typical events per session
  • Normal verification rate

Use baselines to identify anomalies.

Act on Insights

Don't just collect data - use it:

High player deaths on level 3?

  • Reduce enemy difficulty
  • Add more health pickups
  • Improve level design

Low tutorial completion?

  • Shorten tutorial
  • Make it skippable
  • Add interactive elements

High piracy rate?

  • Add value for verified players
  • Implement soft DRM
  • Or embrace it as marketing

Combine with Other Data

Analytics is most powerful when combined with:

  • Player feedback
  • Bug reports
  • Community discussions
  • Sales data

Related Documentation

Custom Events