Next.js (App Router)

The agent runs entirely in the browser, so we use Next’s <Script> component with strategy="afterInteractive" to load it after first paint.

1. Add the script in your root layout

import Script from 'next/script';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>{children}</body>
      <Script
        src="https://cdn.wholisphere.ai/embed.js"
        data-key={process.env.NEXT_PUBLIC_WHOLISPHERE_KEY}
        data-position="bottom-right"
        data-wholisphere
        strategy="afterInteractive"
      />
    </html>
  );
}

2. Set the env var

NEXT_PUBLIC_WHOLISPHERE_KEY=org_yourkey

The NEXT_PUBLIC_ prefix is required so the value is inlined into the client bundle. Wholisphere keys are scoped per-org and IP-allowlisted on Platform plans, so they’re safe to expose.

3. Trigger cache invalidation on deploy

Wire the GitHub Action so the build-time cache flushes on every Vercel deploy:

- name: Invalidate Wholisphere cache
  uses: wholisphere/cache-invalidate-action@v1
  with:
    api-key: ${{ secrets.WHOLISPHERE_API_KEY }}
    urls: "https://${{ vars.PROD_URL }}/*"
    reason: "vercel deploy ${{ github.sha }}"

That’s it. Open any page on your site; the FAB shows up in the bottom-right.

App Router caveats

The agent reads document.title and <main> content. If you’re using next/router for client transitions, the agent re-runs its outline pass on every route change automatically.
Streaming responses + Suspense are fully supported; the agent waits for the body to settle before extracting content.