Embedding a Live iOS or Android App

Embedding lets you drop a live, interactive device running your app into any web page with a single iframe — your marketing site, your docs, a sales demo page, wherever. Visitors can tap around your real app without installing anything.

Embedding is available on the Starter and Pro plans. If you’re on Free or Dev, upgrade to create an embed key. If your organization needs custom terms, contact support@vibeview.io.

Create an embed key

Go to Settings → Embeds and click New Embed Key. Each key controls one embeddable demo:

• Name — a label to help you tell keys apart (e.g. “Docs demo”).
• App — the app the embed streams. Every session started with this key runs this app.
• Allowed domains — the domains permitted to embed this key. Type a domain and press Enter (or comma) to add it; pasting a list splits it into entries automatically. On the Starter plan this is required and covers one domain (a domain and its subdomains count as one); on Professional it’s optional. See Domain allowlisting below.
• Max session duration (optional) — the longest a single visitor session may run, in seconds.
• Max concurrent sessions (optional) — the most sessions this key can have running at once. Visitors who tap start while the key is at its limit wait in a queue and start automatically when a slot frees up; if the wait line itself is full, they’re asked to try again in a few minutes.
• Device models (optional) — pick from a list of the device models currently available to your organization. Select none and visitors get a phone-size device; select one or more and visitors get any available device from your selection (pick a specific model to stream a different form factor, for example a tablet).
• Let visitors choose the device — when on, visitors can pick which device to run your app on. A picker only appears when you’ve selected two or more device models; with one model (or none) selected, visitors get a default device with no picker.
• Allow Agent Control (admins only) — off by default. When on, your own team can drive sessions started with this key programmatically, using your organization’s credentials. It changes nothing for visitors. See Allow Agent Control below.

Click Create, and the key appears in your list along with a ready-to-copy iframe snippet.

Editing a key

Each active key in your list has an Edit action. Editing opens the same form pre-filled with the key’s current settings, so you can change its name, app, allowed domains, device options, max session duration, and max concurrent sessions at any time. Changes apply to new sessions started after you save. Retargeting a key to a different app is allowed — handy when a successor app replaces the one you originally embedded, without re-embedding a new key on every page.

The snippet

Each active key shows its embed snippet with a Copy button:

<iframe
  src="https://vibeview.io/embed/ek_live_xxxxxxxxxxxxxxxxxxxxxxxx"
  width="380"
  height="820"
></iframe>

Paste it anywhere you can embed an iframe. Adjust width/height to fit your layout — the default size mirrors a typical phone aspect ratio.

Revoking a key from the Embeds page is permanent: the key stops working immediately, any page using it stops loading, and it can’t be re-enabled. Create a new key if you need one later.

Domain allowlisting

If you set allowed domains on a key, only pages served from those domains can start a session with it — an embed on any other site is refused with “This embed is not available on this site.”

Each entry is either an exact hostname or a wildcard:

• example.com matches only example.com itself.
• docs.example.com matches only that subdomain.
• *.example.com matches every subdomain (docs.example.com, app.example.com, …) but not example.com itself — add both entries to cover a whole site.

You can paste full URLs — the scheme, path, and port are stripped automatically. Entries that are too broad (such as * or *.com) are rejected.

Plan limits. On the Starter plan, every key must list at least one allowed domain, and your organization’s keys can together cover one domain — a base domain plus its subdomains and wildcard count as a single domain, so example.com, docs.example.com, and *.example.com all fit within the limit. On Professional, domains are unlimited, and you may also leave the list empty to allow embedding from anywhere.

Allowlisting checks the referring page’s domain. Some browsers and privacy settings strip the referrer entirely before it reaches VibeView — in that case, a page on an allowed domain can still be refused with “This embed is not available on this site.” because there’s no referrer to check against the list. If you rely on an allowlist and see this happen on a legitimate page, check whether your site (or a browser extension your visitors use) is suppressing the referrer. On Professional you can leave the allowlist empty if referrer suppression is not something you control.

Allow Agent Control

Allow Agent Control is a per-key setting that is off by default. When it’s on, someone in your organization holding a Developer or Admin credential can drive a session started from this key — reading the screen, tapping, typing, scrolling — with the commands described in AI Agent Control. They target the visitor’s existing session by its id: no second session is started and no extra device is used, and the visitor watches every action happen live on the device in front of them. Useful for guiding someone through your demo, or for checking that an embedded demo still works end to end.

Only an organization admin can change the setting. Other members see it on the key’s form but can’t edit it. Keys with it on show an Agent Control badge beside Active in your key list, so you can tell at a glance which demos are drivable. Changes take effect immediately, including on sessions that are already running — switching it back off stops an in-progress agent at its next command.

Revoking a key does the same thing, and so does disabling one: a key that isn’t active can’t be driven, whatever this setting says. Any of the three is an immediate stop, not just a block on starting new sessions.

The setting grants nothing to the people viewing your embed. Driving a session takes an organization credential the embedded page never has, so no visitor and no page you paste the snippet into can do it, and turning the setting on doesn’t change anything a visitor can tap, see, or reach. The confinement described below stays in place either way: what your team can do on an embed session is a restricted set of commands that can’t leave your app — no home button, no deep links.

What visitors experience

Visitors see a Tap to Start button. Once tapped:

• If a device is free, the session connects and your app loads on it automatically.
• If every device is busy, the visitor is queued and sees their position in line; the session starts the moment a device frees up.
• While the session is live, the embed keeps the visitor focused on your app — system navigation that would exit your app (like a home button) is blocked, so visitors stay on the experience you set up for them.
• If the key has a max session duration, the visitor sees a countdown in the final moments before the session ends.
• When the session ends (visitor closes it, or a cap is reached), the visitor sees Demo ended with a Replay? button to start a new session.
• If the visitor closes the page or navigates away, the session ends automatically a moment later.

Usage and limits

Embed sessions are ordinary VibeView sessions from a billing standpoint: the streaming time they use counts toward your plan’s included streaming minutes, and each running embed session counts toward your plan’s concurrent session limit. Once you’re past your included minutes, streaming continues based on your organization’s overage settings (see Billing and Session Defaults).

The max concurrent sessions and max session duration fields on an embed key are optional limits you can set in addition to your plan’s own limits — they cap what that one key can do, on top of whatever your plan already allows. Reaching the concurrent-session limit doesn’t turn visitors away: they wait in a queue and start automatically when a slot frees up.

Page events (postMessage)

The embedded page sends postMessage events to the parent page so you can react to what’s happening in the demo — for example, to show your own “loading” UI or track analytics.

Every event has the same envelope:

{ "source": "vibeview-embed", "version": 1, "type": "session:started", ...extraFields }

type is one of:

Example listener:

window.addEventListener('message', (event) => {
  if (event.data?.source !== 'vibeview-embed') return;
  console.log('VibeView embed event:', event.data.type, event.data);
});

You can also send commands from the parent page into the embed:

iframe.contentWindow.postMessage({ source: 'vibeview-embed-host', type: 'start' }, 'https://vibeview.io');
iframe.contentWindow.postMessage({ source: 'vibeview-embed-host', type: 'stop' }, 'https://vibeview.io');

start begins a session as if the visitor tapped the button themselves (useful if you want your own call-to-action to trigger it). stop ends the current session early.