Analytics Toolkit - Setup Guide

This guide covers setting up Analytics Toolkit with various backends and implementing GDPR-compliant tracking.

Basic Installation

1. Install Plugin

   Extract to YourProject/Plugins/AnalyticsToolkit/

2. Activate License

   Project Settings → Plugins → gameDNA Analytics Toolkit Enter your license key and click Activate.

3. Choose Backend

   Select your analytics provider (or use Local for testing).

4. Initialize

   Add initialization to your Game Instance or first level:

   Event Init
   → Initialize Analytics
   → On Success: Set bAnalyticsReady = true

Backend Configuration

GameAnalytics

1. Create account at gameanalytics.com
2. Create a new game, note your Game Key and Secret Key
3. Configure in Project Settings:

   Analytics Backend: GameAnalytics
   GameAnalytics Game Key: YOUR_GAME_KEY
   GameAnalytics Secret Key: YOUR_SECRET_KEY

4. Events auto-map to GameAnalytics format

Automatic Mappings:

• level_complete → Progression event
• purchase → Business event
• error → Error event
• Custom events → Design events

Custom REST API

1. Set up your analytics endpoint
2. Configure in Project Settings:

   Analytics Backend: Custom REST
   REST Endpoint: https://api.yoursite.com/analytics
   REST Auth Header: X-API-Key
   REST Auth Token: your-api-key

3. Events sent as JSON POST:

   {
     "event_name": "level_complete",
     "timestamp": "2026-01-22T12:00:00Z",
     "session_id": "abc123",
     "user_id": "user_456",
     "properties": {
       "level": 5,
       "score": 1000
     }
   }

Local File

For development and testing:

Analytics Backend: Local File
Local File Path: Saved/Analytics/

Events are saved as JSON files. Perfect for:

• Development without backend
• Debugging event flow
• Unit testing

Tracking Events

Basic Event

Track Analytics Event
→ Event Name: "button_clicked"
→ Properties:
    → button_name: "play"
    → screen: "main_menu"

Event with Numeric Value

Track Analytics Event
→ Event Name: "item_purchased"
→ Properties:
    → item_id: "sword_01"
    → item_name: "Iron Sword"
    → price: 100
    → currency: "gold"
→ Value: 100

Timed Event

// Start timer
Start Timed Event (EventName: "tutorial_section_1")

// ... player completes section ...

// End timer (duration auto-calculated)
End Timed Event (EventName: "tutorial_section_1")
→ Additional Properties:
    → completed: true
    → hints_used: 2

Session Management

Sessions are tracked automatically, but you can customize:

// Manual session start
Start Analytics Session
→ Session Properties:
    → game_version: "1.2.0"
    → platform: GetPlatformName()
    → country: GetPlayerCountry()

// Session ends automatically on:
// - App backgrounded (mobile)
// - Game closed
// - 30 min inactivity (configurable)

// Manual session end
End Analytics Session
→ Reason: "player_quit"

User Identification

Anonymous Users

By default, users get a device-based anonymous ID:

Get Anonymous User ID
→ Returns: "anon_a1b2c3d4e5f6"

Identified Users

When a user logs in:

On Player Login (UserID, DisplayName)
→ Identify Analytics User
    → User ID: UserID
    → Properties:
        → display_name: DisplayName
        → account_created: AccountDate
        → subscription_tier: "premium"

User Properties

Update user properties over time:

Set Analytics User Property
→ Name: "total_playtime_hours"
→ Value: GetTotalPlaytime()

Set Analytics User Properties (Batch)
→ Properties Map:
    → level: 50
    → achievements_unlocked: 25
    → friends_count: 12

GDPR Compliance (v1.5+)

Consent Management

1. Show Consent Dialog

   On first launch, show the consent UI:

   // Check if consent needed
   Needs Analytics Consent
   → Branch: true?
     → Show Widget: WBP_ConsentDialog

2. Handle Consent Response

   // In your consent dialog widget
   On Accept Pressed
   → Set Analytics Consent (Granted: true)
   → Start Analytics Session
   
   On Decline Pressed
   → Set Analytics Consent (Granted: false)
   // Analytics will not track this user

3. Check Consent Status

   Get Analytics Consent Status
   → Switch:
     → Granted: Full tracking
     → Denied: No tracking
     → Unknown: Show consent dialog

Built-in Consent UI

The plugin includes a ready-to-use consent widget:

// Show built-in dialog
Show Analytics Consent Dialog
→ Style: Minimal / Detailed / Custom
→ On Complete (Granted):
    → Branch: Granted?
      → True: Initialize Analytics
      → False: Continue without analytics

Data Export & Deletion

For GDPR data requests:

// Export user data
Export Analytics User Data (UserID)
→ On Complete (JSONData):
    → Send to User via Email/Download

// Delete user data
Delete Analytics User Data (UserID)
→ On Complete:
    → Print "User data deleted"

Caution

Data deletion sends a request to your backend. Ensure your backend implements the deletion endpoint.

A/B Testing

Run experiments to optimize your game:

1. Define Experiment

   Create Experiment
   → Name: "tutorial_length"
   → Variants:
     → "control": weight=50
     → "short": weight=25
     → "long": weight=25

2. Get Variant

   Get Experiment Variant (ExperimentName: "tutorial_length")
   → Switch on Variant:
     → "control": Use default tutorial
     → "short": Skip to gameplay faster
     → "long": Add extra explanation steps

3. Track Conversion

   // When user completes goal
   Track Experiment Conversion
   → Experiment: "tutorial_length"
   → Conversion Event: "tutorial_complete"

Heatmaps

Track position-based events:

// Track player death locations
On Player Death (Location)
→ Track Heatmap Event
    → Event Name: "player_death"
    → Position: Location
    → Map Name: GetCurrentMapName()

// Track item pickups
On Item Collected (ItemType, Location)
→ Track Heatmap Event
    → Event Name: "item_collected"
    → Position: Location
    → Properties:
        → item_type: ItemType

Visualize in the optional dashboard or export for external tools.

Offline Support

Events are cached when offline:

// Configuration
Project Settings:
  Enable Offline Caching: true
  Max Cached Events: 1000
  Cache Expiry Days: 7

// Events auto-send when online
// Or manually flush:
Flush Cached Analytics Events

Performance Best Practices

1. Batch Events

   The plugin auto-batches, but you can control timing:

   Set Analytics Batch Interval (Seconds: 30)
   Set Analytics Batch Size (Count: 50)

2. Sample High-Frequency Events

   For events that fire constantly:

   // Only track 10% of position updates
   Track Sampled Event
   → Event Name: "player_position"
   → Sample Rate: 0.1

3. Use Appropriate Data Types

   • Use numbers for numeric values (not strings)
   • Keep property names short
   • Limit properties per event to ~10

Troubleshooting

Issue	Solution
Events not appearing	Check backend credentials and network
Session not starting	Ensure Initialize is called first
Consent dialog not showing	Check Needs Analytics Consent logic
High memory usage	Reduce batch size, enable sampling

Debug Mode

Project Settings:
  Enable Debug Logging: true
  Log Events to Screen: true

Events will print to screen and Output Log.

Next Steps

• Plugin Overview - Feature list
• GDPR Guide - Official GDPR information
• GameAnalytics Docs - GameAnalytics documentation