SparkGames Documentation

Everything you need to integrate AI-powered analytics into your game. From first install to production-ready dashboards in under an hour.

Quick Start

Get up and running with SparkGames in three simple steps. No data engineering experience required.

bash
# Unity - add via Package Manager
# Window > Package Manager > + > Add package from git URL
https://github.com/sparkgames/unity-sdk.git

# Unreal - add to .uproject plugins
# Or install via Epic Marketplace: "SparkGames Analytics"

# Godot - add via AssetLib or download from GitHub
https://github.com/sparkgames/godot-sdk

C#
// Initialize in your game's entry point
SparkAnalytics.Init("YOUR_API_KEY");

// Track custom events
SparkAnalytics.Track("level_complete", new Dictionary<string, object> {
    { "level_id", 42 },
    { "time_seconds", 187.5 },
    { "deaths", 3 },
    { "score", 94200 }
});

Installation

Detailed installation guides for every supported platform.

Unity SDK

Requires Unity 2020.3 LTS or newer. Supports IL2CPP and Mono backends.

C#
// 1. Import the SparkGames package
using SparkGames.Analytics;

// 2. Initialize in Awake() or Start()
public class GameManager : MonoBehaviour {
    void Awake() {
        SparkAnalytics.Init("sk_live_your_api_key", new SparkConfig {
            EnableAutoEvents = true,    // auto-track sessions, crashes
            BatchInterval = 30,         // send events every 30 seconds
            LogLevel = SparkLogLevel.Warning
        });
    }
}

// 3. Track events anywhere in your code
SparkAnalytics.Track("player_death", new Dictionary<string, object> {
    { "level", "dungeon_03" },
    { "enemy", "boss_dragon" },
    { "player_hp", 0 }
});

Unreal Engine SDK

Supports UE 4.27+ and Unreal Engine 5.x. C++ and Blueprint compatible.

C++
// 1. Add to your Build.cs
PublicDependencyModuleNames.Add("SparkGamesSDK");

// 2. Initialize in your GameInstance
#include "SparkAnalytics.h"

void UMyGameInstance::Init() {
    Super::Init();
    USparkAnalytics::Initialize("sk_live_your_api_key");
    USparkAnalytics::SetAutoEvents(true);
}

// 3. Track events
TMap<FString, FString> Props;
Props.Add("weapon", "plasma_rifle");
Props.Add("damage", "450");
USparkAnalytics::Track("enemy_killed", Props);

Godot SDK

Supports Godot 4.0+ with GDScript and C# bindings.

GDScript
# 1. Add the SparkGames addon to res://addons/sparkgames/
# 2. Enable in Project > Project Settings > Plugins

# 3. Initialize in your autoload
func _ready():
    SparkAnalytics.init("sk_live_your_api_key", {
        "auto_events": true,
        "batch_interval": 30
    })

# 4. Track events
SparkAnalytics.track("item_collected", {
    "item_id": "gold_key",
    "zone": "forest_temple",
    "player_level": 12
})

REST API (Any Platform)

Use the REST API for custom engines, backend integrations, or any language.

bash
curl -X POST https://api.sparkgamesusa.com/v1/events \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "level_complete",
    "player_id": "usr_abc123",
    "properties": {
      "level_id": 42,
      "time_seconds": 187.5,
      "score": 94200
    },
    "timestamp": "2026-05-14T10:30:00Z"
  }'

API Reference

Base URL: https://api.sparkgamesusa.com/v1. All endpoints require a valid API key in the Authorization header.

Send Events

Submit player events for analytics processing. Supports single events or batches of up to 1,000 events.

Request
{
  "event": "purchase",
  "player_id": "usr_abc123",
  "properties": {
    "item_id": "gem_pack_500",
    "price_usd": 4.99,
    "currency_type": "real",
    "store": "ios_appstore"
  },
  "timestamp": "2026-05-14T10:30:00Z"
}

// Response: 201 Created
{
  "status": "accepted",
  "event_id": "evt_7f8a9b2c",
  "processed_at": "2026-05-14T10:30:00.142Z"
}

Get Analytics

Retrieve analytics metrics for your game. Supports DAU, retention, revenue, session length, and 40+ additional metrics.

Response 200
{
  "metric": "dau",
  "period": "7d",
  "game_id": "gm_123",
  "data": [
    { "date": "2026-05-08", "value": 124500 },
    { "date": "2026-05-09", "value": 131200 },
    { "date": "2026-05-10", "value": 128900 },
    { "date": "2026-05-11", "value": 142300 },
    { "date": "2026-05-12", "value": 139800 },
    { "date": "2026-05-13", "value": 145600 },
    { "date": "2026-05-14", "value": 151200 }
  ],
  "trend": "+8.2%"
}

Get Predictions

Retrieve AI-generated predictions for churn risk, LTV forecasts, and engagement scoring.

Response 200
{
  "type": "churn",
  "game_id": "gm_123",
  "threshold": 0.7,
  "at_risk_players": 3842,
  "predictions": [
    {
      "player_id": "usr_abc123",
      "churn_probability": 0.87,
      "predicted_churn_date": "2026-05-18",
      "risk_factors": ["session_frequency_decline", "iap_stall"],
      "recommended_action": "personalized_offer"
    }
  ],
  "model_accuracy": 0.94,
  "generated_at": "2026-05-14T06:00:00Z"
}

Create Segments

Create AI-powered player segments based on behavior, spending, engagement, or custom rules.

Request
{
  "name": "High-Value At-Risk",
  "game_id": "gm_123",
  "rules": [
    { "metric": "ltv", "operator": "gte", "value": 50 },
    { "metric": "churn_risk", "operator": "gte", "value": 0.6 },
    { "metric": "days_since_last_session", "operator": "lte", "value": 7 }
  ]
}

// Response: 201 Created
{
  "segment_id": "seg_4d5e6f",
  "name": "High-Value At-Risk",
  "player_count": 1247,
  "created_at": "2026-05-14T10:30:00Z"
}

Code Examples

Unity C# - Complete Integration

A full example showing initialization, event tracking, player identification, and accessing predictions from within Unity.

C#
using UnityEngine;
using SparkGames.Analytics;
using System.Collections.Generic;

public class SparkIntegration : MonoBehaviour
{
    [SerializeField] private string apiKey = "sk_live_your_api_key";

    void Awake()
    {
        // Initialize SDK
        SparkAnalytics.Init(apiKey, new SparkConfig {
            EnableAutoEvents = true,
            BatchInterval = 30,
            LogLevel = SparkLogLevel.Warning
        });

        // Identify player (after login)
        SparkAnalytics.Identify("player_12345", new Dictionary<string, object> {
            { "name", "DragonSlayer99" },
            { "install_date", "2026-01-15" },
            { "platform", Application.platform.ToString() }
        });
    }

    // Track a level completion
    public void OnLevelComplete(int levelId, float timeSec, int score)
    {
        SparkAnalytics.Track("level_complete", new Dictionary<string, object> {
            { "level_id", levelId },
            { "time_seconds", timeSec },
            { "score", score },
            { "difficulty", GameSettings.Difficulty }
        });
    }

    // Track a purchase
    public void OnPurchase(string itemId, float price)
    {
        SparkAnalytics.Track("purchase", new Dictionary<string, object> {
            { "item_id", itemId },
            { "price_usd", price },
            { "store", "unity_iap" }
        });
    }

    // Get churn prediction for current player
    public async void CheckChurnRisk()
    {
        var prediction = await SparkAnalytics.GetPrediction("churn");
        if (prediction.Probability > 0.7f)
        {
            Debug.Log($"High churn risk: {prediction.Probability:P0}");
            // Trigger a retention offer
            ShowRetentionOffer(prediction.RecommendedAction);
        }
    }

    void OnApplicationQuit()
    {
        SparkAnalytics.Flush(); // Send remaining events
    }
}

REST API - Python Example

Send events and query analytics using Python and the REST API.

Python
import requests
import json
from datetime import datetime

API_KEY = "sk_live_your_api_key"
BASE_URL = "https://api.sparkgamesusa.com/v1"
HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

# Send an event
def track_event(player_id, event_name, properties):
    payload = {
        "event": event_name,
        "player_id": player_id,
        "properties": properties,
        "timestamp": datetime.utcnow().isoformat() + "Z"
    }
    response = requests.post(
        f"{BASE_URL}/events",
        headers=HEADERS,
        json=payload
    )
    return response.json()

# Get analytics
def get_analytics(metric, period="7d", game_id="gm_123"):
    response = requests.get(
        f"{BASE_URL}/analytics",
        headers=HEADERS,
        params={"metric": metric, "period": period, "game_id": game_id}
    )
    return response.json()

# Get churn predictions
def get_churn_predictions(game_id="gm_123", threshold=0.7):
    response = requests.get(
        f"{BASE_URL}/predictions",
        headers=HEADERS,
        params={"type": "churn", "game_id": game_id, "threshold": threshold}
    )
    return response.json()

# Usage
track_event("usr_abc123", "level_complete", {
    "level_id": 42,
    "time_seconds": 187.5,
    "score": 94200
})

dau_data = get_analytics("dau", "30d")
churn = get_churn_predictions(threshold=0.8)
print(f"At-risk players: {churn['at_risk_players']}")

SDKs

Official SDKs for all major game engines and platforms.

Support

Need help? Our team and community are here for you.