Introduction

If you’re migrating a frontend to SvelteKit and need to ship an interactive AI avatar without slowing down the rest of the rewrite, an <iframe> is usually the least risky path. You isolate the realtime avatar UI, keep auth off the browser, and avoid coupling your migration schedule to whatever the avatar stack is doing underneath.

By the end of this post, you should be able to:

• Embed a conversational avatar in SvelteKit with a customer-managed iframe.

• Understand the integration boundary: what lives in the parent app versus inside the iframe.

• Handle migration concerns like origin allowlists, session lifecycle, and basic sizing.

• Decide when to keep the iframe and when to later replace it with a deeper integration.

The examples below assume a developer-facing avatar platform such as Protoface, where realtime avatar sessions are created server-side and then rendered into your site through a controlled embed.

Why iframe is the right migration tool

During a frontend migration, the biggest risk is usually not the avatar itself. It’s everything around it: auth, state synchronization, layout, browser permissions, and the fact that realtime media is unforgiving when you keep touching the plumbing. An iframe gives you a hard boundary.

That boundary matters because a conversational avatar is not just “some video.” It typically combines:

• Mic capture and audio playback.

• WebRTC or a similar realtime transport for low-latency media.

• Stateful session management on the backend.

• Instruction/configuration for the agent persona, voice, and behavior.

When you embed the whole experience in an iframe, the parent SvelteKit app only needs to:

1. Render the iframe.

2. Set its size and layout.

3. Provide the allowed origin and any contextual parameters.

4. Optionally listen for postMessage events if the embed exposes them.

That means you can migrate page-by-page without rewriting the realtime surface under active users.

What should live outside the iframe

For a migration, keep the parent app boring. In SvelteKit, that usually means the parent handles routing, auth for your own application, and whatever business context determines whether the user should see the avatar. Everything avatar-specific stays behind the iframe boundary.

Practically, this separation gives you a few advantages:

• No API key in the browser. The embed can be provisioned server-side, so your client never sees the secret.

• Safer rollout. You can gate the iframe behind feature flags or route-level conditions while other parts of the app migrate.

• Cleaner failure modes. If the avatar service has an issue, your app still loads and the failure is localized.

• Easier layout work. The iframe can have a fixed aspect ratio or responsive container while your SvelteKit app evolves independently.

For a conversational avatar, that’s usually the right compromise until the migration settles. Later, if you need tighter event integration or a custom UI shell, you can revisit the boundary.

Embedding in SvelteKit

A minimal Svelte component can wrap the iframe and preserve aspect ratio. The exact embed URL and parameters depend on your provider, but the pattern is stable.

<script lang="ts">

</style>

<script lang="ts">

</style>

<script lang="ts">

</style>

A few details matter here:

• allow="microphone; autoplay; camera" is often necessary for realtime voice and media playback.

• aspect-ratio keeps the layout stable before the iframe loads.

• referrerpolicy should be explicit so you know what the embed can observe.

If your embed supports resizing via postMessage, use that to adapt height dynamically. Otherwise, keep the container dimensions predictable; voice agents feel much better when the layout doesn’t jump around during connection setup.

Server-side provisioning in SvelteKit

The important part of a customer-managed embed is that the browser never creates the session directly with an API key. Instead, your SvelteKit server route or server load function requests an embed/session URL from the avatar service and passes only the resulting URL to the page.

The exact request schema depends on the provider, but the shape is usually:

1. Authenticate your server to the avatar API.

2. Create an embed/session with an allowed parent origin.

3. Optionally include persona, voice, or instructions.

4. Render the returned embed URL in the page.

import type { PageServerLoad } from './$types';

};

import type { PageServerLoad } from './$types';

};

import type { PageServerLoad } from './$types';

};

This is intentionally illustrative. Use the fields and endpoint names from the docs, but keep the boundary the same: server creates, client renders.

Migration gotchas that are easy to miss

Most iframe embeds work on the first try. The bugs show up in the edge cases.

1. Origin mismatches. If the embed enforces parent-origin allowlisting, make sure you allow every environment that can host the page: localhost, preview deployments, staging, and production. During migration, preview URLs tend to change more often than anyone expects.

2. Autoplay and audio permissions. Browsers are strict about audio playback. If the agent speaks automatically, you may need a user gesture before playback starts. Don’t assume autoplay will work uniformly across browsers or devices.

3. Cookie and storage assumptions. An iframe is a separate browsing context. If your app or the embed assumes shared storage, that may not hold. Prefer explicit server-side session state over client-side coupling.

4. Layout shifts. Realtime video surfaces often render a placeholder, then connect, then negotiate media. Reserve space up front or the rest of your page will jump.

5. Lifecycle cleanup. In SvelteKit, navigation can destroy and recreate components quickly. Make sure iframe creation and teardown are idempotent so you don’t leave stale sessions around when route transitions happen.

What the embed should and should not do

For a migration, the iframe should do the realtime work and almost nothing else. That includes:

• Capturing and sending mic input.

• Receiving and rendering the avatar video stream.

• Applying persona/instruction settings for that session.

• Enforcing provider-side rate limits and duration limits if supported.

It should not become your application’s state management layer. Don’t push everything through the iframe just because it’s convenient. If the parent app needs to know whether a session is connected, or needs to show “connected / reconnecting / ended,” use a narrow message contract rather than trying to mirror the whole internal state machine.

That restraint pays off during migration. You can keep the integration intentionally dumb until you’re ready to pull the avatar closer to the rest of the app.

Where Protoface fits

Protoface’s customer-managed iframe embeds are a good fit when the requirement is “ship the avatar now, keep secrets off the client, and avoid backend work in the frontend migration.” The model is straightforward: your server provisions the embed, your SvelteKit page renders the iframe, and the realtime media session stays isolated from the rest of the app. The platform also supports parent-origin allowlisting and per-embed controls such as voice, custom instructions, and basic rate limiting, which are the exact knobs you usually want during a staged migration.

If you later move beyond the iframe, the same backend model still applies. You can create and manage avatars or sessions via the REST API, or use the Python SDK in orchestration code. For avatar-in-agent workflows, the LiveKit plugin is the relevant surface; for this specific migration pattern, the iframe is the one that keeps the frontend work bounded. The details are in the docs.

Conclusion

If you’re mid-migration, embedding a conversational AI avatar through an iframe is the pragmatic choice: it keeps realtime media isolated, avoids exposing API keys in the browser, and lets the rest of your SvelteKit app move independently. The implementation is mostly about discipline: provision on the server, lock down origins, reserve layout space, and keep the integration boundary narrow.

Start with the smallest possible embed, verify permissions and responsive behavior in all target environments, then expand only if you actually need tighter coupling. When you’re ready for the next step, the docs and quickstarts linked from the project site are the fastest way to map the embed pattern onto your exact stack.