Troubleshooting

Common issues and solutions for LoopKit integration problems.

Quick Diagnostics

Check Integration Status

Web SDK:

// Verify LoopKit is loaded and initialized
const { isInitialized } = useLoopKit();
console.log('LoopKit initialized:', isInitialized);

// Check configuration
console.log('LoopKit config:', LoopKit.getConfig());

// Test event tracking
track('test_event', { timestamp: Date.now() });

Unity SDK:

// Check initialization status
Debug.Log("LoopKit initialized: " + LoopKit.IsInitialized());

// Verify configuration
Debug.Log("API Key set: " + !string.IsNullOrEmpty(LoopKit.ApiKey));

// Test tracking
LoopKit.Track("test_event", new { test = true });

Verify Network Connectivity

Check API Endpoint:

# Test API connectivity
curl -X POST https://api.loopkit.ai/v1/tracks \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "tracks": [{
      "anonymousId": "test_123",
      "name": "connectivity_test",
      "timestamp": "'$(date -Iseconds)'"
    }]
  }'

Expected Response:

• Success: 204 No Content
• Auth Error: 401 Unauthorized
• Rate Limit: 429 Too Many Requests

Common Issues

1. Events Not Appearing in Dashboard

Symptoms:

• Events tracked but not visible in dashboard
• No error messages in console
• SDK appears to be working

Diagnostic Steps:

// Enable debug mode
LoopKit.setDebug(true);

// Check event queue
console.log('Queue size:', LoopKit.getQueueSize());

// Verify API key format
console.log('API key valid:', /^lk_[a-zA-Z0-9]{32}$/.test(apiKey));

Common Causes:

1. Invalid API Key: Check format and verify in dashboard
2. Network Blocking: Corporate firewalls may block requests
3. Ad Blockers: Some extensions block analytics requests
4. CORS Issues: Verify domain allowlist in dashboard

Solutions:

// Test with minimal event
track('test', {});

// Check browser network tab for failed requests
// Look for 401, 403, or CORS errors

2. High Memory Usage

Symptoms:

• Gradual memory increase over time
• Browser tab becomes sluggish
• Memory warnings in console

Diagnostic Steps:

// Check queue size
console.log('Pending events:', LoopKit.getQueueSize());

// Monitor memory usage
console.log('Memory:', performance.memory);

Solutions:

// Reduce batch size
LoopKit.configure({ batchSize: 10 });

// Increase flush frequency
LoopKit.configure({ flushInterval: 10 });

// Clear queue if needed
LoopKit.clearQueue();

3. Network Request Failures

Symptoms:

• Events queuing but not sending
• Network errors in console
• Repeated retry attempts

Common HTTP Status Codes:

Code	Status	Common Cause	Solution
401	Unauthorized	Invalid/missing API key	Check API key
403	Forbidden	Domain not allowlisted	Add domain to dashboard
413	Payload Too Large	Event too big	Reduce event size
429	Too Many Requests	Rate limit exceeded	Reduce request frequency
500	Internal Server Error	Server issue	Retry with backoff

4. Performance Degradation

Unity-Specific Issues:

Frame Rate Drops:

// ❌ Tracking every frame
void Update() {
    LoopKit.Track("frame_update", new { fps = 1.0f / Time.deltaTime });
}

// ✅ Throttled tracking
void Update() {
    frameCount++;
    if (frameCount % 60 == 0) { // Once per second at 60fps
        LoopKit.Track("performance_sample", new { avg_fps = averageFPS });
    }
}

Memory Leaks:

// ❌ Creating new objects each time
void TrackEvent() {
    LoopKit.Track("event", new Dictionary<string, object> {
        { "level", currentLevel },
        { "score", score }
    });
}

// ✅ Reusing objects
private readonly Dictionary<string, object> reusableProps = new();

void TrackEvent() {
    reusableProps.Clear();
    reusableProps["level"] = currentLevel;
    reusableProps["score"] = score;
    LoopKit.Track("event", reusableProps);
}

❌ Too Frequent Events:

// ❌ Tracking every mouse move
onMouseMove={() => track('mouse_move', { x, y })}

// ✅ Debounced tracking
const debouncedTrack = useCallback(
  debounce((name, props) => track(name, props), 1000),
  []
);

❌ Large Batch Sizes:

// ❌ Too large
<LoopKitProvider options={{ batchSize: 1000 }} />

// ✅ Balanced
<LoopKitProvider options={{ batchSize: 50 }} />

❌ Memory Leaks:

// ✅ Proper cleanup
useEffect(() => {
  const interval = setInterval(() => {
    track('periodic_event');
  }, 10000);

  return () => clearInterval(interval); // Clean up
}, []);

5. Unity-Specific Issues

Build Errors:

Missing Dependencies:

// Ensure all required assemblies are referenced
using System.Collections.Generic;
using UnityEngine;
using LoopKit;

WebGL Compatibility:

// Use WebGL-compatible calls
#if UNITY_WEBGL && !UNITY_EDITOR
    LoopKit.TrackWebGL("event_name", jsonProperties);
#else
    LoopKit.Track("event_name", properties);
#endif

IL2CPP Issues:

// Add to link.xml for IL2CPP builds
<assembly fullname="LoopKit" preserve="all"/>

Platform-Specific Debugging

Web/React Debugging

Developer Tools:

// Check localStorage for queued events
console.log('Queued events:', localStorage.getItem('loopkit_queue'));

// Monitor network requests
// Open DevTools → Network tab → Filter by "loopkit"

// Check for JavaScript errors
window.addEventListener('error', (e) => {
  if (e.filename?.includes('loopkit')) {
    console.error('LoopKit script error:', e);
  }
});

Common React Issues:

// ❌ Multiple providers
function App() {
  return (
    <LoopKitProvider apiKey="key1">
      <LoopKitProvider apiKey="key2">
        {' '}
        {/* Don't do this */}
        <MyApp />
      </LoopKitProvider>
    </LoopKitProvider>
  );
}

// ✅ Single provider at root
function App() {
  return (
    <LoopKitProvider apiKey="your-key">
      <MyApp />
    </LoopKitProvider>
  );
}

Unity Debugging

Console Logging:

// Enable debug logging
LoopKit.SetDebugMode(true);

// Custom logging
public static class LoopKitDebug {
    public static void Log(string message) {
        if (Debug.isDebugBuild) {
            Debug.Log($"[LoopKit] {message}");
        }
    }
}

Event Inspector:

// Create inspector window for events
#if UNITY_EDITOR
[MenuItem("LoopKit/Event Inspector")]
public static void ShowEventInspector() {
    EditorWindow.GetWindow<LoopKitEventInspector>();
}
#endif

API Debugging

Request/Response Inspection

Enable Verbose Logging:

// Web SDK
LoopKit.configure({
  debug: true,
  logLevel: 'verbose',
  enableNetworkLogs: true,
});

// Check browser network tab for detailed request/response data

Unity Network Debugging:

// Enable network logging
LoopKit.Configure(new LoopKitConfig {
    debug = true,
    logNetworkRequests = true
});

Common API Errors

Code	Status	Common Cause	Solution
400	Bad Request	Invalid event format	Check event schema
401	Unauthorized	Invalid/missing API key	Verify API key
403	Forbidden	Domain not allowlisted	Add domain to dashboard
413	Payload Too Large	Event too big	Reduce event size
429	Too Many Requests	Rate limit exceeded	Reduce request frequency
500	Internal Server Error	Server issue	Retry with backoff

SDK Error Codes

JavaScript SDK:

// Error handling
LoopKit.onError((error) => {
  switch (error.code) {
    case 'NETWORK_ERROR':
      console.log('Network issue, events will retry');
      break;
    case 'INVALID_EVENT':
      console.error('Invalid event format:', error.event);
      break;
    case 'RATE_LIMITED':
      console.warn('Rate limited, slowing down');
      break;
    case 'STORAGE_QUOTA_EXCEEDED':
      console.error('Local storage full');
      LoopKit.clearQueue();
      break;
  }
});

Debug Mode Features

Enable Debug Mode

Web SDK:

<LoopKitProvider
  options={{
    debug: true,
    logLevel: 'verbose',
    enableTimings: true,
    enableNetworkLogs: true,
  }}
/>

Unity SDK:

LoopKit.Initialize("your-key", new LoopKitConfig {
    debug = true,
    logLevel = LogLevel.Verbose,
    enableEventInspector = true
});

Debug Information

Available Debug Data:

• Event queue status
• Network request/response logs
• Performance timing data
• Memory usage statistics
• Error stack traces

Debug Commands:

// Console commands (development only)
LoopKit.debug.getQueueSize(); // Current queue length
LoopKit.debug.getMemoryUsage(); // Memory consumption
LoopKit.debug.clearQueue(); // Clear pending events
LoopKit.debug.getNetworkStats(); // Request statistics
LoopKit.debug.simulateError(); // Test error handling

Performance Monitoring

Built-in Monitoring

// Enable performance monitoring
LoopKit.configure({
  enablePerformanceMonitoring: true,
  performanceThresholds: {
    trackingLatency: 10, // ms
    queueSize: 100, // events
    memoryUsage: 5, // MB
  },
});

// Monitor performance metrics
LoopKit.onPerformanceIssue((issue) => {
  console.warn('Performance issue detected:', issue);
});

Getting Help

Self-Service Resources

1. API Documentation: api.loopkit.ai/docs
2. GitHub Issues: github.com/loopkit/issues
3. Discord Community: discord.gg/loopkit

Debug Information to Include

When requesting support, include:

// Generate debug report
const debugInfo = {
  sdk: LoopKit.version,
  browser: navigator.userAgent,
  config: LoopKit.getConfig(),
  queueSize: LoopKit.getQueueSize(),
  lastError: LoopKit.getLastError(),
  networkStats: LoopKit.getNetworkStats(),
};

console.log('LoopKit Debug Info:', JSON.stringify(debugInfo, null, 2));

Unity Debug Info:

Debug.Log($"Unity Version: {Application.unityVersion}");
Debug.Log($"Platform: {Application.platform}");
Debug.Log($"LoopKit Version: {LoopKit.Version}");
Debug.Log($"Queue Size: {LoopKit.GetQueueSize()}");
Debug.Log($"Last Error: {LoopKit.GetLastError()}");

---

Need more help? Join our Discord for live support.