Analytics
Integration Guide

Analytics Integration

This guide walks you through enabling Hyperstone Analytics in your Godot game. The integration is automatic and requires no code changes to get started.

Prerequisites

Before enabling analytics:

  • Your project must be created in Hyperstone
  • Your project must be synced to the cloud
  • You must have at least one export preset configured in Godot

Enabling Analytics

Step 1: Open Export Dialog

  1. Open your project in Hyperstone
  2. Navigate to the Builds tab
  3. Click Create Build or Export

Step 2: Enable Analytics Toggle

In the export dialog, you'll see several optional features:

  1. Find the Enable Analytics toggle
  2. Switch it to ON
  3. The toggle should turn green

Step 3: Configure Export Settings

Configure your export as usual:

  • Select your target platform (Windows, Linux, macOS, Web, etc.)
  • Choose export preset
  • Set build channel (stable, beta, etc.)
  • Configure other options as needed

Step 4: Export

  1. Click Export or Create Build
  2. Hyperstone will:
    • Copy your game to a temporary location
    • Inject the Analytics SDK
    • Configure the SDK with your project token
    • Export the build with analytics enabled
  3. Wait for the export to complete

Step 5: Verify Integration

After export completes:

  1. Check the build log for "Analytics SDK injection completed successfully"
  2. The build card will show an Analytics badge
  3. Your exported game will now track events

What Gets Injected

When you enable analytics, Hyperstone automatically:

1. Copies the SDK

The Analytics SDK is copied to your game's addons/ directory:

your_game/
├── addons/
│   └── hyperstone_analytics/
│       ├── hyperstone.gd
│       ├── plugin.cfg
│       └── README.md
├── project.godot
└── ... (your game files)

2. Configures the SDK

The SDK is configured with:

  • Project Token: Unique identifier for your project
  • Edge Function URL: Backend endpoint for receiving events

These are automatically injected into hyperstone.gd:

const PROJECT_TOKEN = "your-unique-project-token"
const EDGE_FUNCTION_URL = "https://your-supabase-url/functions/v1/hyperstone-collect"

3. Registers Autoload

The SDK is registered as an autoload in project.godot:

[autoload]
Hyperstone="*res://addons/hyperstone_analytics/hyperstone.gd"

This makes the SDK available globally as Hyperstone in all your scripts.

Important Notes

Original Project Unchanged

The Analytics SDK is only injected into the exported build, not your original project files. Your source code remains clean and unmodified.

Build-Specific

Each build can have analytics enabled or disabled independently. You can:

  • Enable analytics for production builds
  • Disable analytics for development builds
  • Test with and without analytics

No Code Changes Required

You don't need to modify your game code to get basic analytics. The SDK automatically tracks:

  • Game launches
  • Session duration
  • Purchase verification
  • Game closes

Testing Analytics

Local Testing

After exporting with analytics enabled:

  1. Run the exported game (not from Godot Editor)
  2. Play for a few minutes
  3. Close the game
  4. Wait 15-20 minutes for events to be sent
  5. Check the Analytics tab in Hyperstone

Note: Events are batched every 15 minutes, so there's a delay before they appear.

Verifying Events

To verify analytics is working:

  1. Open your project in Hyperstone
  2. Navigate to the Analytics tab
  3. Look for recent events:
    • game_start: Should appear after launching
    • game_close: Should appear after closing
    • verified_purchase or unverified_launch: Should appear on first launch

Debug Mode

To see analytics events in real-time during development:

  1. Open the exported game's console/terminal
  2. Look for log messages: 
    [Hyperstone Analytics] Event tracked: game_start
[Hyperstone Analytics] Batch sent successfully

Troubleshooting

Analytics Not Appearing

Possible Causes:

  • Events haven't been sent yet (wait 15-20 minutes)
  • Network connection issues
  • Project token not configured correctly

Solutions:

  • Wait for the batch timer (15 minutes)
  • Check your internet connection
  • Re-export with analytics enabled
  • Check the build log for errors

"Analytics SDK injection failed" Error

Possible Causes:

  • Project not synced to cloud
  • Missing export presets
  • File permission issues

Solutions:

  • Sync your project to the cloud first
  • Ensure you have at least one export preset in Godot
  • Check file permissions in your project directory

Events Not Tracking

Possible Causes:

  • Game running from Godot Editor (SDK only works in exported builds)
  • Network firewall blocking requests
  • Invalid project token

Solutions:

  • Always test with exported builds, not from the editor
  • Check firewall settings
  • Re-export to regenerate project token

Duplicate Events

Possible Causes:

  • Multiple instances of the game running
  • Cached events from previous sessions

Solutions:

  • Close all game instances before testing
  • Clear cached events: Delete user://hyperstone_cache.log

Advanced Configuration

Custom Event Tracking

Once analytics is enabled, you can track custom events in your game code:

# Track a simple event
Hyperstone.track("level_complete")
 
# Track an event with data
Hyperstone.track("player_death", {
    "level": 3,
    "cause": "enemy"
})

See the Custom Events guide for detailed examples.

Batch Interval

By default, events are sent every 15 minutes. To change this:

  1. Open addons/hyperstone_analytics/hyperstone.gd in your exported build
  2. Find the line: _batch_timer.wait_time = 900.0
  3. Change 900.0 to your desired interval in seconds
    • 300 = 5 minutes
    • 1800 = 30 minutes
    • 3600 = 1 hour

Note: Shorter intervals increase network usage and battery drain on mobile devices.

Offline Caching

The SDK automatically caches events when the network is unavailable. Cached events are stored in:

user://hyperstone_cache.log

On the next game launch, cached events are automatically sent and the cache file is deleted.

Disabling Analytics

To create a build without analytics:

  1. Open the export dialog
  2. Ensure the Enable Analytics toggle is OFF
  3. Export as usual

The build will not include the Analytics SDK.

Next Steps

Now that analytics is integrated:

  1. Track Custom Events - Add gameplay tracking
  2. View Analytics Data - Understand your dashboard
  3. Best Practices - Optimize your analytics

Related Documentation

OverviewCustom Events