Widget Integration Guide

Pernoex offers three integration modes: Floating for a chat bubble experience,Embedded for custom layouts where you want the chat always visible, and Inline Explainer for contextual "Ask AI" functionality on text selection that opens an AI sidebar with full conversational support.

Floating Mode

The default integration. A chat bubble appears in the corner of your page that users can click to open and close.

Basic Setup

Add this before the closing </body> tag:

<script src="https://cdn.pernoex.com/widget.js" 
        data-api-key="YOUR_API_KEY"></script>

Custom API URL

For self-hosted instances:

<script src="https://cdn.pernoex.com/widget.js" 
        data-api-key="YOUR_API_KEY"
        data-api-url="https://your-api.example.com/api/v1"></script>

Live Preview

Click the chat bubble to preview

Embedded Mode

Render the chat inside a specific container. Perfect for dedicated support pages, sidebars, or custom layouts.

Setup

<div id="chat-container" style="height: 600px;"></div>

<script src="https://cdn.pernoex.com/widget.js" 
        data-manual-init="true"></script>

<script>
  Pernoex.init({
    apiKey: 'YOUR_API_KEY',
    mode: 'embedded',
    container: '#chat-container',
    showHeader: true,
    borderRadius: '12px'
  });
</script>

Live Preview

AI Assistant

Hi! How can I help you today?

How do I get started?

Great question! You can start by creating a project in your dashboard...

Embedded mode - always visible

Configuration Options

Option	Type	Default	Description
`apiKey`	string	required	Your project's public API key
`mode`	'floating' \| 'embedded'	'floating'	Widget display mode
`container`	string \| HTMLElement	none	CSS selector or element (required for embedded)
`apiUrl`	string	cdn default	Custom API endpoint URL
`showHeader`	boolean	true	Show or hide header in embedded mode
`showBranding`	boolean	from config	Override branding visibility
`borderRadius`	string	'0'	CSS border radius for container

Inline Explainer Mode

Add contextual AI explanations to any text on your page. Users can highlight text and click "Ask AI" to get explanations grounded in your knowledge base in a sidebar that pushes page content, keeping the reading context visible.

Dashboard Controlled Enable or disable the inline explainer from your project's Settings page in the dashboard. When enabled, users can select text and get AI explanations powered by your indexed documentation. The sidebar also supports follow up conversations for deeper understanding.

Basic Setup

<!-- Inline explainer is controlled from your dashboard settings -->
<!-- Once enabled, it works automatically with text selection -->

<script src="https://cdn.pernoex.com/widget.js" 
        data-api-key="YOUR_API_KEY"></script>

How It Works

Our RAG pipeline ensures accurate responses grounded in your documentation.

Click "RAG pipeline" above to preview

Advanced Configuration

// For programmatic control, you can override dashboard settings
Pernoex.init({
  apiKey: 'YOUR_API_KEY',
  inline: {
    enabled: true,                              // Override dashboard setting
    triggerSelector: 'article, .docs-content',  // Only in these areas
    excludeSelector: 'nav, .code-block',        // Not in these areas
    position: 'auto',                           // 'auto' | 'above' | 'below'
    showFollowUp: true,                         // Allow follow-up questions
    theme: 'auto'                               // Match system theme
  }
});

Configuration Options

Option	Type	Default	Description
`enabled`	boolean	false	Enable inline explainer (controlled from dashboard settings by default)
`triggerSelector`	string	none	CSS selector to limit where text selection triggers the explainer
`excludeSelector`	string	none	CSS selector for areas to exclude from text selection
`position`	'auto' \| 'above' \| 'below'	'auto'	Preferred tooltip position relative to selection
`maxWidth`	number	400	Maximum width of the explainer sidebar in pixels
`showFollowUp`	boolean	false	Show input field for follow up questions
`theme`	'light' \| 'dark' \| 'auto'	'auto'	Color theme for the sidebar

Combined with Floating Widget

The inline explainer works alongside your main chat widget automatically. When enabled from the dashboard, both the floating chat and text selection explainer are available to your users:

// Inline explainer works alongside the floating widget automatically
// Just enable it in your dashboard settings, or override via init:

Pernoex.init({
  apiKey: 'YOUR_API_KEY',
  inline: {
    enabled: true  // Works alongside the floating chat widget
  }
});

Common Use Cases

Full-Page Chat

Create a dedicated support or chat page:

<!DOCTYPE html>
<html>
<head>
  <style>
    body, html { margin: 0; height: 100%; }
    #chat-container { height: 100vh; width: 100%; }
  </style>
</head>
<body>
  <div id="chat-container"></div>
  
  <script src="https://cdn.pernoex.com/widget.js" 
          data-manual-init="true"></script>
  <script>
    Pernoex.init({
      apiKey: 'YOUR_API_KEY',
      mode: 'embedded',
      container: '#chat-container'
    });
  </script>
</body>
</html>

AI Assistant

Hi! How can I help you today?

How do I get started?

Great question! You can start by creating a project in your dashboard...

Embedded mode - always visible

Sidebar Integration

Add a persistent chat sidebar to your application:

<div style="display: flex; height: 100vh;">
  <main style="flex: 1;">
    <!-- Your main content -->
  </main>
  
  <aside id="chat-sidebar" 
         style="width: 400px; border-left: 1px solid #e5e7eb;">
  </aside>
</div>

<script src="https://cdn.pernoex.com/widget.js" 
        data-manual-init="true"></script>
<script>
  Pernoex.init({
    apiKey: 'YOUR_API_KEY',
    mode: 'embedded',
    container: '#chat-sidebar',
    showHeader: true
  });
</script>

Help

Need help with anything?

Sidebar integration layout

JavaScript API Reference

Control Methods

Available for floating mode:

// Open the chat window
Pernoex.open()

// Close the chat window
Pernoex.close()

// Toggle open/closed state
Pernoex.toggle()

// Check if widget is currently open
const isOpen = Pernoex.isOpen()

// Clear all messages and start a new conversation
Pernoex.clearMessages()

// Get explanation for text programmatically
const explanation = await Pernoex.explain("text to explain")

// Destroy the widget and clean up
Pernoex.destroy()

Event Callbacks

Listen to widget lifecycle events:

Pernoex.init({
  apiKey: 'YOUR_API_KEY',
  onReady: () => {
    console.log('Widget is ready');
  },
  onOpen: () => {
    console.log('Widget opened');
  },
  onClose: () => {
    console.log('Widget closed');
  },
  onError: (error) => {
    console.error('Widget error:', error);
  }
});

Framework Examples

import { useEffect, useRef } from 'react';

function ChatWidget() {
  const containerRef = useRef(null);

  useEffect(() => {
    const script = document.createElement('script');
    script.src = 'https://cdn.pernoex.com/widget.js';
    script.setAttribute('data-manual-init', 'true');
    document.body.appendChild(script);

    script.onload = () => {
      window.Pernoex.init({
        apiKey: 'YOUR_API_KEY',
        mode: 'embedded',
        container: containerRef.current,
        showHeader: true
      });
    };

    return () => {
      window.Pernoex?.destroy();
      document.body.removeChild(script);
    };
  }, []);

  return <div ref={containerRef} style={{ height: '600px' }} />;
}

Security & Best Practices

Important: Only use your public API key in client-side code. Never expose private/secret keys in HTML or JavaScript.

Domain Restrictions

Configure allowed domains in your project settings to prevent unauthorized use. The widget will only load on whitelisted domains.

Content Security Policy

If you use CSP headers, allow the following:

script-src 'self' https://cdn.pernoex.com;
connect-src 'self' https://api.pernoex.com;
style-src 'self' 'unsafe-inline';

Troubleshooting

Widget Not Appearing

Verify your API key is correct
Check that your domain is whitelisted in project settings
Open browser console for errors
Ensure the script tag is loaded (check the Network tab)

Embedded Mode Container Empty

Confirm container element exists before calling Pernoex.init()
Set an explicit height on the container element
Check console for initialization errors
Verify data-manual-init="true" is set on the script tag

Styling Issues

Widget styles are isolated to prevent conflicts
Ensure the container has defined dimensions
Check for z index conflicts with page elements

Inline Explainer Not Appearing

Verify inline explainer is enabled in your project's Settings page on the dashboard
Check triggerSelector matches elements on your page
Ensure selection is at least 3 characters
Check console for JavaScript errors
Verify the selected area is not excluded by excludeSelector

Explanations Are Generic

Ensure your knowledge base is indexed (check Crawl status in dashboard)
The selected text should relate to content in your indexed pages
Try selecting more specific terms from your documentation
Check that your project has sufficient token balance

Sidebar Not Pushing Content

The sidebar pushes page content to the left when it opens
Ensure your page layout can accommodate the sidebar width
Check for fixed positioning elements that may not respond to the push

Need Help?

Have questions about integration? Reach out to our support team at [email protected] or explore more examples in your dashboard.