SetOnReconnecting

Subscribe to be notified when reconnection state changes. This callback is triggered automatically by sym3.js when it detects connection loss (e.g., when the browser tab is hidden and the connection drops) and when reconnection completes.

When you register this callback, sym3.js automatically handles:

  1. Tab visibility detection - Monitors when browser tab is hidden/visible
  2. View state saving - Calls SaveViewState() when tab is hidden
  3. Connection monitoring - Checks if connection was lost while tab was hidden
  4. Auto-reconnection - Attempts to reconnect if connection was lost
  5. View state restoration - Calls RestoreViewState() after successful reconnection

You don’t need to implement any of this logic - just show/hide your UI!

Notes:

  • This callback must be set after CreateSym3() but can be set anytime before the user starts hiding/showing tabs
  • The callback can be called multiple times during a session if connection is lost and restored repeatedly
  • View state includes: camera position, rotation, zoom, background color, highlight mode, and outline mode
  • If no callback is registered, reconnection still happens automatically, but no UI feedback is shown
  • The callback is optional - if your app doesn’t need reconnection UI, you don’t need to set it

When the callback is triggered:

Event isReconnecting What sym3.js does automatically Client app should do
Tab hidden - Saves view state Nothing
Tab visible + disconnected true Attempts reconnection Show reconnection overlay
Reconnection succeeds false Restores view state Hide reconnection overlay
Tab visible + still connected - Restores view state Nothing

See the Demo Example

Function

SYM3.SetOnReconnecting(callbackFunction)

Parameters

callbackFunction (Function)

A callback function that will be invoked when reconnection state changes.

Callback Parameters

Parameter Type Description
isReconnecting Boolean true when reconnection starts (show UI), false when reconnection completes (hide UI)

Return Value

None (void)

Example: Basic Usage

// Simple reconnection UI handler
SYM3.SetOnReconnecting(function(isReconnecting) {
    if (isReconnecting) {
        // Show "Reconnecting..." overlay
        document.getElementById('reconnection-overlay').style.display = 'flex';
        console.log("Reconnecting to server...");
    } else {
        // Hide overlay
        document.getElementById('reconnection-overlay').style.display = 'none';
        console.log("Reconnected successfully!");
    }
});

Example: With Custom UI Elements

var reconnectionOverlay = null;

function showReconnectionOverlay() {
    if (!reconnectionOverlay) {
        reconnectionOverlay = document.getElementById('reconnection-overlay');
    }
    if (reconnectionOverlay) {
        reconnectionOverlay.classList.add('active');
    }
}

function hideReconnectionOverlay() {
    if (reconnectionOverlay) {
        reconnectionOverlay.classList.remove('active');
    }
}

// Register the callback
SYM3.SetOnReconnecting(function(isReconnecting) {
    if (isReconnecting) {
        showReconnectionOverlay();
    } else {
        hideReconnectionOverlay();
    }
});

Complete Working Example

//-- Create sym3 instance
SYM3 = CreateSym3(27000, "localhost", true);

//-- Set up reconnection UI handler (only UI code needed!)
SYM3.SetOnReconnecting(function(isReconnecting) {
    var overlay = document.getElementById('reconnection-overlay');
    if (isReconnecting) {
        overlay.style.display = 'flex';
    } else {
        overlay.style.display = 'none';
    }
});

//-- Subscribe to project initialization
SYM3.SetOnProjectInitialised(function(projectName, projectGuid, protocolVersion, stateVersion, cameraNames) {
    console.log("Project initialized:", projectName);
    // Everything else is handled automatically by sym3.js!
});