Unreal Engine Plugin Setup Guide

Complete setup guide for integrating Tokebi analytics into your Unreal Engine projects.

v1.0 plugin with custom Blueprint nodes, Project Settings UI, and automatic batching for production games.

🚀 Quick Setup Overview

Get analytics running in under 10 minutes! The Tokebi Unreal Engine Plugin provides production-ready analytics with Blueprint nodes and C++ support.

📦

1. Install

Download & Copy Plugin Files

🔧

2. Setup

Edit → Project Settings → Plugins

📊

3. Track

Use Blueprint nodes or C++

📦 Step 1: Installation Methods

🎯 Choose Your Installation Method

Two ways to install the Tokebi Unreal Engine Plugin. Both methods give you the same production-ready plugin with Blueprint nodes and C++ support.

📦 Method 1: GitHub Download (Recommended)

Installation Steps

1. Download the plugin from GitHub as ZIP
2. Extract to your project's Plugins/ folder
3. Enable in Edit → Plugins → Search "Tokebi Analytics"
4. Restart Unreal Editor when prompted
5. Configure in Edit → Project Settings → Plugins → Tokebi Analytics

✅ Gets you: Complete plugin with Blueprint nodes and C++ support

What You Get

• Custom Blueprint nodes for analytics
• Project Settings UI integration
• Automatic event batching (30s intervals)
• C++ function library support
• Persistent player ID management
• Cross-platform compatibility
• Manual flush control
• Offline event queuing

Download from GitHub

🔧 Method 2: Manual File Structure

Create Plugin Directory

Create folder structure in your project:

YourProject/
├── Plugins/
│   └── TokebiAnalytics/
│       ├── TokebiAnalytics.uplugin
│       └── Source/
│           └── TokebiAnalytics/

Copy Source Files

Place these 7 files in Source/TokebiAnalytics/:

TokebiAnalytics.Build.cs
TokebiAnalyticsModule.h
TokebiAnalyticsModule.cpp
TokebiAnalyticsFunctions.h
TokebiAnalyticsFunctions.cpp
TokebiAnalyticsSettings.h
TokebiAnalyticsSettings.cpp

Enable & Configure

Enable the plugin and configure your API key in Project Settings

✅ Important: ALL files go directly in Source/TokebiAnalytics/ - NO Public/Private subfolders

⚙️ Step 2: Setup & Configuration

🚀 Project Settings Configuration

Configuration Steps

1. Get your API Key from tokebimetrics.com
2. Go to Edit → Project Settings
3. Navigate to Plugins → Tokebi Analytics
4. Enter your API Key
5. Set your Game ID (or leave empty for auto-generation)
6. Choose Environment (development/production)

💡 Tip: The plugin refuses to send events if API Key is not configured - ensuring no accidental test data!

Available Settings

API Key ✅ (Required)

Your Tokebi authentication key

Game ID ⚪ (Optional)

Unique identifier (auto-generated if empty)

API Endpoint ⚪ (Optional)

Defaults to Tokebi production API

Environment ⚪ (Optional)

development or production

ℹ️ Note: Settings are saved per-project and persist across sessions.

🎮 Plugin Features & Performance

⚡ Performance Features

• Automatic batching (30-second intervals)
• World context intelligence (Editor + PIE + Shipping)
• Thread-safe event queuing
• Offline event storage
• Automatic retry logic
• Manual flush control
• Persistent player IDs

🔧 Perfect For

• PC, Console & Mobile games
• Blueprint-heavy projects
• C++ development
• Production games requiring stability
• Cross-platform deployment
• Projects needing professional analytics UI

📊 Step 3: Basic Usage

🎯 Blueprint Usage

Available Blueprint Nodes

Session Management

• Tokebi Start Session - Initialize analytics
• Tokebi End Session - Clean up & flush events

Event Tracking

• Tokebi Track - Custom events with data
• Tokebi Track Level Start - Level begins
• Tokebi Track Level Complete - Level ends
• Tokebi Track Purchase - In-game purchases

Example Blueprint Flow

BeginPlay → Delay (1.0 second) → Tokebi Start Session

[Player Clicks Button] → Tokebi Track
    ├─ Event Name: "button_clicked"  
    └─ Event Data: {"button_name": "play", "screen": "main_menu"}

[Level Starts] → Tokebi Track Level Start
    └─ Level Name: "forest_level_1"

[Level Complete] → Tokebi Track Level Complete
    ├─ Level Name: "forest_level_1"
    ├─ Completion Time: 67.5
    └─ Score: 1500

EndPlay → Tokebi End Session

⚡ Pro Tip: Add a 1-2 second delay after BeginPlay before starting analytics to ensure proper initialization.

💻 C++ Usage

Complete C++ Integration Example

#include "TokebiAnalyticsFunctions.h"

// Session Management  
void AYourGameMode::BeginPlay()
{
    Super::BeginPlay();
    
    // Delay analytics initialization (recommended)
    FTimerHandle TimerHandle;
    GetWorldTimerManager().SetTimer(TimerHandle, [this]()
    {
        UTokebiAnalyticsFunctions::TokebiStartSession();
    }, 1.0f, false);
}

// Custom Event Tracking
void TrackButtonClick(const FString& ButtonName, const FString& Screen)
{
    TMap<FString, FString> EventData;
    EventData.Add(TEXT("button_name"), ButtonName);
    EventData.Add(TEXT("screen"), Screen);
    EventData.Add(TEXT("timestamp"), FString::FromInt(FDateTime::UtcNow().ToUnixTimestamp()));
    
    UTokebiAnalyticsFunctions::TokebiTrack(TEXT("button_clicked"), EventData);
}

// Level Events
void OnLevelStart(const FString& LevelName)
{
    UTokebiAnalyticsFunctions::TokebiTrackLevelStart(LevelName);
}

void OnLevelComplete(const FString& LevelName, float CompletionTime, int32 Score)
{
    UTokebiAnalyticsFunctions::TokebiTrackLevelComplete(LevelName, CompletionTime, Score);
}

// Manual Control
void ForceFlushEvents()
{
    UTokebiAnalyticsFunctions::TokebiFlushEvents();
}

🚀 Advanced Features

⚡ Smart Batching & Flushing

Automatic Batching

• 30-second intervals (configurable)
• 50 events per batch (configurable)
• Smart timing: Immediate flush on session end
• World context intelligence for timers
• Offline queuing when connection lost

Manual Control

Force immediate event delivery when needed:

Blueprint: Use "Tokebi Flush Events" node

C++: UTokebiAnalyticsFunctions::TokebiFlushEvents()

🎮 Game Registration

• Automatic registration on first use
• Game ID generation if not configured
• Retry logic for failed registrations
• Manual trigger: TokebiRegisterGame()

👤 Player ID Management

• Persistent IDs across sessions
• Saved to: ProjectSaved/Analytics/
• Automatic generation on first run
• Cross-platform consistency

📋 Requirements & Compatibility

✅ System Requirements

• Unreal Engine 5.0+ (recommended)
• Unreal Engine 4.27+ (compatibility)
• C++ Project Support (has Source folder)
• Tokebi Metrics account
• API key from dashboard
• Internet connection for events

🌐 Platform Support

• Windows, Mac, Linux
• PlayStation, Xbox, Nintendo Switch
• iOS, Android
• All Unreal Engine supported platforms

💡 Get your account at tokebimetrics.com

🗃️ Data Format

📡 Event Data Structure

All events sent to Tokebi follow this standardized JSON format:

Single Event Format

{
  "eventType": "level_complete",
  "payload": {
    "level": "level_1",
    "score": 1500,
    "timestamp": 1642123456
  },
  "gameId": "your_game_id",
  "playerId": "player_1642123400_7834",
  "platform": "unreal",
  "environment": "development"
}

Game Registration

POST /api/games
{
  "gameTitle": "Your Game Name",
  "platform": "unreal",
  "apiKey": "your_api_key"
}

Response:
{
  "gameId": "generated_game_id",
  "status": "success"
}

🔧 Troubleshooting

❌ Plugin Not Loading

• Check TokebiAnalytics plugin is enabled in Edit → Plugins
• Verify all 7 source files are in correct locations (no Public/Private folders)
• Restart the editor after enabling
• Ensure project is C++ enabled (has Source folder)
• Try regenerating project files (.uproject → Generate Visual Studio project files)

⚠️ Events Not Sending

• Check API key is configured in Project Settings → Plugins → Tokebi Analytics
• Verify internet connection
• Look for errors in Output Log (search "Tokebi")
• Try manual flush: UTokebiAnalyticsFunctions::TokebiFlushEvents()
• Enable verbose logging: LogTokebiAnalytics=Verbose

🔄 Timer/Auto-Flush Issues

• Check logs for "Using [play/editor/context] world for timer"
• Verify world context is available when initializing
• Manual flush always works regardless of timer status
• Use delayed initialization (1-2 second delay after BeginPlay)

🔨 Build Errors

• Make sure HTTP, Json, and Engine modules are available
• Check that your project supports plugins
• Delete Binaries and Intermediate folders, then rebuild
• Ensure all files are in Source/TokebiAnalytics/ (not in Public/Private subfolders)

🎯 You're Ready!

Your Unreal Engine project is now equipped with powerful analytics. The plugin provides production-ready performance with Blueprint nodes, C++ support, and automatic batching.

Check your Tokebi dashboard to see events in real-time and explore the Dashboard and Funnel Analytics features.