ivx-crashlytics

Files (1)

• SKILL.md

SKILL.md (first lines)

# IntelliVerseX Crashlytics

## Overview

The Crashlytics module provides automatic crash and exception capture, breadcrumb trails, crash grouping, and alert webhooks. It supports self-hosted reporting via Nakama storage, or integration with external services (Sentry, Firebase Crashlytics, Backtrace). All platforms share the same API surface.

```
Exception/Crash
      │
      ▼
IVXCrashReporter
      │
      ├── Stack Trace Capture
      ├── Breadcrumb Trail (last N actions)
      ├── Device + Game State Metadata
      └── Crash Grouping (fingerprint)
      │
      ├──► Nakama Storage (self-hosted)
      ├──► Sentry (external)
      ├──► Firebase Crashlytics (external)
      └──► Webhook Alerts (Slack, Discord)
```

---

## 1. Configuration

### IVXCrashlyticsConfig ScriptableObject

Create via **Create > IntelliVerseX > Crashlytics Configuration**.

| Field | Description |
|-------|-------------|
| `EnableCrashReporting` | Master toggle |
| `Backend` | `Nakama`, `Sentry`, `FirebaseCrashlytics`, `Backtrace` |
| `SentryDSN` | Sentry project DSN (if using Sentry) |
| `BreadcrumbCapacity` | Max breadcrumbs to retain (default 50) |
| `CaptureLogErrors` | Auto-capture `Debug.LogError` as non-fatal events |
| `CaptureLogExceptions` | Auto-capture `Debug.LogException` (default true) |
| `CaptureNativeCrashes` | Capture native C/C++ crashes on Android/iOS |
| `ANRTimeoutSec` | Seconds of UI thread stall to flag as ANR on Android (default 5) |
| `AttachScreenshot` | Capture screenshot on crash (increases report size) |
| `MaxReportsPerSession` | Rate limit: max crash reports per session (default 10) |

---

## 2. Automatic Crash Capture

### Unity Setup

The crash reporter hooks into Unity's log callback automatically:

```csharp
using IntelliVerseX.Diagnostics;

IVXCrashReporter.Instance.Initialize();
```

After initialization, all unhandled exceptions and `LogError`/`LogException` calls are captured automatically.

### Manual Exception Reporting

```csharp
try
{
    RiskyOperation();
}
catch (Exception ex)
{
    IVXCrashReporter.Instance.ReportException(ex, new Dictionary<string, string>
    {
        { "operation", "risky_op" },
        { "player_level", "12" },
    });
}
```

### Non-Fatal Error Reporting

```csharp
IVXCrashReporter.Instance.ReportError(
    "network_timeout",
    "Failed to fetch leaderboard after 3 retries",
    severity: ErrorSeverity.Warning,
    metadata: new Dictionary<string, string>
    {
        { "endpoint", "/v2/leaderboard" },
        { "retry_count", "3" },
    }
);
```

---

## 3. Breadcrumbs

Breadcrumbs record the player's recent actions leading up to a crash:

### Automatic Breadcrumbs

The SDK automatically logs these breadcrumb types:

| Type | Example | Auto-Captured |
|------|---------|--------------|
| **Navigation** | Scene loaded, menu opened | Yes |
| **UI** | Button clicked, dialog shown | Yes (if using IVX UI) |
| **Network** | RPC call, socket connect/disconnect | Yes |
| **State** | Login, purchase, level start | Yes |
| **System** | Memory warning, focus lost | Yes |

### Custom Breadcrumbs

```csharp
IVXCrashReporter.Instance.AddBreadcrumb(
    category: "gameplay",
    message: "Boss fight started",
    metadata: new Dictionary<string, string>
    {
        { "boss_id", "dragon_king" },

From intelli-verse-x/Intelli-verse-X-SDK, MIT.

More from intelli-verse-x/Intelli-verse-X-SDK