Introduction

There are two very different ways to put a realtime avatar on a web page: an embedded avatar widget and a native Astro integration. They can look similar from the outside, but they solve different problems, with different trust boundaries, performance characteristics, and maintenance costs.

The short version: an embedded widget is a prebuilt runtime you drop into a site, usually through an <iframe>. A native Astro integration is application code you own inside your Astro app, where you render UI, manage state, and wire avatar events directly into your frontend and backend.

If you are deciding between them, the right question is not “which is better?” It is “where do I want the integration to live, and how much control do I need?” By the end of this post, you should be able to choose the right surface for your app, understand the operational trade-offs, and know where each approach fits in a realtime avatar stack.

What an embedded avatar widget actually is

An embedded widget is a self-contained avatar experience hosted by the provider and mounted into your page with an <iframe>. The page does not directly run the avatar session logic. Instead, your site acts as the container, while the widget handles the realtime connection, rendering, and interaction internally.

That architecture matters. It means:

• Your browser never needs to hold an API key.

• The widget can enforce its own session controls, such as parent-origin allowlisting and per-embed limits.

• You can add an avatar to a marketing page, help center, or product surface without adding backend code.

Operationally, this is the lowest-friction path. You configure the embed, copy the iframe snippet, and you are done. It is a good fit when you want a finished interaction surface rather than a deeply customized component.

What a native Astro integration actually is

A native Astro integration means you build the avatar experience as part of your Astro application. Astro renders the page, but the avatar logic is yours: session creation, token handling, UI state, event listeners, error handling, and any custom business logic around the conversation.

That gives you much tighter control over the experience. You can:

• Place the avatar inside a bespoke layout instead of an iframe.

• Coordinate avatar state with the rest of your app.

• Gate access using your own auth system.

• Route conversation events into analytics, support workflows, or product logic.

The trade-off is that you own more of the integration surface. If the avatar needs a session token, your app or backend must mint or fetch it. If the stream drops, you own the recovery logic. If the UI needs to react to the agent speaking, listening, or finishing, you implement that wiring.

The real difference: trust boundary, not just packaging

People often describe the difference as “iframe vs. component,” but the more useful distinction is the trust boundary.

With an embedded widget, the provider owns the runtime boundary. Your application hands off control to a sandboxed surface, which is useful when you want to avoid exposing credentials or replicating session-management logic in every client. This is especially attractive for customer-facing sites where the avatar is a feature, not the core app.

With a native Astro integration, your application owns the boundary. That means more flexibility, but also more responsibility. You decide how to authenticate users, when to create sessions, what data the avatar can see, and how the avatar UI fits into the page lifecycle.

In practice, this changes how you think about failure modes:

• Embedded widget: simpler deployment, fewer moving parts in your app, but less control over the internals.

• Native integration: more code and more ownership, but better composition with the rest of your product.

Realtime mechanics: what is happening under the hood

Regardless of the surface, a realtime avatar is usually part of a streaming conversation loop. Speech or text enters the agent, the agent generates a response, and the avatar streams synchronized video with lip motion aligned to the produced speech. In a voice-agent setup, that typically rides on top of a low-latency media pipeline such as WebRTC or an equivalent streaming transport.

That has a few practical implications:

• You are not loading a static video asset. You are joining a session.

• Latency matters more than in ordinary UI components.

• Session lifecycle matters: connect, negotiate, stream, reconnect, teardown.

An embedded widget hides most of that lifecycle. A native integration exposes it to your app, which is useful if you need to coordinate the avatar with a voice agent, call state, or product workflow.

When an iframe embed is the right choice

Choose the embedded widget when you want fast time-to-value and a constrained attack surface. Typical cases:

• A support or sales landing page that needs a talking avatar.

• A campaign site where the avatar is mostly self-contained.

• A product demo that should be easy to ship and easy to remove.

It is also the best option when you explicitly do not want browser-side secrets. A well-designed embed can keep API keys server-side or eliminate the need for them in the browser entirely, which is exactly what you want for a public-facing page.

The limitation is customization depth. If you need the avatar to participate in app-wide state, share auth context, or emit rich telemetry into your frontend architecture, the iframe will eventually feel like a boundary you are fighting.

When a native Astro integration is the right choice

Choose native integration when the avatar is part of the product, not just embedded in it. Examples:

• A conversational assistant inside a logged-in dashboard.

• A game or simulation UI where the avatar drives state transitions.

• A customer-support workflow that needs tight coupling to ticket state and user identity.

Astro is a good fit here because it lets you keep most of the page server-rendered while still building interactive islands where needed. That is useful when the avatar is one part of a larger app and you want to keep the rest of the page simple and fast.

But be honest about ownership. Native integration means you need backend code for session creation and probably some way to keep API keys out of the browser. It also means your frontend team owns the lifecycle bugs: reconnects, duplicate joins, stale state, and cleanup on navigation.

Minimal example: creating a session from your backend

If you go native, the usual pattern is: your server calls the REST API, then your client uses the returned session details. Exact request and response fields depend on the avatar/session shape in the docs, but the flow looks like this:

curl -X POST https://api.protoface.com/v1/sessions \
}'

curl -X POST https://api.protoface.com/v1/sessions \
}'

curl -X POST https://api.protoface.com/v1/sessions \
}'

The important part is not the exact JSON above; it is the pattern. Keep the key on the server, create sessions server-side, then hand the browser only the minimum data it needs to connect.

Minimal example: Python SDK in a backend service

If your app already has Python backend code, the SDK is usually the cleanest way to create and manage sessions programmatically. The API shape is intentionally small: instantiate the client, call the relevant method, and pass the resulting session data to your frontend or voice-agent runtime.

from protoface import ProtofaceClient

print(session)

from protoface import ProtofaceClient

print(session)

from protoface import ProtofaceClient

print(session)

Use this pattern when the avatar session is created as part of an authenticated server flow, not directly from the browser.

How this relates to LiveKit voice agents

There is one important adjacent case: if your “avatar” is really the face of a voice agent, you may not be choosing between iframe and Astro at all. You may be integrating the avatar into an agent runtime such as LiveKit.

In that setup, the avatar becomes one media surface in a larger agent pipeline. The agent handles audio, turn-taking, and conversational state; the avatar handles the synchronized talking face. The integration point is the agent runtime, not your website layout.

A typical Python-side setup looks like this:

from livekit.plugins import protoface

)

from livekit.plugins import protoface

)

from livekit.plugins import protoface

)

If you are building a voice agent, this is often the cleaner architecture because the avatar is attached where the conversation already lives. See the plugin examples in the relevant GitHub repository and the documentation at docs.protoface.com for the exact runtime details.

Practical decision checklist

Use this as a quick rule of thumb:

• Choose the embedded widget if you want speed, isolation, and no browser-exposed credentials.

• Choose a native Astro integration if you need tight UI composition, app state coupling, or custom lifecycle control.

• Choose a backend-managed session flow whenever the client should not hold secrets.

• Choose an agent integration when the avatar is part of a voice pipeline rather than a standalone UI surface.

Also consider billing and observability early. Realtime avatars are not just static assets; they are ongoing sessions with quality tiers, usage, and operational state. If you care about that in production, instrument it from day one.

Conclusion

An embedded avatar widget and a native Astro integration are not competing implementations of the same thing. They represent two different levels of ownership. The iframe embed gives you a constrained, low-friction runtime. The native Astro approach gives you composition and control, at the cost of more integration work.

If you are just trying to ship a realtime avatar to a public page, start with the embed. If the avatar is becoming part of your product’s interaction model, move it into your app and own the session lifecycle explicitly. If you are building a voice agent, attach the avatar at the agent layer instead of forcing the browser to do work it should not own.

For implementation details, start with the docs at docs.protoface.com, and use the quickstarts and SDKs as reference material when you need to move from architecture to code.