Unity error tracking installation

PostHog is available for Unity through the Unity Package Manager.

1. Open Window > Package Manager.
2. Click the + button and select Add package from git URL.
3. Enter https://github.com/PostHog/posthog-unity.git?path=com.posthog.unity.

The Unity SDK requires Unity 2021.3 LTS or later and the .NET Standard 2.1 API Compatibility Level.

The easiest way to configure PostHog is through the Unity Inspector:

1. Go to Edit > Project Settings > PostHog.
2. Enter your API Key and select your Host.
3. Keep Capture Exceptions enabled.

The settings asset is created at Assets/Resources/PostHogSettings.asset. PostHog automatically initializes when your game starts using these settings.

You can also initialize PostHog in code:

using PostHogUnity;
using UnityEngine;

public class GameManager : MonoBehaviour
{
    void Start()
    {
        PostHog.Setup(new PostHogConfig
        {
            ApiKey = "<ph_project_token>",
            Host = "https://us.i.posthog.com",
            CaptureExceptions = true,
            ExceptionDebounceIntervalMs = 1000,
            CaptureExceptionsInEditor = true
        });
    }
}

You can find your project token and instance address in the project settings page in PostHog.

The Unity SDK captures exception events automatically by default. On most platforms, it captures exceptions reported through Unity's exception logging pipeline. On WebGL, it listens for Unity exception log messages.

Captured events include Unity and C# stack frames when available, exception type, exception message, whether the exception was handled, and Unity SDK metadata.

For handled exceptions, call CaptureException manually:

using System;
using System.Collections.Generic;
using PostHogUnity;

try
{
    SaveGame();
}
catch (Exception exception)
{
    PostHog.CaptureException(exception, new Dictionary<string, object>
    {
        { "scene", UnityEngine.SceneManagement.SceneManager.GetActiveScene().name },
        { "flow", "save_game" }
    });
}

All error tracking options can be set through the Unity Inspector or in PostHogConfig:

To disable automatic exception capture:

PostHog.Setup(new PostHogConfig
{
    ApiKey = "<ph_project_token>",
    CaptureExceptions = false
});

Trigger a test exception in Play Mode and confirm it appears in the Error Tracking tab.

try
{
    throw new InvalidOperationException("Test exception from Unity");
}
catch (Exception exception)
{
    PostHog.CaptureException(exception);
    PostHog.Flush();
}

To test automatic capture, report an exception through Unity's logger:

Debug.LogException(new InvalidOperationException("Automatic test exception from Unity"));
PostHog.Flush();