Embed SDK
Embed Upcube avatars on any website with a single script tag. This is a demo SDK foundation — not a production CDN release.
Embed concepts
Understand the building blocks before integrating.
Embed Config
Controls how your avatar widget appears and behaves. Choose theme, position, default mode, and branding visibility.
Theme: system
Position: bottom-right
Mode: text
Domain Allowlist
Only listed domains can initialize the widget. Protects against unauthorized embedding on other sites.
upcube.ai
Session Token
Short-lived token generated server-side. Scoped to one domain and one agent. Never exposed to unauthorized clients.
Token: demo_**********_placeholder
Expires: 15 minutes
Config validation result
The validateEmbedConfig helper checks for required fields and valid enum values.
Integration snippet
Copy this snippet into any HTML page to embed an Upcube avatar. Replace placeholder values with your own configuration.
<!-- Upcube Avatar Cloud Embed SDK (Demo) -->
<!-- This is a demo SDK foundation — not a production CDN release. -->
<!-- In production, replace src with the official SDK bundle URL. -->
<div id="upcube-avatar-cloud-root"></div>
<script type="application/json" id="upcube-embed-config">
{
"agentId": "sample_ethen_agent",
"sessionToken": "demo_session_token_placeholder",
"allowedDomains": [
"example.com",
"upcube.ai"
],
"theme": "system",
"position": "bottom-right",
"defaultMode": "text",
"showBranding": true,
"leadCaptureEnabled": false
}
</script>
<script src="/embed.js" defer></script>This is a demo SDK foundation scaffold. The embed script (/embed.js) is a static placeholder that demonstrates the structure but does not connect to any real avatar backend, session manager, or STT/TTS pipeline. Do not use in production.
Widget preview
When integrated, the widget would appear in the configured position on your page.
Ethen avatar widget
The widget would render here at configured position
- Theme: system
- Position: bottom-right
- Mode: text
Architecture
How the embed SDK fits into the Upcube Avatar Cloud platform.
1. Site owner configures an agent
From the Upcube Console, configure a LiveAgent persona, attach an EmbedConfig with allowed domains, and generate a short-lived session token.
2. Site owner adds the script tag
Copy the generated snippet into any HTML page. The snippet includes a config block and references the embed script.
3. Widget validates and renders
The embed script reads the config, validates the origin against allowed domains, exchanges the session token server-side, and renders the avatar widget in the configured position.
4. Visitor interacts with the avatar
Site visitors see the avatar widget, can type or speak to it, and get real-time responses. Events are streamed back to Upcube for analytics.
SDK roadmap
What's coming for the embed SDK.