Home / Docs / Browser SDK

Browser SDK

The Floe browser SDK injects the AI overlay into your site or product. One script tag, one function call. No build step, no dependencies. The overlay renders on top of your existing UI inside an isolated container, handling voice AI conversation, Q&A, and guided actions without changing anything about your product.

Installation

Load the SDK, then initialize Floe from your own external script. Both are external and deferred, so Floe() runs after the SDK loads and nothing is inlined — this works under a strict Content-Security-Policy. Add this just before the closing </body> tag:

<!-- 1. Load the SDK (allow https://cdn.floe.so in your script-src) -->
<script src="https://cdn.floe.so/floe-sdk.iife.js" defer></script>
<!-- 2. Initialize from your own script -->
<script src="/floe-init.js" defer></script>

// floe-init.js — served from your own origin
const floe = Floe({
  clientKey: "YOUR_CLIENT_KEY",
  demoMode: true,
  demoSiteId: "YOUR_SITE_ID",
});
floe.ready.then(() => console.log("Floe ready"));
// later: floe.disconnect();

Replace YOUR_CLIENT_KEY and YOUR_SITE_ID with the values from your site settings. Because both scripts are deferred, they execute in order after the page parses — floe-init.js runs once the SDK has loaded and exposed the global Floe() function, which mounts the overlay. Your product loads exactly as it did before. If your CSP allows inline scripts (or you use a per-request nonce), you can call Floe(...) from an inline <script> instead.

Floe() returns an SDK instance with a ready promise and a disconnect() method to tear the overlay down (shown above).

Choosing a mode

One embed runs one mode. Pick it with a single flag:

  • Demo mode (demoMode: true) — the live, voice-led demo agent. Drives your real product and streams it to the visitor. Pair with demoSiteId.
  • Website agent (websiteAgent: true) — the top-of-funnel Ask Floe Q&A launcher with contextual nudges, which hands off in place to a live demo. Pair with demoSiteId so the hand-off can start the demo.

demoMode and websiteAgent are mutually exclusive. If both are set, demoMode wins. With neither set, the SDK mounts the in-product overlay used for onboarding and support.

Use the same two-script embed as above and set websiteAgent: true in your init script:

// floe-init.js — website agent (top-of-funnel Q&A that hands off to a demo)
Floe({ clientKey: "YOUR_CLIENT_KEY", websiteAgent: true, demoSiteId: "YOUR_SITE_ID" });

What the SDK does

Once mounted, the SDK:

  • Renders the overlay inside a Shadow DOM container, fully isolated from your product's CSS. Your styles don't leak in; the overlay's don't leak out.
  • Establishes a voice connection via WebRTC to the Floe voice server, so the visitor can talk to the agent and hear responses in real time. In the website agent the session starts muted — the visitor can type instead.
  • Streams the demo in demo and website-agent mode: the agent drives your product in a server-side browser and the visitor watches it live, as video, inside the overlay.
  • Captures screen context for the in-product agent so it understands what the user is looking at, during active sessions only. See Security.

The SDK does not modify your DOM outside its own overlay container, inject styles into your pages, or intercept your network requests.

Configuration reference

Everything is passed to Floe() as a single config object.

| Option | Type | Description | | --- | --- | --- | | clientKey | string | Required. Your site's client key, from site settings. | | demoMode | boolean | Run the live demo agent. Default false. | | websiteAgent | boolean | Run the top-of-funnel Ask Floe Q&A launcher. Default false. Ignored if demoMode is also set. | | demoSiteId | string | The site to demo. Needed for demo mode and for the website agent's demo hand-off. | | embedMode | "docked" | "fullscreen" | How the demo renders. docked (default) starts as a bottom-docked pill and goes full-bleed once the demo starts; fullscreen opens the demo immediately. Use fullscreen on dedicated demo pages. | | enableAudio | boolean | Enable voice. Default true. | | nudge | object | Bottom-docked nudge shown when minimized: { text, autoShow, autoHideDelay }. | | userInfo | object | Identify a known user: { externalId, email, name, company, designation, metadata }. | | prospectEmail | string | Pre-fill the prospect's work email so the intro form skips the email step. Collect it on your own page first to gate the session behind real intent. | | industry, useCase, companyName, companySize, role | string | Extra context to personalize the opening. | | apiUrl | string | Override the Floe API URL. Defaults to production. | | debug | boolean | Verbose console logging. Default false. |

React usage

Initialize Floe from the script's onLoad signal, and disconnect on unmount:

import Script from "next/script";
import { useEffect, useRef } from "react";

export function FloeDemo() {
  const floeRef = useRef<{ disconnect?: () => void } | null>(null);

  // Tear the overlay down when the component unmounts.
  useEffect(() => () => floeRef.current?.disconnect?.(), []);

  return (
    <Script
      src="https://cdn.floe.so/floe-sdk.iife.js"
      strategy="afterInteractive"
      onLoad={() => {
        if (floeRef.current) return; // guard against double-init
        floeRef.current = (window as any).Floe({
          clientKey: "YOUR_CLIENT_KEY",
          demoMode: true,
          demoSiteId: "YOUR_SITE_ID",
          embedMode: "docked",
        });
      }}
    />
  );
}

onLoad fires once window.Floe is available, so it's the safe place to initialize. The ref guards against a double-init and disconnects the overlay when the component unmounts.

Verifying the installation

  1. Open your product in Chrome.
  2. Open DevTools (F12) → Console.
  3. Type window.Floe and press Enter. You should see a function.
  4. Confirm the overlay (demo pill or Ask Floe launcher) appears on the page.

If window.Floe is undefined, check that the script tag is present in the page source and loaded without error. If it's defined but nothing appears, check that clientKey is correct and matches your site settings.

How it loads

The SDK is served from a global CDN as a single IIFE bundle that attaches window.Floe. The overlay renders inside a Shadow DOM container appended to the document body, so your stylesheets and the overlay's never conflict. This is why the SDK works on any product without styling issues.

Framework compatibility

The SDK works with any web framework or none — React, Vue, Angular, Svelte, plain HTML. Because it's a script tag plus a function call, and renders into Shadow DOM, it sits outside your application's component tree entirely.

FAQ

Does the SDK work on single-page applications? Yes. It detects route changes automatically and re-scopes the agent's context — including the website agent's page-scoped nudges — as the user navigates within your SPA.

Will the SDK slow down my product? No. It loads asynchronously and does not block rendering. On pages where the overlay is never opened, the impact is a single small network request.

Can I run demo and website-agent mode from one embed? No — one embed runs one mode. demoMode and websiteAgent are mutually exclusive (demoMode wins if both are set). Use the mode that fits the surface.

Can I use different keys in development and production? Yes. Use your development client key and site ID in dev, production values in prod. The dashboard shows each site's sessions separately.

What if I need to remove the SDK later? Call disconnect() on the instance returned by Floe() — that unmounts the overlay and ends any live session. Removing the script tag alone does not tear down an overlay that has already mounted. disconnect() leaves your product's DOM untouched; the one thing it doesn't clear is the first-party anonymous ID the website agent keeps in local storage, which resets when the visitor clears site data.