Skip to main content

​
Overview

Loading a Digital Twin follows a strict sequence: inject the SDK script, initialize with credentials, poll for readiness, subscribe to events, then start the conversation. Skipping or reordering these steps causes silent failures. This guide walks through each phase using the sdk-sample.js reference implementation. 
DOM Ready
  └─ init()
       └─ Inject <script src="pria-sdk.js">
            └─ onload → priasdk(url, user, publicId, '', display)
                 └─ waitForReady() [poll 100ms]
                      └─ isReady() === true
                           └─ setupPria()
                                ├─ subscribe(handleResponse)
                                └─ button.click →
                                     ├─ setVisible(false)
                                     ├─ showLoading()
                                     ├─ setTimeout(5s fallback)
                                     └─ send({ command: 'convo.start' })
                                          │
                                    ┌─────┴──────┐
                                    ▼              ▼
                              pria-response    pria-error
                              ├─ hideLoading   ├─ reset timer
                              └─ setVisible    └─ retry convo.start
                                   (true)          (loops until success
                                                    or timeout)

​
Phase 1: Script Injection

Wait for the DOM, then dynamically load the SDK script from your Pria server. 
function init() {
    // Guard against double-initialization
    if (typeof window.priasdk === 'function') return;

    const script = document.createElement('script');
    script.src = 'https://pria.praxislxp.com/pria-sdk.js';
    script.async = true;

    script.onload = () => {
        // Phase 2 starts here
    };

    document.body.appendChild(script);
}

// Trigger on DOM ready
if (document.readyState === 'loading') {
    document.addEventListener('DOMContentLoaded', init);
} else {
    init();
}
You can inject optional CSS before loading the script to constrain the Pria UI dimensions:
const style = document.createElement('style');
style.textContent = '#pria_ui { max-width: 380px!important; max-height: 480px!important; }';
document.head.appendChild(style);

​
Phase 2: SDK Initialization

Inside the script.onload callback, call window.priasdk() with five arguments. This creates the iframe, establishes the Socket.io connection, and performs the REGISTER handshake. 
script.onload = () => {
    // 1. User identity (persistent via cookies)
    const userConfig = {
        email: 'user123@example.com',
        profilename: 'User 123',
        lticontextid: document.URL
    };

    // 2. Display options
    const displayOptions = {
        buttonWidth: '320px',
        buttonPosition: 'initial',
        buttonContainerId: 'my-button-container',
        openOnLoad: false   // Keep hidden until conversation starts
    };

    // 3. Initialize — PUBLIC_ID is your Digital Twin's public instance ID
    window.priasdk(
        'https://pria.praxislxp.com',  // Base URL
        userConfig,                      // User identity
        PUBLIC_ID,                       // Digital Twin public ID
        '',                              // Reserved (pass empty string)
        displayOptions                   // Display configuration
    );

    // 4. Begin polling for readiness
    waitForReady(setupPria);
};
openOnLoad: false is critical. Without it, the user sees a blank chat panel while the backend is still connecting. The UI should only appear after convo.start succeeds.

​
Persistent User Identity

The reference implementation uses cookies to maintain a stable user identity across visits, which preserves conversation history: 
function getUserIdentity() {
    const now = Math.floor(Date.now() / 1000);
    let userId = getCookie('pria-web-user');
    if (!userId) {
        setCookie('pria-web-user', now, 365);
        userId = now;
    }
    return {
        email: `${userId}@your-domain.com`,
        profilename: `${userId} WebUser`,
        lticontextid: document.URL
    };
}

​
Phase 3: Poll for Readiness

The SDK needs time to load the iframe, connect via Socket.io, and complete the REGISTER handshake. Poll isReady() until it returns true. 
function waitForReady(callback) {
    const timer = setInterval(() => {
        if (window.pria && window.pria.isReady && window.pria.isReady()) {
            clearInterval(timer);
            callback();
        }
    }, 100);  // Check every 100ms
}
isReady() returns true only after the Socket.io connection is established and the Digital Twin configuration is loaded. Never send commands before this returns true.

​
Phase 4: Subscribe and Setup

Once the SDK is ready, subscribe to response events and wire up your UI trigger. 
function setupPria() {
    // 1. Subscribe to all Pria responses
    window.pria.subscribe(handlePriaResponse);

    // 2. Clean up on page unload
    window.addEventListener('beforeunload', () => {
        if (window.pria && typeof window.pria.destroy === 'function') {
            window.pria.destroy();
        }
    });

    // 3. Wire the launch button
    const button = document.getElementById('my-launch-button');
    if (button) {
        button.addEventListener('click', () => {
            window.pria.setVisible(false);    // Hide UI during connection
            showLoading();                     // Show spinner overlay
            startResponseTimer();              // Safety timeout
            window.pria.send({ command: 'convo.start' });
        });
    }
}
The button click triggers four actions in sequence:
  1. Hide the Pria UI — prevents showing an empty chat window
  2. Show a loading overlay — gives the user visual feedback
  3. Send convo.start — tells the backend to initialize the AI session

​
Phase 5: Response Handling with Retry

The response handler manages two scenarios: successful start and transient connection errors. 
const RESPONSE_TIMEOUT = 5000; // 5 seconds
let responseTimer = null;

function startResponseTimer() {
    clearResponseTimer();
    responseTimer = setTimeout(() => {
        hideLoading();
        window.pria.setVisible(true);  // Show UI as fallback
    }, RESPONSE_TIMEOUT);
}

function clearResponseTimer() {
    if (responseTimer) {
        clearTimeout(responseTimer);
        responseTimer = null;
    }
}

function handlePriaResponse(response) {
    const command = response?.response?.command;
    const type = response?.type;
    const content = response?.response?.content;
    const isError = response?.response?.isError;

    // SUCCESS — conversation started
    if (type === 'pria-response' && command === 'convo.start') {
        clearResponseTimer();
        hideLoading();
        window.pria.setVisible(true);
        return;
    }

    // TRANSIENT ERROR — backend not ready yet, retry
    if (type === 'pria-error' && command === 'convo.start' && isError) {
        if (content && (content.includes('NO-SESSION') || content.includes('not connected'))) {
            // Reset the timeout to give more time
            startResponseTimer();
            // Retry immediately
            window.pria.send({ command: 'convo.start' });
            return;
        }
    }
}

​
How the Retry Loop Works

EventAction
convo.start sent5-second timeout starts
pria-response with convo.startTimer cleared, loading hidden, UI shown
pria-error with NO-SESSIONTimer reset (another 5s), convo.start retried
Timeout fires (no response)Loading hidden, UI shown as fallback
The NO-SESSION error means the Socket.io connection is established but the AI backend session hasn’t initialized yet. This is a normal race condition — retrying resolves it within 1-2 attempts.

​
Loading Overlay

Provide visual feedback while the Digital Twin connects. The reference implementation uses a full-screen overlay with a spinner: 
function createLoadingOverlay() {
    const overlay = document.createElement('div');
    overlay.id = 'pria-loading-overlay';
    overlay.innerHTML = `
        <div class="pria-loading-content">
            <div class="pria-loading-spinner"></div>
            <span>Connecting to your Digital Twin...</span>
        </div>
    `;
    overlay.style.cssText = `
        position: fixed; top: 0; left: 0; right: 0; bottom: 0;
        background: rgba(0, 0, 0, 0.5);
        display: flex; align-items: center; justify-content: center;
        z-index: 99999;
    `;
    return overlay;
}

.pria-loading-content {
    background: white;
    padding: 24px 32px;
    border-radius: 12px;
    display: flex;
    align-items: center;
    gap: 16px;
    font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
    box-shadow: 0 4px 20px rgba(0, 0, 0, 0.2);
}
.pria-loading-spinner {
    width: 24px; height: 24px;
    border: 3px solid #e0e0e0;
    border-top-color: #3B82F6;
    border-radius: 50%;
    animation: pria-spin 1s linear infinite;
}
@keyframes pria-spin { to { transform: rotate(360deg); } }

​
Complete Minimal Example

Putting it all together — a minimal working integration: 
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>Digital Twin</title>
</head>
<body>
    <button id="start-btn">Talk to Digital Twin</button>
    <div id="pria-btn-container"></div>

    <script>
    (function() {
        const BASE_URL = 'https://pria.praxislxp.com';
        const PUBLIC_ID = 'your-public-id-here';
        const TIMEOUT = 5000;
        let timer = null;

        function startTimer() {
            clearTimer();
            timer = setTimeout(() => {
                window.pria.setVisible(true);
            }, TIMEOUT);
        }
        function clearTimer() {
            if (timer) { clearTimeout(timer); timer = null; }
        }

        function handleResponse(res) {
            if (res.type === 'pria-response' && res.response?.command === 'convo.start') {
                clearTimer();
                window.pria.setVisible(true);
            }
            if (res.type === 'pria-error' && res.response?.command === 'convo.start') {
                if (res.response?.content?.includes('NO-SESSION') ||
                    res.response?.content?.includes('not connected')) {
                    startTimer();
                    window.pria.send({ command: 'convo.start' });
                }
            }
        }

        function setup() {
            window.pria.subscribe(handleResponse);
            document.getElementById('start-btn').addEventListener('click', () => {
                window.pria.setVisible(false);
                startTimer();
                window.pria.send({ command: 'convo.start' });
            });
        }

        function waitReady(cb) {
            const t = setInterval(() => {
                if (window.pria?.isReady?.()) { clearInterval(t); cb(); }
            }, 100);
        }

        // Boot
        const s = document.createElement('script');
        s.src = BASE_URL + '/pria-sdk.js';
        s.onload = () => {
            window.priasdk(BASE_URL, {
                email: 'guest@example.com',
                profilename: 'Guest'
            }, PUBLIC_ID, '', {
                buttonContainerId: 'pria-btn-container',
                openOnLoad: false
            });
            waitReady(setup);
        };
        document.body.appendChild(s);
    })();
    </script>
</body>
</html>

​
Common Pitfalls

Sending commands before isReady()If you call pria.send() before the SDK is ready, the command is silently dropped. Always gate on isReady().
Missing subscribe() before convo.startIf you send convo.start without subscribing first, you won’t receive the success response and your UI will never transition from the loading state.
Not handling page unloadCall pria.destroy() on beforeunload to cleanly disconnect the Socket.io session. Without this, the server may hold stale sessions.