virtual-banker/docs/WIDGET_INTEGRATION.md

# Widget Integration Guide

## Quick Start

### 1. Include the Widget Script

Add the widget loader script to your HTML page:

```html
<script src="https://cdn.example.com/virtual-banker/widget.js"
        data-tenant-id="your-tenant-id"
        data-user-id="user-123"
        data-auth-token="jwt-token"
        data-api-url="https://api.example.com"
        data-avatar-enabled="true"></script>
<div id="virtual-banker-widget"></div>
```

### 2. Configuration Options

| Attribute | Required | Description |
|-----------|----------|-------------|
| `data-tenant-id` | Yes | Tenant identifier |
| `data-user-id` | No | User identifier (for authenticated sessions) |
| `data-auth-token` | No | JWT token for authentication |
| `data-api-url` | No | API base URL (default: http://localhost:8081) |
| `data-avatar-enabled` | No | Enable/disable avatar (default: true) |

## Programmatic API

### Methods

```javascript
// Open widget
window.VirtualBankerWidgetAPI.open();

// Close widget
window.VirtualBankerWidgetAPI.close();

// Minimize widget
window.VirtualBankerWidgetAPI.minimize();

// Set context (page/route information)
window.VirtualBankerWidgetAPI.setContext({
  route: '/account',
  accountId: 'acc-123',
  productId: 'prod-456'
});

// Update authentication token
window.VirtualBankerWidgetAPI.setAuthToken('new-jwt-token');
```

## PostMessage Events

Listen for widget events from the parent window:

```javascript
window.addEventListener('message', (event) => {
  if (event.data.source === 'virtual-banker-widget') {
    switch (event.data.type) {
      case 'ready':
        console.log('Widget is ready');
        break;
      
      case 'session_started':
        console.log('Session ID:', event.data.payload.sessionId);
        break;
      
      case 'action_requested':
        console.log('Action:', event.data.payload.action);
        console.log('Params:', event.data.payload.params);
        // Handle action (e.g., open ticket, schedule appointment)
        break;
      
      case 'action_completed':
        console.log('Action completed:', event.data.payload);
        break;
      
      case 'handoff_to_human':
        console.log('Handoff reason:', event.data.payload.reason);
        // Show human agent interface
        break;
    }
  }
});
```

## Sending Messages to Widget

Send commands to the widget from the parent window:

```javascript
const widget = document.getElementById('virtual-banker-widget');
if (widget && widget.contentWindow) {
  widget.contentWindow.postMessage({
    type: 'open',
    source: 'virtual-banker-host'
  }, '*');
}
```

Available commands:
- `open` - Open the widget
- `close` - Close the widget
- `minimize` - Minimize the widget
- `setContext` - Update context
- `setAuthToken` - Update auth token

## Styling

The widget can be styled via CSS:

```css
#virtual-banker-widget {
  position: fixed;
  bottom: 20px;
  right: 20px;
  width: 400px;
  height: 600px;
  z-index: 9999;
  border-radius: 8px;
  box-shadow: 0 4px 16px rgba(0, 0, 0, 0.2);
}

#virtual-banker-widget.minimized {
  height: 60px;
  width: 200px;
}
```

## Theming

Theme can be configured per tenant via the backend API. The widget will automatically apply the theme from the session configuration.

## Accessibility

The widget is built with accessibility in mind:
- Full keyboard navigation
- Screen reader support
- ARIA labels
- Captions always available
- Reduced motion support (respects OS preference)

## Browser Support

- Chrome/Edge 90+
- Firefox 88+
- Safari 14+
- Mobile browsers (iOS Safari, Chrome Mobile)

## Security

- Content Security Policy (CSP) compatible
- No direct secrets in browser
- Ephemeral session tokens only
- CORS configured for embedding