ivx-analytics-pipeline

Files (1)

• SKILL.md

SKILL.md (first lines)

# IntelliVerseX Analytics Pipeline

## Overview

The Analytics Pipeline provides a unified event tracking, funnel analysis, and data export system across all 10 supported engines. Built on top of the Satori analytics backend, it adds structured taxonomy enforcement, pre-built funnel definitions, cohort analysis helpers, and one-click export to warehouse targets (BigQuery, Snowflake, Redshift, S3).

```
Game Client → IVXAnalyticsManager → Satori Events API → Data Lake Export
                    │                       │
              Event Taxonomy          Audiences / Flags
              (validation)            (segmentation)
```

---

## 1. Configuration

### IVXAnalyticsConfig ScriptableObject

Create via **Create > IntelliVerseX > Analytics Configuration**.

| Field | Description |
|-------|-------------|
| `EnableAnalytics` | Master toggle for event tracking |
| `TaxonomyMode` | `Permissive` (log unknown events) or `Strict` (reject unknown events) |
| `BatchSize` | Number of events to batch before flushing (default 10) |
| `FlushIntervalSec` | Max seconds between flushes (default 30) |
| `EnableOfflineQueue` | Queue events when offline, flush on reconnect |
| `OfflineQueueMaxSize` | Max queued events before oldest are dropped (default 500) |
| `EnableDebugLogging` | Log all events to Unity console |
| `SamplingRate` | 0.0–1.0, percentage of sessions that track events (default 1.0) |

---

## 2. Event Taxonomy

### Taxonomy Categories

Every event belongs to one of six categories following the `category.action.detail` naming convention:

| Category | Examples | Purpose |
|----------|----------|---------|
| `engagement` | `engagement.session_start`, `engagement.session_end` | Session and attention metrics |
| `progression` | `progression.level_complete`, `progression.tutorial_step` | Player advancement tracking |
| `monetization` | `monetization.purchase`, `monetization.ad_viewed` | Revenue events |
| `social` | `social.friend_added`, `social.chat_message` | Social feature usage |
| `system` | `system.error`, `system.performance` | Technical health metrics |
| `custom` | `custom.*` | Game-specific events |

### Defining Event Schemas

```csharp
using IntelliVerseX.Analytics;

IVXEventTaxonomy.Instance.DefineEvent(new EventSchema
{
    Name = "progression.level_complete",
    Category = EventCategory.Progression,
    RequiredMetadata = new[] { "level_id", "score" },
    OptionalMetadata = new[] { "time_sec", "hints_used", "stars" },
    MetadataTypes = new Dictionary<string, MetadataType>
    {
        { "level_id", MetadataType.String },
        { "score", MetadataType.Number },
        { "time_sec", MetadataType.Number },
        { "hints_used", MetadataType.Number },
        { "stars", MetadataType.Number },
    },
});
```

### Tracking Events

```csharp
IVXAnalyticsManager.Instance.Track("progression.level_complete", new Dictionary<string, string>
{
    { "level_id", "world_1_boss" },
    { "score", "12500" },
    { "time_sec", "142" },
    { "stars", "3" },
});
```

In `Strict` taxonomy mode, events without a registered schema are rejected and logged as warnings.

### Validating Events (Development)

```csharp
var result = IVXEventTaxonomy.Instance.Validate("progression.level_complete", metadata);
if (!result.Valid)
{
    Debug.LogWarning($"Event validation failed: {string.Join(", ", result.Errors)}");
}
```

---

## 3. Pre-Built Funnels

### IVXFunnelBuilder

Define multi-step funnels and query conversion rates:

```csharp
using IntelliVerseX.Analytics;

var onboardingFunnel = IVXFunnelBuilder.Create("onboarding")
    .Step("engagement.session_start")
    .Step("progression.tutorial_step", metadata => metadata["step"] == "1")
    .Step("progression.tutorial_step", metadata => metadata["step"] == "3")
    .Step("progression.tutorial_complete")
    .Step("monetization.first_purchase")
    .Build();

IVXAnalyticsManager.Instance.RegisterFunnel(onboardingFunnel);
```

### Pre-Defined Funnel Templates

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

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