// Quickstart

From zero to a populated heatmap in ten minutes.

This guide gets you from a clean Unity project to seeing your first event on the Traced dashboard. You'll need:

  • A Unity project (2021.3 LTS or newer; we test on 2022.3).
  • A Traced account — sign up at /signup and wait for beta approval.

1. Install the package

In Unity: Window → Package Manager → + → Add package from git URL.

https://github.com/ItsBenProductions/spatialpulse.git?path=unity-sdk

Unity downloads and imports the package. You'll see Traced in your Packages list. Optionally import the Basic sample to get a reference scene.

2. Create the config asset

In your Project window, right-click → Create → Traced → Config. Save it somewhere obvious (e.g. Assets/Config/TracedConfig.asset). Open the inspector and fill in:

  • Api Key — sp_test_… from your dashboard's API Keys page during development; sp_live_… for shipped builds.
  • Project Id — also on the API Keys page.

3. Initialize the SDK at startup

using UnityEngine;
using Traced;

public class GameBootstrap : MonoBehaviour {
  public TracedConfig Config;

  void Awake() {
    Traced.Init(Config);
  }
}

4. Set session context at match start

Traced.SetSessionContext(new Dictionary<string, string> {
  { "map", "arena_01" },
  { "mode", "deathmatch" },
  { "build_version", Application.version },
  { "platform", "quest" },
});

Each call starts a new session_id server-side. Every subsequent event is tagged with it. Sessions appear under the project's Sessions page.

5. Fire events

// Simple point event
Traced.TrackEvent("death", transform.position);

// With rotation — unlocks compass / orientation rendering
Traced.TrackEvent("death", transform.position, transform.rotation);

// With metadata for later filtering
Traced.TrackEvent("death", transform.position, transform.rotation,
  new Dictionary<string, string> {
    { "weapon", "sniper" },
    { "team", "red" },
  });

For other shapes — Pair, Volume, Frustum, Trail, Position streams — see the event shapes guide.

6. Confirm it's working

With Enable Debug Logs on the config:

  1. Press Play in Unity.
  2. Trigger a few events.
  3. Watch the Console — you'll see [Traced] Initialized and POST … 132B raw / 87B gzip after the 5s flush window.
  4. Open your dashboard. Within ~100ms (via Realtime) the event appears on the project's Overview.

Common gotchas

ProblemFix
Config is invalidFill in Api Key + Project Id on the config asset.
Editor mode + EnableInEditor=false → SDK inertCheck Enable In Editor on the config, or test in a build.
Events appear in console but never POSTNetwork blocked, or the 5s flush window hasn't elapsed yet. Call Traced.Flush() manually.
Ingest failed · code=401API key is wrong or revoked. Check the dashboard.
Ingest failed · code=429You've hit a rate limit. Reduce MaxEventsPerSecond or wait.

Test events without writing scripts

For one-off testing or stress-testing the dashboard during development, open Traced → Event Tester… in the Unity menu. The tool lets you click any point in the scene view, choose an event shape (Point / Oriented / Pair / Volume / Frustum / Trail / Position), add metadata KVPs, and fire to your live project. No Play mode required — events POST directly to /v1/ingest viaUnityWebRequest. Includes a burst mode that fires N copies with random jitter, useful for stress-testing the viewer.

Next