Install the widget

Requirements

Packages

@mediansh/widget @mediansh/agent-tools

Import the stylesheet once, next to your global CSS. It styles the widget and nothing else on your page.

import "@mediansh/widget/styles.css";

Environment variables

On runtimes without process.env, such as Cloudflare Workers, pass the key in code.

medianIdentity(resolve, { key: env.MEDIAN_KEY });
median(config, { key: env.MEDIAN_KEY });

:::danger Never put MEDIAN_KEY behind NEXT_PUBLIC_, VITE_ or PUBLIC_. Those prefixes ship the value to every visitor, and the key signs identities and tool calls. Only the median_pk_ public key belongs in the browser. :::

Get the key into the browser

Create a key in Settings → API. You get two values.

publicKeyFromMedianKey throws on a bad value:

Mount it

Mount one widget, once, near the root of your app. It sits in the bottom right corner.

Next.js App Router

import { MedianSupport } from "@mediansh/widget";
import { publicKeyFromMedianKey } from "@mediansh/agent-tools";

export function Support() {
  const key = process.env.MEDIAN_KEY;
  if (!key) return null;

  return <MedianSupport apiKey={publicKeyFromMedianKey(key)} />;
}

import "@mediansh/widget/styles.css";
import { Support } from "./support";

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>
        {children}
        <Support />
      </body>
    </html>
  );
}

Support has no "use client", so it is a server component and MEDIAN_KEY stays on the server. A static layout renders at build time, so set MEDIAN_KEY in the build environment too.

Next.js Pages Router

Pages have no server component to derive the key in, so serve it from an identity route.

import { medianIdentity } from "@mediansh/agent-tools";

export const config = { runtime: "edge" };

// Return the signed in user's id, or null. Null answers with the key alone.
export default medianIdentity(async () => null).GET;

Keep runtime: "edge". medianIdentity answers a Request with a Response, which a Pages Router API route only accepts on the edge runtime.

import "@mediansh/widget/styles.css";
import { MedianSupport } from "@mediansh/widget";
import type { AppProps } from "next/app";

export default function App({ Component, pageProps }: AppProps) {
  return (
    <>
      <Component {...pageProps} />
      <MedianSupport identity="/api/median/identity" />
    </>
  );
}

Vite or client-only React

VITE_MEDIAN_PUBLIC_KEY=median_pk_...

import "@mediansh/widget/styles.css";
import { MedianSupport } from "@mediansh/widget";
import { createRoot } from "react-dom/client";
import { App } from "./App";

createRoot(document.getElementById("root")!).render(
  <>
    <App />
    <MedianSupport apiKey={import.meta.env.VITE_MEDIAN_PUBLIC_KEY} />
  </>,
);

Only the public key goes in a VITE_ variable. @mediansh/agent-tools is not needed here.

Without React

import "@mediansh/widget/styles.css";
import { mountMedianSupport } from "@mediansh/widget";

const support = mountMedianSupport({ apiKey: "median_pk_..." });

For Vue, Svelte, Rails or plain HTML with a bundler. It takes the same props as <MedianSupport> and appends its own container to <body>. react and react-dom must still be installed. Call it in the browser, after the page exists. update() and unmount() are on Control from code.

Errors inside the widget never break your page. The widget hides itself and logs the reason to the console. Code you run on your own server, such as publicKeyFromMedianKey, is outside that guard.

Identify users

The identity route is one line:

import { auth } from "@clerk/nextjs/server";
import { medianIdentity } from "@mediansh/agent-tools";

export const { GET } = medianIdentity(async () => (await auth()).userId);

<MedianSupport identity="/api/median/identity" />

The route answers with the public key and the signed user, so apiKey is optional. Pass both and the launcher shows before the route answers. Changes to user sync on their own. A field you stop sending keeps its last value.

Identity covers returning more than an id, signing yourself, and requiring sign in.

Reset on sign out

import { medianSupport } from "@mediansh/widget";

async function signOut() {
  await auth.signOut();
  medianSupport.reset();
}

reset() removes this browser's session and saved email, and signs out the user the widget holds. See Identity.

Content Security Policy

If your site sends a Content Security Policy, add these sources:

connect-src 'self' https://handsome-hare-949.convex.cloud wss://handsome-hare-949.convex.cloud https://cloud.median.sh;
img-src 'self' https://cloud.median.sh https://img.clerk.com https://cdn.discordapp.com https://*.slack-edge.com https://secure.gravatar.com data: blob:;

A blocked picture shows as a letter. Feedback and crash report screenshots redraw your page from the DOM, so an image or font your policy will not fetch comes out blank or in a fallback font. When the agent asks to see the screen, the widget uses the browser's screen sharing. A Permissions-Policy that blocks display-capture makes it redraw the page instead.

Match your colors

The widget reads shadcn-style CSS variables from your page, such as --primary and --card, and uses a light theme without them. See Theming.

Bundle size

The launcher loads with your page. The markdown renderer loads when a visitor points at or focuses the launcher, when the panel opens, or when the page goes idle with an answered thread behind the button. The screenshot code loads the first time a picture is taken. Do not wrap the component in dynamic() or lazy(). That only delays the launcher.

Verify the install

Load a page

The launcher is in the bottom right corner. The console has no errors that mention Median.

Send a message

The widget asks for an email before the first message. It skips this when user.email is set, requireEmail is false, or Ask for an email is off in Agent → Behavior.

Find it in the inbox

Open Inbox in the dashboard. The thread is under Open. If the agent handed it over, it is also under Needs a person.

Troubleshooting

More widget problems are on Support widget. Dashboard problems are on Troubleshooting.