159 lines
3.6 KiB
Markdown
159 lines
3.6 KiB
Markdown
# 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
|
|
|