Hypercade Docs

Unity SDK Integration

6 min read

The HypercadeAnalytics package adds Hypercade analytics to your Unity game. It’s a UPM (Unity Package Manager) package with C# API.

Tested against Unity 2022.3 LTS. Newer Unity 6 versions also work; older 2021.x is unverified.

Installation

  1. Open the Package Manager (Window > Package Manager).
  2. Click the + button in the top-left and choose Add package from git URL…
  3. Paste the git URL provided by Hypercade (typically https://github.com/<your-org>/HypercadeAnalytics.git?path=foundation/analytics/plugin/unity).
  4. Click Add.

Unity downloads and compiles the package automatically. You should see Hypercade Analytics appear in the Package Manager list.

Manual installation

If your project can’t use git URLs (e.g. air-gapped builds), install from a local copy:

  1. Get a copy of the foundation/analytics/plugin/unity/ directory from Hypercade.
  2. Copy its contents into your project under Packages/io.hypercade.analytics/ (the folder name must match the name field in package.json, which is io.hypercade.analytics — using com.hypercade.analytics will fail to bind).
  3. Unity detects and imports it automatically on the next domain reload.

Configuration

You have two ways to provide the endpoint, project token, and game slug. Pick whichever you prefer — they can be mixed.

Project Settings (recommended for non-engineers): Open Edit > Project Settings > Hypercade Analytics. Fill in Endpoint, Token, and Game Slug. The values are saved to Assets/Resources/HypercadeAnalyticsSettings.asset and packed into your build automatically.

Code arguments (recommended for CI / per-build overrides): Pass the values directly to Initialize(). Code arguments take precedence over the Project Settings asset.

Initialization

Initialize the SDK early in your game’s lifetime — typically in a GameInstance bootstrap script:

using Hypercade.Analytics;
 
public class GameBootstrap : MonoBehaviour
{
    void Start()
    {
        // Pass empty strings to fall back to Project Settings.
        HypercadeAnalytics.Instance.Initialize(
            "https://data.programmoria.com",
            "<your-project-token>",
            "<your-game-slug>"
        );
    }
}

Replace:

  • <your-project-token> with your Hypercade project token (from the portal)
  • <your-game-slug> with your game identifier (e.g., "my_game" or "my_game_alpha")

Call Initialize once per game session. Subsequent calls are ignored with a warning in the Unity console. The SDK auto-emits a session_start row into the sessions table on Initialize, and a session_end row (with duration_ms) when the application loses focus, pauses, or quits.

Logging progression markers

Use markers to log significant moments — levels completed, bosses defeated, milestones reached:

HypercadeAnalytics.Instance.LogMarker("progression", "boss_01_down");

The first parameter is the BigQuery table name the row will land in (e.g. progression, achievements, tutorial). The second parameter is the marker tag, which is stored in the marker column of that table. Pick a small, stable set of table names and reuse them — every distinct table name creates a new BigQuery table on first write.

Logging custom events

Log structured data as key-value pairs:

HypercadeAnalytics.Instance.LogEvent("gameplay", new Dictionary<string, object>
{
    { "level", 3 },
    { "score", 12500 },
    { "difficulty", "hard" },
    { "completed", true }
});

The first argument is again the destination table name; the dictionary is the row. Supported value types:

  • string (BigQuery STRING)
  • int / long (BigQuery NUMERIC)
  • float / double (BigQuery NUMERIC, rounded to 9 decimal places)
  • bool (BigQuery BOOL)

Stick to those four types. Other numeric types (byte, short, uint, ulong, decimal) are not currently supported and may be silently coerced to strings, which pins the BigQuery column to STRING permanently. Cast to int or long before logging.

Manual flush

Events are appended to an on-disk journal as you call LogMarker / LogEvent. The SDK auto-flushes the journal to the server when the application loses focus, pauses, or quits. To force a flush at a known-safe checkpoint (e.g. autosave, scene transition):

HypercadeAnalytics.Instance.Flush();

Flush is fire-and-forget — it returns immediately and runs the upload as a coroutine.

Machine identity

The SDK generates a unique machine ID per device. This ID is used to identify repeat players without logging personal information.

Identity file locations:

  • Windows: %LOCALAPPDATA%\HypercadeFoundation\hc_identity.dat
  • macOS: ~/Library/Application Support/Hypercade/hc_identity.dat
  • Linux: ~/.config/hypercade/hc_identity.dat

The identity file is created automatically on first run as a random UUID v4 and persisted. It is not deterministic from hardware — if the file is deleted, the next run generates a new UUID. The ID does not survive OS reinstalls or moving the user profile to a new machine.

You don’t need to interact with the identity file directly. The SDK manages it.

Auto-collected fields

The SDK automatically includes these fields with every event:

  • h_id - Hypercade machine ID (from the identity file)
  • app - Your game slug
  • env_os - Operating system (Windows, Mac, Linux, iOS, Android)
  • env_gpu - GPU model
  • env_ram - System RAM in GB
  • env_vram - Video RAM in GB
  • env_deck - Is this a Steam Deck? (true/false)

You don’t log these manually. They appear in every event in BigQuery.

Event batching and retry

The SDK is journal-first: every Log* call appends one NDJSON line to a per-game file under %LOCALAPPDATA%\HypercadeFoundation\<slug>\events.ndjson (or the platform equivalent). Transport is not continuous — flushes happen at well-defined moments:

  • when you call Flush() explicitly
  • on OnApplicationPause(true) and OnApplicationFocus(false) (alt-tab, mobile background, etc.)
  • on OnApplicationQuit
  • on next startup, if a previous session crashed mid-flush (orphan-journal recovery)

A flush groups all pending rows by table and POSTs each table’s rows in one batched call to /v1/log/batch. If the server returns 503 (table just got created or schema patched), the SDK retries up to 3 times. If a flush fails for any other reason, the journal is preserved and replayed on the next flush — occasional duplicate rows are acceptable per the backend’s no-insertId design.

You don’t need to handle retries yourself.

Data format

The SDK posts to https://data.programmoria.com/v1/log/batch. Each request wraps a single table’s rows:

{
  "token": "<your-project-token>",
  "table": "gameplay",
  "rows": [
    {
      "h_id": "550e8400-e29b-41d4-a716-446655440000",
      "app": "my_game",
      "env_os": "Windows 11",
      "env_gpu": "NVIDIA GeForce RTX 4090",
      "env_ram": 32,
      "env_vram": 24,
      "env_deck": false,
      "level": 3,
      "score": 12500,
      "difficulty": "hard"
    }
  ]
}

Rows are flat — no nested objects or arrays. The managed fields (h_id, app, env_*) are injected automatically; you don’t add them yourself.

Best practices

  • Initialize early: Do this in Start() or Awake() before any game logic runs.
  • Log meaningful markers: Progression markers help you understand player flow. Log things that matter - levels, bosses, major features.
  • Keep event data simple: Use flat key-value pairs. Avoid deeply nested structures.
  • Use consistent keys: If you log “level” in one event, use “level” consistently. This makes querying easier.
  • Avoid logging PII: Don’t include player names, emails, or other personal data in events.
  • Handle network failures gracefully: The SDK queues events locally if the network is down. Trust that they’ll sync when connectivity returns.

Troubleshooting

Events not appearing in BigQuery:

  • Verify the project token is correct.
  • Check that the game slug matches what’s in the Hypercade portal.
  • Ensure the game has network connectivity to reach data.programmoria.com.
  • Check the console (Window > General > Console) for error messages.

Package installation failed:

  • If the git URL doesn’t work, try manual installation (see Installation section).
  • Ensure you have access to the repository Hypercade provided.

Identity file not found:

  • This is normal on first run. The SDK creates it automatically.
  • If you see repeated creation warnings, check file system permissions.

High memory usage:

  • Large event batches may cause temporary memory spikes. This is normal.
  • If you’re logging thousands of events per second, consider batching or sampling.

For help, contact the Hypercade team at hello@hypercade.io.

Backlinks