@convai/web-sdk 1.6.0-beta.0 → 1.6.0-beta.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +39 -45
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -45,7 +45,7 @@ yarn add @convai/web-sdk
|
|
|
45
45
|
### React
|
|
46
46
|
|
|
47
47
|
```tsx
|
|
48
|
-
import { useConvaiClient, ConvaiWidget } from
|
|
48
|
+
import { useConvaiClient, ConvaiWidget } from "@convai/web-sdk";
|
|
49
49
|
|
|
50
50
|
export function App() {
|
|
51
51
|
const client = useConvaiClient({
|
|
@@ -60,7 +60,7 @@ export function App() {
|
|
|
60
60
|
### Vanilla TypeScript
|
|
61
61
|
|
|
62
62
|
```ts
|
|
63
|
-
import { ConvaiClient, createConvaiWidget } from
|
|
63
|
+
import { ConvaiClient, createConvaiWidget } from "@convai/web-sdk/vanilla";
|
|
64
64
|
|
|
65
65
|
const client = new ConvaiClient({
|
|
66
66
|
apiKey: import.meta.env.VITE_CONVAI_API_KEY,
|
|
@@ -69,7 +69,7 @@ const client = new ConvaiClient({
|
|
|
69
69
|
|
|
70
70
|
const widget = createConvaiWidget(document.body, { convaiClient: client });
|
|
71
71
|
|
|
72
|
-
window.addEventListener(
|
|
72
|
+
window.addEventListener("beforeunload", () => {
|
|
73
73
|
widget.destroy();
|
|
74
74
|
void client.disconnect();
|
|
75
75
|
});
|
|
@@ -81,34 +81,34 @@ window.addEventListener('beforeunload', () => {
|
|
|
81
81
|
|
|
82
82
|
Full documentation is at **<a href="https://docs.convai.com/api-docs/plugins-and-integrations/web-plugins/convai-web-sdk" target="_blank" rel="noopener noreferrer">docs.convai.com</a>**.
|
|
83
83
|
|
|
84
|
-
| Guide
|
|
85
|
-
|
|
86
|
-
| <a href="https://docs.convai.com/api-docs/plugins-and-integrations/web-plugins/convai-web-sdk" target="_blank" rel="noopener noreferrer">Quick Start</a>
|
|
87
|
-
| <a href="https://docs.convai.com/api-docs/plugins-and-integrations/web-plugins/convai-web-sdk" target="_blank" rel="noopener noreferrer">Configuration</a>
|
|
88
|
-
| <a href="https://docs.convai.com/api-docs/plugins-and-integrations/web-plugins/convai-web-sdk" target="_blank" rel="noopener noreferrer">React Integration</a>
|
|
89
|
-
| <a href="https://docs.convai.com/api-docs/plugins-and-integrations/web-plugins/convai-web-sdk" target="_blank" rel="noopener noreferrer">Vanilla JS</a>
|
|
90
|
-
| <a href="https://docs.convai.com/api-docs/plugins-and-integrations/web-plugins/convai-web-sdk/event-reference" target="_blank" rel="noopener noreferrer">Events</a>
|
|
91
|
-
| <a href="https://docs.convai.com/api-docs/plugins-and-integrations/web-plugins/convai-web-sdk/dynamic-context" target="_blank" rel="noopener noreferrer">Context Management</a>
|
|
92
|
-
| <a href="https://docs.convai.com/api-docs/plugins-and-integrations/web-plugins/convai-web-sdk/emotions" target="_blank" rel="noopener noreferrer">Emotions</a>
|
|
93
|
-
| <a href="https://docs.convai.com/api-docs/plugins-and-integrations/web-plugins/convai-web-sdk" target="_blank" rel="noopener noreferrer">Lipsync</a>
|
|
94
|
-
| <a href="https://docs.convai.com/api-docs/plugins-and-integrations/web-plugins/convai-web-sdk/actions" target="_blank" rel="noopener noreferrer">Actions</a>
|
|
95
|
-
| <a href="https://docs.convai.com/api-docs/plugins-and-integrations/web-plugins/convai-web-sdk/long-term-memory" target="_blank" rel="noopener noreferrer">Memory</a>
|
|
96
|
-
| <a href="https://docs.convai.com/api-docs/plugins-and-integrations/web-plugins/convai-web-sdk" target="_blank" rel="noopener noreferrer">Audio & Video</a>
|
|
97
|
-
| <a href="https://docs.convai.com/api-docs/plugins-and-integrations/web-plugins/convai-web-sdk/error-handling" target="_blank" rel="noopener noreferrer">Error Handling</a>
|
|
98
|
-
| <a href="https://docs.convai.com/api-docs/plugins-and-integrations/web-plugins/convai-web-sdk/auth-tokens" target="_blank" rel="noopener noreferrer">Auth Tokens</a>
|
|
99
|
-
| <a href="https://docs.convai.com/api-docs/plugins-and-integrations/web-plugins/convai-web-sdk/websocket-transport-layer" target="_blank" rel="noopener noreferrer">WebSocket Transport</a> | Alternative transport for WebRTC-constrained environments
|
|
84
|
+
| Guide | Description |
|
|
85
|
+
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------- |
|
|
86
|
+
| <a href="https://docs.convai.com/api-docs/plugins-and-integrations/web-plugins/convai-web-sdk" target="_blank" rel="noopener noreferrer">Quick Start</a> | First working integration in under 5 minutes |
|
|
87
|
+
| <a href="https://docs.convai.com/api-docs/plugins-and-integrations/web-plugins/convai-web-sdk" target="_blank" rel="noopener noreferrer">Configuration</a> | All `ConvaiConfig` options |
|
|
88
|
+
| <a href="https://docs.convai.com/api-docs/plugins-and-integrations/web-plugins/convai-web-sdk" target="_blank" rel="noopener noreferrer">React Integration</a> | `useConvaiClient`, `ConvaiWidget`, and React-specific patterns |
|
|
89
|
+
| <a href="https://docs.convai.com/api-docs/plugins-and-integrations/web-plugins/convai-web-sdk" target="_blank" rel="noopener noreferrer">Vanilla JS</a> | `ConvaiClient`, `createConvaiWidget`, and audio setup |
|
|
90
|
+
| <a href="https://docs.convai.com/api-docs/plugins-and-integrations/web-plugins/convai-web-sdk/event-reference" target="_blank" rel="noopener noreferrer">Events</a> | Full event reference — `botReady`, `stateChange`, `messagesChange`, `interactionCreated`, and more |
|
|
91
|
+
| <a href="https://docs.convai.com/api-docs/plugins-and-integrations/web-plugins/convai-web-sdk/dynamic-context" target="_blank" rel="noopener noreferrer">Context Management</a> | Dynamic context, `updateContext`, file upload, session management |
|
|
92
|
+
| <a href="https://docs.convai.com/api-docs/plugins-and-integrations/web-plugins/convai-web-sdk/emotions" target="_blank" rel="noopener noreferrer">Emotions</a> | Per-turn emotion detection with provider options |
|
|
93
|
+
| <a href="https://docs.convai.com/api-docs/plugins-and-integrations/web-plugins/convai-web-sdk" target="_blank" rel="noopener noreferrer">Lipsync</a> | ARKit / MetaHuman blendshape streams and `BlendshapeQueue` API |
|
|
94
|
+
| <a href="https://docs.convai.com/api-docs/plugins-and-integrations/web-plugins/convai-web-sdk/actions" target="_blank" rel="noopener noreferrer">Actions</a> | Trigger character behaviors and scene actions |
|
|
95
|
+
| <a href="https://docs.convai.com/api-docs/plugins-and-integrations/web-plugins/convai-web-sdk/long-term-memory" target="_blank" rel="noopener noreferrer">Memory</a> | Long-term memory scoped to end users |
|
|
96
|
+
| <a href="https://docs.convai.com/api-docs/plugins-and-integrations/web-plugins/convai-web-sdk" target="_blank" rel="noopener noreferrer">Audio & Video</a> | Microphone, camera, screen share controls |
|
|
97
|
+
| <a href="https://docs.convai.com/api-docs/plugins-and-integrations/web-plugins/convai-web-sdk/error-handling" target="_blank" rel="noopener noreferrer">Error Handling</a> | `error`, `disconnect`, `serverResponse`, retry patterns |
|
|
98
|
+
| <a href="https://docs.convai.com/api-docs/plugins-and-integrations/web-plugins/convai-web-sdk/auth-tokens" target="_blank" rel="noopener noreferrer">Auth Tokens</a> | Server-side token exchange for production |
|
|
99
|
+
| <a href="https://docs.convai.com/api-docs/plugins-and-integrations/web-plugins/convai-web-sdk/websocket-transport-layer" target="_blank" rel="noopener noreferrer">WebSocket Transport</a> | Alternative transport for WebRTC-constrained environments |
|
|
100
100
|
|
|
101
101
|
---
|
|
102
102
|
|
|
103
103
|
## Package entry points
|
|
104
104
|
|
|
105
|
-
| Import path
|
|
106
|
-
|
|
107
|
-
| `@convai/web-sdk`
|
|
108
|
-
| `@convai/web-sdk/react`
|
|
109
|
-
| `@convai/web-sdk/vanilla`
|
|
110
|
-
| `@convai/web-sdk/core`
|
|
111
|
-
| `@convai/web-sdk/lipsync-helpers`
|
|
105
|
+
| Import path | Contents |
|
|
106
|
+
| ----------------------------------- | --------------------------------------------------------------------------------------------------------------- |
|
|
107
|
+
| `@convai/web-sdk` | React hooks, components, and re-exported core types |
|
|
108
|
+
| `@convai/web-sdk/react` | Same as default (React-explicit alias) |
|
|
109
|
+
| `@convai/web-sdk/vanilla` | `ConvaiClient`, `createConvaiWidget`, `AudioRenderer` |
|
|
110
|
+
| `@convai/web-sdk/core` | Framework-agnostic `ConvaiClient`, managers, and all types |
|
|
111
|
+
| `@convai/web-sdk/lipsync-helpers` | Blendshape format utilities and queue helpers |
|
|
112
112
|
| `@convai/web-sdk/vanilla/websocket` | **Opt-in.** Registers the WebSocket transport. Import alongside `/vanilla` when using `transport: "websocket"`. |
|
|
113
113
|
|
|
114
114
|
---
|
|
@@ -119,13 +119,13 @@ The default transport is WebRTC (LiveKit). A WebSocket-based transport is availa
|
|
|
119
119
|
|
|
120
120
|
```ts
|
|
121
121
|
// Add this import once (e.g. in your app entry file)
|
|
122
|
-
import
|
|
123
|
-
import { ConvaiClient } from
|
|
122
|
+
import "@convai/web-sdk/vanilla/websocket";
|
|
123
|
+
import { ConvaiClient } from "@convai/web-sdk/vanilla";
|
|
124
124
|
|
|
125
125
|
const client = new ConvaiClient({
|
|
126
|
-
apiKey:
|
|
127
|
-
characterId:
|
|
128
|
-
transport:
|
|
126
|
+
apiKey: "...",
|
|
127
|
+
characterId: "...",
|
|
128
|
+
transport: "websocket",
|
|
129
129
|
});
|
|
130
130
|
```
|
|
131
131
|
|
|
@@ -140,7 +140,7 @@ See the <a href="https://docs.convai.com/api-docs/plugins-and-integrations/web-p
|
|
|
140
140
|
Vision dynamic context is the default WebRTC/LiveKit vision path when `enableVideo: true`. Camera, screen, canvas, and custom video tracks can feed unified vision context; set `visionInputConfig.enabled: false` only when you need to keep the video channel while opting out.
|
|
141
141
|
|
|
142
142
|
```tsx
|
|
143
|
-
import { useConvaiClient } from
|
|
143
|
+
import { useConvaiClient } from "@convai/web-sdk";
|
|
144
144
|
|
|
145
145
|
const client = useConvaiClient({
|
|
146
146
|
apiKey: import.meta.env.VITE_CONVAI_API_KEY,
|
|
@@ -157,10 +157,10 @@ const client = useConvaiClient({
|
|
|
157
157
|
replacePreviousVisionContext: true,
|
|
158
158
|
},
|
|
159
159
|
respondModes: {
|
|
160
|
-
vision:
|
|
161
|
-
contextUpdate:
|
|
162
|
-
sceneMetadata:
|
|
163
|
-
trigger:
|
|
160
|
+
vision: "silent",
|
|
161
|
+
contextUpdate: "auto",
|
|
162
|
+
sceneMetadata: "silent",
|
|
163
|
+
trigger: "must_respond",
|
|
164
164
|
},
|
|
165
165
|
});
|
|
166
166
|
```
|
|
@@ -171,14 +171,14 @@ Publish visual sources with semantic labels so acknowledgments can distinguish w
|
|
|
171
171
|
await client.videoControls.enableVideo(); // webcam source
|
|
172
172
|
|
|
173
173
|
const handle = await client.videoControls.publishCanvas(canvas, {
|
|
174
|
-
source:
|
|
175
|
-
name:
|
|
174
|
+
source: "canvas",
|
|
175
|
+
name: "canvas-pov",
|
|
176
176
|
fps: 1,
|
|
177
177
|
});
|
|
178
178
|
|
|
179
179
|
const statusId = client.visionStatus();
|
|
180
180
|
const triggerId = client.visionTrigger({
|
|
181
|
-
respondMode:
|
|
181
|
+
respondMode: "silent",
|
|
182
182
|
frameIndices: [-1, -1],
|
|
183
183
|
});
|
|
184
184
|
|
|
@@ -195,12 +195,6 @@ npm install @convai/web-sdk@beta
|
|
|
195
195
|
|
|
196
196
|
---
|
|
197
197
|
|
|
198
|
-
## Example app
|
|
199
|
-
|
|
200
|
-
A full React Three Fiber integration demo is in [`examples/react-three-fiber`](./examples/react-three-fiber/). It demonstrates lipsync on a 3D character, emotion display, dynamic context, vision validation, and file upload.
|
|
201
|
-
|
|
202
|
-
---
|
|
203
|
-
|
|
204
198
|
## License
|
|
205
199
|
|
|
206
200
|
Licensed under the [Apache License 2.0](./LICENSE). Copyright 2025 Convai.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@convai/web-sdk",
|
|
3
|
-
"version": "1.6.0-beta.
|
|
3
|
+
"version": "1.6.0-beta.1",
|
|
4
4
|
"description": "Build web apps with lifelike AI characters. The Convai Web SDK gives you real-time voice, lipsync, emotions, and dynamic context — with first-class support for React and vanilla TypeScript.",
|
|
5
5
|
"private": false,
|
|
6
6
|
"type": "module",
|