Hypercade Docs

Unity SDK Integration

4 min read

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

Installation

  1. In Unity, go to Window > TextMesh Pro > Import TMP Essential Resources (if not already done).
  2. Open the Package Manager (Window > Package Manager).
  3. Click the ”+” button and select “Add package from git URL…”
  4. Enter the git URL provided by Hypercade.
  5. Click Add.

The package will install automatically.

Manual installation

If your project doesn’t support git URLs, you can install manually:

  1. Download the HypercadeAnalytics package from Hypercade.
  2. Extract it into your project’s Packages/ directory.
  3. Rename the folder to com.hypercade.analytics.
  4. Unity will detect and import it automatically.

Initialization

Initialize the SDK early in your game’s lifetime - typically in a GameManager or at startup:

using Hypercade.Analytics;
 
public class GameManager : MonoBehaviour
{
    void Start()
    {
        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. It’s safe to call multiple times (subsequent calls are ignored).

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 marker type (e.g., “progression,” “achievement,” “tutorial”). The second is a descriptive string.

Logging custom events

Log structured data as key-value pairs:

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

Supported types:

  • string (text)
  • int / long (integers)
  • float / double (decimals)
  • bool (true/false)

The SDK converts these to JSON automatically.

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. If deleted, a new ID is generated. The ID is deterministic for a given machine - the same device always gets the same ID (useful for testing, but the ID doesn’t persist across OS reinstalls or hardware changes).

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

Events are batched and sent periodically (roughly every 30-60 seconds). If the service is unavailable (returns 503), the SDK:

  1. Queues the event locally
  2. Retries when the service comes back online
  3. Sends all queued events when connectivity is restored

You don’t need to handle retries yourself. The SDK does it automatically.

Data format

Events are sent as flat JSON to the endpoint https://data.programmoria.com/v1/log/. Example:

{
  "h_id": "550e8400-e29b-41d4-a716-446655440000",
  "app": "my_game",
  "env_os": "Windows",
  "env_gpu": "NVIDIA GeForce RTX 4090",
  "env_ram": 32,
  "env_vram": 24,
  "env_deck": false,
  "event_name": "session_end",
  "level": 3,
  "score": 12500,
  "difficulty": "hard"
}

No nested objects. Keep the structure flat.

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 [email protected].

Backlinks