@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();

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

// 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");

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?");

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?">
        <i class="ph ph-question"></i>
    </button>
</div>

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

Direct Button Integration:

<button onclick="Brainfish.Widgets.onContextHelp('How do I reset my password?')">
    Reset Password
</button>

Programmatic Usage:

function showHelp(question) {
    Brainfish.Widgets.onContextHelp(question);
}

// Usage
showHelp("How do I update my profile?");

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.