#### Integration Sample (integration-sample.html) This example demonstrates using the `PriaIntegration` class from `pria-sdk-web.js` for a streamlined integration: ```javascript theme={null} // Load SDK with PriaIntegration helper class PriaIntegration.loadSdk(baseUrl, displayOptions, instanceConfig, userConfig); // Wait for SDK to be ready const timer = setInterval(() => { if (window.pria && window.pria.isReady && window.pria.isReady()) { clearInterval(timer); // SDK is ready - user can interact with the button } }, 100); // Clean termination PriaIntegration.destroySdk(); ``` **Best for:** Quick integrations where you want the Digital Twin button to appear and let users click to start conversations naturally.

#### SDK Sample (sdk-sample.html) This example loads the remote `pria-sdk.js` directly, giving you full control over events and conversation flow: ```javascript theme={null} // Load SDK script directly const script = document.createElement('script'); script.src = `${BASE_URL}/pria-sdk.js`; script.onload = () => { window.priasdk(BASE_URL, userConfig, PUBLIC_ID, pictureUrl, displayOptions); waitForReady(setupPria); }; // Subscribe to events for granular control window.pria.subscribe((response) => { const command = response?.response?.command; if (response.type === 'pria-response' && command === 'convo.start') { // Conversation started - show the UI window.pria.setVisible(true); } }); // Programmatically start conversation window.pria.send({ command: 'convo.start' }); ``` **Best for:** Advanced integrations requiring: * Custom loading indicators while connecting * Automatic conversation start on button click * Error handling with retry logic * Visibility control based on connection state The SDK Sample hides the Digital Twin UI until the conversation is confirmed started, providing a smoother user experience with loading feedback. ### Standard Integration For full control, use JavaScript to configure and load the SDK. Configuration object example: ```javascript theme={null} // Configuration let config = { displayOptions: { buttonPositionRight: 'calc(50% - 40px)', buttonPositionBottom: '80px' }, instanceConfig: { publicId: 'f831501f-b645-481a-9cbb-331509aaf8c1', pictureUrl: 'https://cdn.domain.com/pics/dt_1.png' }, userConfig: { email: 'john@doe.com', profilename: 'John Doe', usertype: 1, userid: 110, roleid: 123, rolename: "Course ABC", partnerid: 1, partnername: "ABC Global Inc." }, ... other useful configuration objects }; ``` This object configures display, digital twin instance, and user identity. Load the SDK: ```javascript theme={null} /** * Load the Pria SDK */ loadPriaSDK() { return new Promise((resolve, reject) => { const script = document.createElement('script'); script.src = 'pria-sdk-web.js'; script.async = true; script.onload = () => { PriaIntegration.loadSdk( 'https://pria.praxislxp.com', config.displayOptions, config.instanceConfig, config.userConfig ); resolve(); }; script.onerror = (error) => { reject(new Error('Web SDK loading failed')); }; document.body.appendChild(script); }); } // usage await loadPriaSDK(); ``` The SDK file should be the copy you installed. You can organize includes under `/assets/js/` as needed. For a full example, see [SDK Playground Example](/mdx/sdk/javascript#sdk-playground). ## Configuration Parameters The SDK requires three objects: `displayOptions`, `instanceConfig`, and `userConfig`. ### Display Options The `displayOptions` object controls the display and behavior of your digital twin on screen. ```javascript theme={null} let displayOptions = { fullScreen: false, // Expand in full screen mode openOnLoad: false, // Open Pria immediately when loaded buttonWidth: '80px', // Size of the Pria logo button buttonPosition: 'fixed', // Button position type (fixed, relative, sticky) buttonPositionRight: '20px', // Distance from right edge buttonPositionBottom: '20px', // Distance from bottom edge buttonNoBounce: true, // Disable button bounce animation priaContainerId: '', // Container ID for Pria window (default: BODY) buttonContainerId: '', // Container ID for button (default: BODY) allowPop: false, // Allow popping out of containing iframe noUI: false, // Disable UI for headless operation convoMode: false // Auto-start convo (voice) mode when ready } ``` Set `noUI: true` to use Pria programmatically without the visual interface Adjust `buttonPositionRight` with CSS for positioning, e.g., `calc(50% - 40px)` for center alignment. ### Convo Mode (`convoMode`) The `convoMode` display option lets you auto-start real-time voice (speech-to-speech) mode as soon as the Digital Twin determines that voice is available for the current user. This is useful when you want your application to launch directly into a voice experience without requiring the user to navigate through the text interface first. **How it works:** After the user authenticates, the SDK receives a `convo.ready` event from the Digital Twin indicating whether real-time voice is authorized. When `convoMode` is enabled, the SDK automatically sends a `convo.start` command and opens the UI panel. **Values:** | Value | Behavior | | --------------------------------------------------- | -------------------------------------------------------------------------------------------------- | | `false` (default) | No auto-start. Voice mode must be started manually. | | `true` | Auto-start voice mode with the default assistant in a new conversation. | | `{ conversationId, conversationName, assistantId }` | Auto-start voice mode targeting a specific conversation and/or assistant. All fields are optional. | **Simple auto-start:** ```javascript theme={null} let displayOptions = { convoMode: true, fullScreen: true, openOnLoad: true } ``` **Targeted auto-start with a specific assistant and conversation:** ```javascript theme={null} let displayOptions = { convoMode: { conversationId: 123, // maps to course_id conversationName: 'Customer Onboarding', // maps to course_name assistantId: '6bec24be-4e86-4071-b90f-d588' // target assistant _id }, fullScreen: true, openOnLoad: true } ``` `convoMode` requires that real-time voice (convo) is enabled for the user's institution. If voice is not authorized, the flag is silently ignored and the text interface loads normally. ### Instance Configuration The `instanceConfig` object configure which Digital Twin to use along with the picture rendered in the start button. ```javascript theme={null} let instanceConfig = { publicId: '41407647-248c-4f0e-a317-71fc151ba8fb', // Public ID identifying your Digital Twin pictureUrl: 'https://cdn.domain.com/pics/dt_1.png', // Picture to use for the on-screen icon of your Digital Twin }; ``` The publicId identifies your digital twin instance Load these values securely and asynchronously—never expose sensitive data in your HTML. ### User identity Set the user identity in the `userConfig` object ```javascript theme={null} let userConfig = { email: 'john@doe.com', // Required profilename: 'John Doe', profilepicture: '', // Leave empty for user's default picture userid: '123', // Optional user identifier on your site roleid: 123, // Optional conversation/course ID rolename: 'Course ABC', // Optional conversation/course name partnerid: 1, // Optional customer/account ID partnername: 'ABC Global Inc.' // Optional customer/account name }; ``` The `email` is required and serves as the main identifier in Praxis AI Middleware. For education, set `roleid` and `rolename` to specify the course. Use `partnerid` and `partnername` to identify an Account or Customer when you create a multi tenant solution For enhanced security, always retrieve these values asynchronously from a secure source to prevent exposure of plaintext data in the page. ### Wait for Pria and Start Convo mode Here is an example demonstrating how to Wait for Pria to be fully ready, then start Convo mode ```javascript theme={null} /** * Start a conversation with optional assistant and course selection */ const startConversation = async (assistantId, conversationId, conversationName) => { let request = { command: 'convo.start' }; // Optionally specify an assistant if (assistantId) { request.assistantId = assistantId; } // Optionally specify an existing conversation if (conversationId && conversationName) { request.selectedCourse = { course_id: conversationId, course_name: conversationName }; } console.log("Starting convo mode"); window.pria.send(request); } /** * Handle responses from Pria */ const handleResponse = async (data) => { console.log("Got response from Pria", data); const command = data?.response?.command; const content = data?.response?.content; if (data.type === 'pria-response') { console.log("Processing command:", command); // Handle convo.start success - show UI if (command === 'convo.start') { // Use SDK's display function to show the UI panel window.pria.display(true); } else if (command === 'assistants.list' && content) { // Handle assistants list response console.log("Assistants loaded:", content); } else if (command === 'conversations.list' && content) { // Handle conversations list response console.log("Conversations loaded:", content); } } else if (data.type === 'pria-error') { const errorContent = data?.response?.content; if (errorContent && errorContent.indexOf("not connected") > -1) { // Retry after delay if not connected setTimeout(() => startConversation(), 2000); } else { console.error("Pria error:", errorContent); } } } /** * Wait for Pria to be fully loaded and ready */ const waitForPria = () => { // Use isReady to check if Pria is fully initialized if (!window?.pria?.isReady()) { console.log("Waiting for Pria to load..."); return; } console.log('Pria loaded and ready'); clearInterval(waitForPriaTimer); // Subscribe to Pria responses window.pria.subscribe(handleResponse); // Start conversation after a brief delay setTimeout(() => startConversation(), 2000); // Clean up on page unload window.addEventListener('beforeunload', () => { window.pria.unsubscribe(handleResponse); window.pria.destroy(); // Clean up Pria resources }); } let waitForPriaTimer = setInterval(waitForPria, 1000); ``` Use `window.pria.isReady()` to check if Pria is fully initialized before sending commands. ## Integration Class Sample This example is provided AS IS to demonstrate how you can cleanly integrate a Digital Twin in your Web Application. It is extracted from the playground example code. ```javascript theme={null} /** * Javascript Class integration example * Demonstrates modern patterns for Pria SDK integration */ class PriaTestHarness { constructor() { this.pria = null; this.waitForPriaTimer = null; this.isConnected = false; this.conversationMode = 'existing'; // 'existing' or 'new' this.assistantsCache = []; // Cache assistants for lookup // Configuration this.config = { displayOptions: { buttonPositionRight: 'calc(50% - 40px)', buttonPositionBottom: '80px' }, instanceConfig: { publicId: 'f831501f-b645-481a-9cbb-331509aaf8c1', pictureUrl: 'https://cdn.domain.com/pics/dt_1.png' }, userConfig: { email: 'john@doe.com', profilename: 'John Doe', usertype: 1, userid: 110, roleid: 123, rolename: "Course ABC", partnerid: 1, partnername: "ABC Global Inc." }, localhost: true }; this.init(); } /** * Initialize the application */ async init() { try { await this.loadPriaSDK(); } catch (error) { console.error('Failed to initialize application:', error); } } /** * Load the Pria SDK */ loadPriaSDK() { return new Promise((resolve, reject) => { const script = document.createElement('script'); script.src = 'pria-sdk-web.js'; script.async = true; script.onload = () => { console.log('Web SDK Script loaded'); const url = 'https://pria.praxislxp.com'; PriaIntegration.loadSdk( url, this.config.displayOptions, this.config.instanceConfig, this.config.userConfig ); this.waitForPriaTimer = setInterval(() => this.waitForPria(), 1000); resolve(); }; script.onerror = (error) => { console.error('Failed to load Web SDK:', error); reject(new Error('Web SDK loading failed')); }; document.body.appendChild(script); }); } /** * Wait for Pria to be available and set up subscriptions */ waitForPria() { // Use isReady() to check if Pria is fully initialized if (!window.pria?.isReady()) { console.log("Waiting for Pria to load..."); return; } clearInterval(this.waitForPriaTimer); this.pria = window.pria; this.isConnected = true; // Subscribe to Pria responses this.pria.subscribe(this.handlePriaResponse.bind(this)); // Load assistants and conversations on connection this.loadAssistants(); this.loadConversations(); // Clean up on page unload window.addEventListener('beforeunload', () => { this.pria.unsubscribe(this.handlePriaResponse); this.pria.destroy(); // Clean up Pria resources }); } /** * Handle responses from Pria */ handlePriaResponse(response) { const command = response?.response?.command; const content = response?.response?.content; if (response.type === 'pria-response') { console.log("Processing command:", command); // Handle convo.start success - show UI if (command === 'convo.start') { this.showPria(); } else if (command === 'assistants.list' && content) { this.assistantsCache = content; console.log("Assistants loaded:", content.length); } else if (command === 'conversations.list' && content) { console.log("Conversations loaded:", content.length); } } else if (response.type === 'pria-error') { console.error("Pria error:", content); } } /** * Start a conversation */ startConversation(assistantId, conversationId, conversationName) { if (!this.isConnected) return; let request = { command: 'convo.start' }; if (assistantId) { request.assistantId = assistantId; } if (conversationId && conversationName) { request.selectedCourse = { course_id: conversationId, course_name: conversationName }; } this.pria.send(request); } /** * Load assistants list */ loadAssistants() { if (!this.isConnected) return; this.pria.send({ command: 'assistants.list' }); } /** * Load conversations list */ loadConversations() { if (!this.isConnected) return; this.pria.send({ command: 'conversations.list' }); } /** * Toggle Pria visibility (show/hide entirely) */ togglePriaVisibility(visible) { if (!this.isConnected) return; this.pria.setVisible(visible); } /** * Toggle Pria panel display (expand/collapse) */ togglePriaDisplay() { if (!this.isConnected) return; // Use SDK's isDisplayed() to check current state const isCurrentlyDisplayed = this.pria.isDisplayed(); this.pria.display(!isCurrentlyDisplayed); } /** * Show Pria interface */ showPria() { if (!this.pria) return; // Check if UI is already shown using SDK's isDisplayed() if (!this.pria.isDisplayed()) { this.pria.display(true); } } } // Initialize the application when DOM is loaded document.addEventListener('DOMContentLoaded', () => { new PriaTestHarness(); }); ``` ### Key SDK Methods Used | Method | Description | | ---------------------------- | ---------------------------------------------------------------- | | `pria.isReady()` | Check if Pria is fully initialized and ready to receive commands | | `pria.subscribe(callback)` | Listen for responses from Pria | | `pria.unsubscribe(callback)` | Remove a response listener | | `pria.send(request)` | Send a command to Pria | | `pria.setVisible(visible)` | Show or hide Pria entirely (removes from DOM view) | | `pria.isVisible()` | Check if Pria is currently visible | | `pria.display(show)` | Expand or collapse the Pria UI panel | | `pria.isDisplayed()` | Check if the UI panel is currently expanded | | `pria.destroy()` | Clean up and remove Pria from the page | ### Checking Ready State Always verify Pria is ready before sending commands: ```javascript theme={null} /** * Check if Pria SDK is ready to receive messages * @returns {boolean} True if SDK is fully connected and ready */ function isPriaReady() { return window.pria && typeof window.pria.isReady === 'function' && window.pria.isReady(); } // Usage in your application if (isPriaReady()) { window.pria.send({ command: 'convo.start' }); } ``` The `isReady()` method returns `true` only when the SDK is fully connected to the middleware and ready to send/receive messages. ### Cleanup and Reload When you need to remove Pria or reload it with new configuration: ```javascript theme={null} // Destroy SDK completely (removes all UI, event listeners, and references) PriaIntegration.destroySdk(); // Reload with new or existing configuration PriaIntegration.reloadSdk( 'https://pria.praxislxp.com', displayOptions, instanceConfig, userConfig ); ``` After calling `destroy()` or `destroySdk()`, all existing references to `pria` become invalid. The SDK must be fully reloaded before use. ## SDK Playground Example See a live demo: at [SDK Playground Example](https://pria.praxislxp.com/pria-sdk-web-sample.html). ``` https://pria.praxislxp.com/pria-sdk-web-sample.html ```

This demo covers integration, connection detection, command execution, and more. ## Automation Refer to the [Javascript APIs](/mdx/sdk/javascript) for interacting with your Digital Twin programmatically using Javascript