@brainfish-ai/web-widget

Brainfish In-App Widget

This package provides a simple way to integrate a Brainfish in-app widget in your website or web application. It supports popup widgets with contextual help functionality.

Installation

npm install @brainfish-ai/web-widget

Directly in your HTML

<script type="module">
    import Brainfish from "https://cdn.jsdelivr.net/npm/@brainfish-ai/web-widget@latest/dist/web.js"
    Brainfish.Widgets.init({ widgetKey: "your-key" });
</script>

Popup Widget

The popup widget provides a floating button that opens a search interface in a modal overlay.

Basic Usage

<!-- The widget will automatically create a floating button -->
<script>
    Brainfish.Widgets.init({
        widgetKey: "your-widget-key",
        environment: "production" // or "staging", "local"
    });
</script>

Widget Control API

// Open the widget
Brainfish.Widgets.open();

// Open the widget with custom positioning
Brainfish.Widgets.open({
    position: 'bottom-right' // 'bottom-left' | 'bottom-right' | 'top-left' | 'top-right'
});

// Close the widget
Brainfish.Widgets.close();

// Create a new conversation thread
// If widget is open, resets the current conversation
// If widget is closed, opens it with a new conversation
Brainfish.Widgets.createNewThread();

// Check if widget is ready
if (Brainfish.Widgets.isReady) {
    // Widget is ready to use
}

User Management

// Identify a user
Brainfish.Widgets.identify({
    name: "John Doe",
    email: "[e-mail]",
    userId: "user_123"
});

// Set secret attributes (for internal use)
Brainfish.Widgets.setSecretAttributes("internal_data_123");

Customization with Overrides

Customize your widget's appearance and behavior using the overrides configuration:

Brainfish.Widgets.init({
    widgetKey: "your-widget-key",
    overrides: {
        // Suggested questions that appear when widget opens
        suggestions: [
            'How do I reset my password?',
            'How do I contact support?',
            'What are your pricing plans?'
        ],

        // Theme customization
        theme: {
            inputButtonBgColor: '#3b82f6',
            inputButtonColor: '#ffffff'
        },

        // Widget settings
        panelTitle: 'Help Center',
        placeholder: 'Ask a question...',

        // Action buttons
        bodyActionButtons: [
            {
                icon: 'Calendar',
                type: 'link',
                label: 'Book a Demo',
                value: 'https://calendly.com/your-company'
            }
        ]
    }
});

📚 For complete customization options, see:

• Overrides Guide - Complete documentation with examples
• Quick Reference - Fast lookup for common configurations

Custom Positioning

Both open() and onContextHelp() methods support custom positioning to control where the widget appears on screen. This is useful for creating contextual experiences or avoiding UI conflicts.

Available Positions:

• 'bottom-left' - Widget appears in bottom-left corner (default)
• 'bottom-right' - Widget appears in bottom-right corner
• 'top-left' - Widget appears in top-left corner
• 'top-right' - Widget appears in top-right corner

Usage Examples:

// Open widget in different positions
Brainfish.Widgets.open({ position: 'top-right' });
Brainfish.Widgets.open({ position: 'bottom-left' });

// Contextual help with positioning
Brainfish.Widgets.onContextHelp("How do I reset my password?", {
    position: 'top-left'
});

// Dynamic positioning based on user interaction
function showHelpNearElement(question, element) {
    const rect = element.getBoundingClientRect();
    const position = rect.left < window.innerWidth / 2 ? 'bottom-left' : 'bottom-right';

    Brainfish.Widgets.onContextHelp(question, { position });
}

Contextual Help Feature

The contextual help feature allows you to open the widget with a pre-filled question based on user interaction.

// Trigger contextual help with a specific question
Brainfish.Widgets.onContextHelp("How do I reset my password?");

// Trigger contextual help with custom positioning
Brainfish.Widgets.onContextHelp("How do I reset my password?", {
    position: 'top-left' // 'bottom-left' | 'bottom-right' | 'top-left' | 'top-right'
});

Implementation Examples

HTML with Help Icons:

<div class="form-field">
    <label>Email Address</label>
    <input type="email" value="[e-mail]">
    <button class="help-icon"
            data-question="How do I change my email address?"
            data-position="top-left">
        <i class="ph ph-question"></i>
    </button>
</div>

<script>
// Add event listeners to help icons with custom positioning
document.querySelectorAll('.help-icon').forEach(icon => {
    icon.addEventListener('click', (e) => {
        const question = e.target.dataset.question;
        const position = e.target.dataset.position || 'bottom-right';
        Brainfish.Widgets.onContextHelp(question, { position });
    });
});
</script>

Direct Button Integration:

<button onclick="Brainfish.Widgets.onContextHelp('How do I reset my password?', { position: 'top-right' })">
    Reset Password
</button>

Programmatic Usage:

function showHelp(question, position = 'bottom-right') {
    Brainfish.Widgets.onContextHelp(question, { position });
}

// Usage with different positions
showHelp("How do I update my profile?", 'top-left');
showHelp("How do I contact support?", 'bottom-right');

Event Listeners

The widget emits events when it opens and closes. You can listen to these events:

// Set up the abort controller
const controller = new AbortController();
const { signal } = controller;

// Listen for widget events
window.addEventListener('onBrainfishWidgetOpen', (event) => {
    console.log('Widget opened');
    // Your custom logic here
}, { signal });

window.addEventListener('onBrainfishWidgetClose', (event) => {
    console.log('Widget closed');
    // Your custom logic here
}, { signal });

// Clean up event listeners when no longer needed
controller.abort();

Analytics Events

The widget automatically tracks analytics events:

• Open Widget - When the widget is opened
• Open Widget - Contextual Help - When opened via contextual help
• Open Widget - Custom Trigger - When opened with custom trigger
• Close Widget - When the widget is closed

Build

Run the following command to build the widget:

yarn build:web-widget

Testing locally

Start the local server

cd packages/web-widget
npx serve ./ -p 8000 -C

Open the Playground

The playground provides a comprehensive testing environment for the Brainfish widget:

open http://localhost:8000/playground/index.html

The playground includes:

• Widget Configuration - Set environment, API key, and widget settings
• Contextual Help Testing - Test the new contextual help feature with sample questions
• Real-world Demo - See how customers would implement contextual help in their apps
• API Testing - Test all widget methods and functionality
• Live Logs - Monitor widget events and debugging information

Test Different Environments

You can test the widget in different environments by passing the env parameter:

# Local environment
open http://localhost:8000/playground/index.html?env=local

# Staging environment
open http://localhost:8000/playground/index.html?env=staging

# Production environment
open http://localhost:8000/playground/index.html?env=prod

Agent Widget Development

If you want to test with the agent widget (Next.js app), start it locally:

cd packages/agent-widget
npm run dev

This will run the agent widget on port 3000, which the playground will automatically connect to in local development mode.