Skip to content
Framedash Docs

Unity SDK

This guide explains how to automatically collect performance telemetry using the Framedash Unity SDK.

Requirements

Section titled “Requirements”
  • Unity 2022.3 or later
  • .NET Standard 2.1 / .NET Framework 4.x

Installation

Section titled “Installation”
Section titled “Unity Package Manager (Recommended)”
  1. Open Window > Package Manager
  2. Select ”+” > “Add package from git URL…”
  3. Enter the following URL:
https://github.com/crane-valley/framedash-unity-sdk.git

To pin a specific release, append a version tag:

https://github.com/crane-valley/framedash-unity-sdk.git#v0.1.0

Initial Setup

Section titled “Initial Setup”

Initialize the SDK once at startup, for example from a MonoBehaviour on a persistent GameObject:

using System.Collections.Generic;
using Framedash;
using UnityEngine;


public sealed class GameBootstrap : MonoBehaviour
{
    // Assign the API key in the Inspector, or load it from a ScriptableObject
    // or platform secret store. Environment variables are unavailable on
    // mobile, console, and WebGL, so avoid Environment.GetEnvironmentVariable.
    [SerializeField] private string _apiKey;


    private void Awake()
    {
        TelemetrySDK.Initialize(
            apiKey: _apiKey,
            buildId: Application.version);
    }
}

endpointUrl is optional and defaults to https://ingest.framedash.dev/v1/events; pass it explicitly to target a local or self-hosted ingest endpoint.

Automatic Performance Data Collection

Section titled “Automatic Performance Data Collection”

The SDK automatically collects the following data:

  • FPS — Frame rate
  • Frame Time — Processing time per frame
  • Memory — Managed heap + native memory usage

Sending Custom Events

Section titled “Sending Custom Events”
TelemetrySDK.Instance.Track(
    eventName: "player_death",
    mapId: "map_01",
    position: transform.position);

To attach categorical attributes or numeric metrics, pass the optional dictionaries:

TelemetrySDK.Instance.Track(
    eventName: "player_death",
    mapId: "map_01",
    position: transform.position,
    attributes: new Dictionary<string, string> { { "cause", "fall_damage" } },
    metrics: new Dictionary<string, float> { { "health", 0f } });

Identifying the Player (Optional)

Section titled “Identifying the Player (Optional)”

By default events are sent anonymously. Call SetPlayerId after the player logs in to associate subsequent events with them:

TelemetrySDK.Instance.SetPlayerId(playerId);

Next Steps

Section titled “Next Steps”