outsella-widget
Version:
A voice-enabled widget SDK for Outsella assistant
245 lines (179 loc) • 6.11 kB
Markdown
# Outsella Widget SDK
The Outsella Widget SDK provides a voice-enabled assistant that integrates seamlessly into any web application. Delivered as a single script, it automatically adds a customizable `<outsella-widget>` web component to your page. It works across React, Next.js, Vue, Angular, and plain HTML without extra wrappers, offering a unified API regardless of your framework.
## Installation
### Via CDN (Recommended)
Add the script to your HTML `<head>` or `<body>`:
```html
<script
src="https://unpkg.com/outsella-widget/dist/main.umd.js"
data-position="right"
data-agentid="9d87f124-55e5-4f6c-b85a-843276ec0be0"
></script>
```
- The widget will automatically append to the `<body>` with the specified `position` and `agentid`.
- No additional CSS `<link>` is required—styles are bundled in the script.
### Via NPM
For framework-specific projects:
```bash
npm install outsella-widget
```
Then import in your project:
```javascript
import "outsella-widget"; // Registers the widget and appends it
```
- Note: Styles are included in the script, so no separate CSS import is needed unless you want to override them.
---
## Usage Options
### 1. Plain HTML (Script Method)
Load the widget with a single script tag:
```html
<html lang="en">
<head>
<script
src="https://unpkg.com/outsella-widget/dist/main.umd.js"
data-position="left"
data-agentid="9d87f124-55e5-4f6c-b85a-843276ec0be0"
></script>
</head>
<body></body>
</html>
```
- The widget auto-appends to `<body>` with the specified attributes.
### 2. Plain HTML (Custom Element Method)
Manually add the `<outsella-widget>` tag if preferred:
```html
<html lang="en">
<head>
<script src="https://unpkg.com/outsella-widget/dist/main.umd.js"></script>
</head>
<body>
<outsella-widget
position="right"
agentid="9d87f124-55e5-4f6c-b85a-843276ec0be0"
></outsella-widget>
</body>
</html>
```
### 3. React Applications
Use the custom element directly:
```jsx
function App() {
return (
<div>
<h1>My React App</h1>
<outsella-widget
position="right"
agentid="9d87f124-55e5-4f6c-b85a-843276ec0be0"
></outsella-widget>
</div>
);
}
export default App;
```
- Import `"outsella-widget"` in your entry file (e.g., `index.js`) if using NPM:
```javascript
import "outsella-widget";
```
### 4. Next.js Applications
Use the custom element with client-side rendering:
```jsx
"use client";
export default function Page() {
return (
<outsella-widget
position="left"
agentid="9d87f124-55e5-4f6c-b85a-843276ec0be0"
></outsella-widget>
);
}
```
- Import `"outsella-widget"` in `_app.js` or a top-level file if using NPM:
```javascript
import "outsella-widget";
```
### 5. Vue Applications
Use the custom element in your template:
```vue
<template>
<outsella-widget
position="right"
agentid="9d87f124-55e5-4f6c-b85a-843276ec0be0"
/>
</template>
<script setup>
import "outsella-widget"; // Registers the widget
</script>
```
### 6. Angular Applications
Add the custom element schema and use the tag:
```typescript
import { NgModule, CUSTOM_ELEMENTS_SCHEMA } from "@angular/core";
@NgModule({
schemas: [CUSTOM_ELEMENTS_SCHEMA],
})
export class AppModule {}
```
```html
<outsella-widget
position="left"
agentid="9d87f124-55e5-4f6c-b85a-843276ec0be0"
></outsella-widget>
```
- Import `"outsella-widget"` in `main.ts` if using NPM:
```typescript
import "outsella-widget";
```
---
## Configuration Options
### Script Attributes (CDN Method)
When using the script tag:
| Attribute | Type | Description | Default |
|-----------------|--------|---------------------------------------------|-----------|
| `data-position` | string | Widget position: "left" or "right" | `"right"` |
| `data-agentid` | string | Unique identifier for agent configuration | Required |
### Element Attributes (Custom Element Method)
When using `<outsella-widget>`:
| Property | Type | Description | Default |
|------------|--------|---------------------------------------------|-----------|
| `position` | string | Widget position: "left" or "right" | `"right"` |
| `agentid` | string | Unique identifier for agent configuration | Required |
---
## Key Features
- **Single Script Integration**: No separate CSS or dependencies—just one `<script>` tag.
- **Shadow DOM Encapsulation**: Styles are isolated from the host page.
- **Responsive Design**: Adapts to mobile screens automatically.
- **Voice First**: Built-in voice recognition capabilities.
- **Customizable**: Override styles with CSS variables inside the shadow DOM.
```css
/* Override styles by targeting the custom element */
outsella-widget {
--primary-color: #2563eb;
--border-radius: 1rem;
}
```
---
## Browser Support
| Browser | Version |
| ------- | ------- |
| Chrome | 64+ |
| Firefox | 69+ |
| Safari | 14.1+ |
| Edge | 79+ |
---
## Troubleshooting
**Widget Not Appearing?**
1. **CDN Method**: Check the `<script>` tag’s `src`, `data-position`, and `data-agentid`. Ensure the URL is correct and the network request succeeds.
2. **Custom Element Method**: Verify `agentid` is valid and the script loads before the element is parsed (use `<script defer>` if in `<head>`).
3. Open DevTools to inspect `<outsella-widget>` and its shadow root.
**Font or Styles Not Applying?**
1. Ensure your widget’s CSS (bundled in the script) includes `font-family` rules.
2. Check the shadow root’s `<style>` element in DevTools for your styles.
**Voice Not Working?**
1. Use HTTPS (required for Web Speech API).
2. Check microphone permissions in the browser.
3. Confirm Web Speech API support (Chrome 33+, Edge 79+, etc.).
---
## License
[Add your license details here, e.g., MIT, Apache 2.0, etc.]