Version 1.34.2 | Production Ready | Unreal Engine 5.5+
WebSocket connections in the Supabase UE5 Plugin provide real-time functionality through the AsyncRealtime class, enabling live database change subscriptions with production-grade reliability, thread safety, and automatic reconnection handling.
The WebSocket implementation uses Supabase’s Realtime WebSocket API to establish persistent connections for real-time database updates. The system is built with enterprise-grade reliability featuring automatic reconnection, connection health monitoring, and comprehensive error handling.
Thread-Safe Operations: All WebSocket operations are thread-safe with proper mutex locking and safe delegate broadcasting to prevent race conditions in multiplayer scenarios.
Automatic Reconnection: Intelligent reconnection strategy with exponential backoff and jitter to prevent connection storms during network interruptions.
Connection Health Monitoring: Built-in heartbeat mechanism ensures connection reliability with configurable intervals and timeout detection.
State Management: Comprehensive connection state tracking with proper transition handling and event broadcasting for UI integration.
Memory Safety: Automatic cleanup and weak reference patterns prevent memory leaks and ensure proper resource management.
The WebSocket connection uses the ERealtimeConnectionState enum to track connection lifecycle:
Use the Subscribe to Realtime node in Blueprint:
// Simple subscription to a table
UAsyncRealtime* RealtimeTask = UAsyncRealtime::SubscribeToRealtime(
this,
TEXT("users")
);
// Bind events
RealtimeTask->OnDataReceived.AddDynamic(this, &AMyActor::OnRealtimeData);
RealtimeTask->OnConnectionStateChanged.AddDynamic(this, &AMyActor::OnConnectionStateChanged);
// Activate subscription
RealtimeTask->Activate();
// Create realtime subscription
UAsyncRealtime* RealtimeSubscription = UAsyncRealtime::SubscribeToRealtimeAdvanced(
this,
TEXT("game_sessions"),
{TEXT("INSERT"), TEXT("UPDATE"), TEXT("DELETE")},
ESupabaseKey::Service,
30.0f, // Heartbeat interval
true, // Enable reconnection
5, // Max reconnect attempts
30.0f, // Connection timeout
TEXT("public") // Schema
);
// Bind event handlers
RealtimeSubscription->OnDataReceived.AddDynamic(this, &AGameManager::HandleRealtimeUpdate);
RealtimeSubscription->OnConnectionStateChanged.AddDynamic(this, &AGameManager::HandleConnectionState);
RealtimeSubscription->OnFailure.AddDynamic(this, &AGameManager::HandleRealtimeError);
// Start subscription
RealtimeSubscription->Activate();
Heartbeat Interval: Configure how often heartbeat messages are sent to maintain connection (default: 30 seconds).
Reconnection Settings: Control automatic reconnection behavior with maximum attempts and exponential backoff timing.
Connection Timeout: Set maximum time to wait for initial connection establishment (default: 30 seconds).
Event Filtering: Subscribe to specific database events (INSERT, UPDATE, DELETE) or all events (*).
Schema Selection: Specify database schema for subscriptions (default: “public”).
UAsyncRealtime* AdvancedSubscription = UAsyncRealtime::SubscribeToRealtimeAdvanced(
this,
TEXT("player_inventory"),
{TEXT("INSERT"), TEXT("UPDATE")}, // Only listen for inserts and updates
ESupabaseKey::Service,
15.0f, // More frequent heartbeats for critical data
true, // Enable auto-reconnection
10, // Higher reconnection attempts for critical connections
45.0f, // Longer timeout for slow networks
TEXT("game_data") // Custom schema
);
// Check connection state
ERealtimeConnectionState CurrentState = RealtimeSubscription->GetConnectionState();
// Manual reconnection
if (CurrentState == ERealtimeConnectionState::Error) {
RealtimeSubscription->Reconnect();
}
// Manual disconnection
RealtimeSubscription->Disconnect();
// Health check
bool bIsHealthy = RealtimeSubscription->IsConnectionHealthy();
UFUNCTION()
void AMyActor::OnRealtimeData(const FString& EventType, const FString& TableName, const FJsonObjectWrapper& Data) {
if (EventType == TEXT("INSERT")) {
// Handle new record
UE_LOG(LogTemp, Log, TEXT("New record added to %s"), *TableName);
}
else if (EventType == TEXT("UPDATE")) {
// Handle record update
UE_LOG(LogTemp, Log, TEXT("Record updated in %s"), *TableName);
}
else if (EventType == TEXT("DELETE")) {
// Handle record deletion
UE_LOG(LogTemp, Log, TEXT("Record deleted from %s"), *TableName);
}
}
UFUNCTION()
void AMyActor::OnConnectionStateChanged(ERealtimeConnectionState NewState) {
switch (NewState) {
case ERealtimeConnectionState::Connected:
UE_LOG(LogTemp, Log, TEXT("WebSocket connected"));
break;
case ERealtimeConnectionState::Subscribed:
UE_LOG(LogTemp, Log, TEXT("Successfully subscribed to realtime updates"));
break;
case ERealtimeConnectionState::Error:
UE_LOG(LogTemp, Error, TEXT("Connection error occurred"));
break;
}
}
The WebSocket implementation uses several thread safety mechanisms:
std::atomic for thread-safe accessFCriticalSectionTWeakObjectPtr to prevent dangling pointersThe automatic reconnection system implements:
WebSocket connections use the following URL pattern:
wss://your-project.supabase.co/realtime/v1/websocket?apikey=your-anon-key&vsn=1.0.0
The plugin automatically converts your Supabase HTTP URL to the appropriate WebSocket endpoint format.
Connection Timeout: When initial connection takes longer than configured timeout period.
Authentication Failure: Invalid API keys or insufficient permissions for realtime access.
Network Interruption: Temporary network issues causing connection drops.
Rate Limiting: Supabase imposing rate limits on connection attempts.
The system provides several recovery mechanisms:
Heartbeat Tuning: Adjust heartbeat intervals based on network reliability and application needs.
Event Filtering: Subscribe only to needed events to reduce bandwidth and processing overhead.
Connection Pooling: Reuse connections across multiple subscriptions when possible.
Cleanup Management: Always properly cleanup subscriptions to prevent resource leaks.
The plugin provides comprehensive logging for connection monitoring:
// Enable debug logging
USupabaseManager::EnableDebugLogging(true);
// Monitor connection states
RealtimeSubscription->OnConnectionStateChanged.AddDynamic(this, &AMyActor::LogConnectionState);
Always use appropriate API keys for WebSocket connections:
WebSocket subscriptions respect Supabase Row Level Security policies:
-- Example RLS policy for user-specific data
CREATE POLICY "Users can only see their own data" ON user_profiles
FOR SELECT USING (auth.uid() = user_id);
Connection Fails: Verify Supabase URL format and API key validity.
No Events Received: Check database table permissions and RLS policies.
Frequent Disconnections: Adjust heartbeat intervals and connection timeout settings.
Memory Leaks: Ensure proper cleanup of subscription objects.
For complete implementation examples and integration patterns, see:
The WebSocket connections system provides a robust foundation for real-time applications in Unreal Engine 5, with production-ready reliability and comprehensive error handling.