SessionIQ React Widget (@sessioniq/widget-react)

Overview

This package provides a pre-built React component (AgentWidget) that acts as a user interface for interacting with the @sessioniq/client-sdk. It allows users to:

• Select an active analysis agent.
• Start and stop session recording.
• Trigger session analysis.
• View analysis status updates and results (including AI insights and suggestions) in a chat interface.
• Interact with the AI agent via chat messages after analysis is complete.

The widget handles communication with the SDK, including subscribing to real-time updates and sending commands like startRecording, stopRecording, analyzeSession, and sendChatMessage.

Installation

# Using npm (or pnpm or yarn)
npm install @sessioniq/widget-react @sessioniq/client-sdk

Note: @sessioniq/client-sdk is a required peer dependency.

Usage

import React, { useState, useEffect, useRef } from "react";
import { SessionIQSdk } from "@sessioniq/client-sdk";
import { AgentWidget } from "@sessioniq/widget-react";
// Import the CSS if your bundler supports it
import "@sessioniq/widget-react/widget-react.css";

function App() {
  const [isInitialized, setIsInitialized] = useState(false);
  // Use a ref to hold the SDK instance to avoid re-creating it on re-renders
  const sdkRef = useRef<InstanceType<typeof SessionIQSdk> | null>(null);

  useEffect(() => {
    // Initialize SDK only once
    if (!sdkRef.current) {
      console.log("Initializing SessionIQ SDK...");
      const sdkInstance = new SessionIQSdk();
      sdkRef.current = sdkInstance;

      sdkInstance.init({
        clientId: "YOUR_CLIENT_ID", // Replace with your actual Client ID
        logLevel: "debug", // Optional: Set desired log level
      })
      .then(() => {
        console.log("SessionIQ SDK Initialized!");
        setIsInitialized(true);
      })
      .catch((error) => {
        console.error("Failed to initialize SessionIQ SDK:", error);
        // Handle initialization error (e.g., show error message)
      });
    }

    // Cleanup function to destroy SDK instance on component unmount
    return () => {
      if (sdkRef.current) {
        console.log("Destroying SessionIQ SDK instance.");
        sdkRef.current.destroy();
        sdkRef.current = null;
        setIsInitialized(false);
      }
    };
  }, []); // Empty dependency array ensures this runs only once on mount

  return (
    <div>
      {/* Other application content */}

      {/* Render AgentWidget only after SDK is initialized */}
      {isInitialized && sdkRef.current && (
        <AgentWidget sdk={sdkRef.current} position="bottom-right" />
      )}

      {/* Example of using the useWidget hook (optional) */}
      {/* <WidgetController /> */}
    </div>
  );
}

/*
// Example of a separate component to control the widget
import { useWidget } from "@sessioniq/widget-react";

function WidgetController() {
  const { isWidgetOpen, openWidget, closeWidget } = useWidget();

  return (
    <div style={{ position: 'fixed', top: '10px', left: '10px' }}>
      <button onClick={openWidget}>Open Widget</button>
      <button onClick={closeWidget}>Close Widget</button>
      <p>Widget is: {isWidgetOpen ? 'Open' : 'Closed'}</p>
    </div>
  );
}
*/

export default App;

Exports

This package exports:

• AgentWidget: The main React component.
• useWidget: A custom React hook to control the widget's visibility programmatically.

Component Props (AgentWidget)

• sdk (Required): An initialized instance of SessionIQSdk from @sessioniq/client-sdk.
• position (Optional, default: 'bottom-right'): Controls the floating position of the widget button. Options: 'bottom-right', 'top-right', 'bottom-left', 'top-left', 'hidden'.

Custom Hook (useWidget)

Provides functions and state to control the widget UI:

import { useWidget } from "@sessioniq/widget-react";

function MyComponent() {
  const { isWidgetOpen, toggleWidget, openWidget, closeWidget } = useWidget();

  // Example usage:
  return (
    <div>
      <button onClick={openWidget}>Open Support Widget</button>
      <p>Widget is currently {isWidgetOpen ? 'open' : 'closed'}.</p>
    </div>
  );
}

• isWidgetOpen: A boolean state indicating if the widget panel is open.
• toggleWidget(): Function to toggle the widget panel's visibility.
• openWidget(): Function to open the widget panel.
• closeWidget(): Function to close the widget panel.

License

MIT License - Copyright (c) 2025 SessionIQ