One next/script tag. It loads after your page is interactive, renders in a Shadow DOM so it doesn't touch your styles, and works with the App Router and the Pages Router.
In the dashboard create a project and copy its key from Install & settings. Add your production domain and your preview domains to Allowed origins, for example https://*.vercel.app. Local development (http://localhost:3000) needs its own line if you want to test there.
App Router, in app/layout.tsx:
import Script from "next/script";
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<html lang="en">
<body>
{children}
<Script src="https://uups.dev/widget.js" data-project-key="pk_…" strategy="afterInteractive" />
</body>
</html>
);
}Pages Router, in pages/_app.tsx:
import Script from "next/script";
import type { AppProps } from "next/app";
export default function App({ Component, pageProps }: AppProps) {
return (
<>
<Component {...pageProps} />
<Script src="https://uups.dev/widget.js" data-project-key="pk_…" strategy="afterInteractive" />
</>
);
}Using Cursor or Claude Code? The Install with AI prompt in the project settings does the same.
Sign the user id on the server with the project's identity secret, so reports are marked verified and nobody can send feedback in someone else's name. Put the secret in UUPS_IDENTITY_SECRET; never expose it to the browser.
// app/feedback-user.tsx
"use client";
import { useEffect } from "react";
type Reporter = { id: string; email?: string; name?: string; signature: string };
export function FeedbackUser({ user }: { user: Reporter | null }) {
useEffect(() => {
const w = window as any;
w.FeedbackWidget = w.FeedbackWidget || { q: [] };
if (w.FeedbackWidget.q) w.FeedbackWidget.q.push(["identify", user]);
else w.FeedbackWidget.identify(user);
}, [user]);
return null;
}// app/layout.tsx (server component)
import { createHmac } from "node:crypto";
import Script from "next/script";
import { FeedbackUser } from "./feedback-user";
export default async function RootLayout({ children }: { children: React.ReactNode }) {
const user = await getCurrentUser(); // your auth
const reporter = user && {
id: user.id,
email: user.email,
name: user.name,
signature: createHmac("sha256", process.env.UUPS_IDENTITY_SECRET!).update(user.id).digest("hex"),
};
return (
<html lang="en">
<body>
{children}
<Script src="https://uups.dev/widget.js" data-project-key="pk_…" strategy="afterInteractive" />
<FeedbackUser user={reporter} />
</body>
</html>
);
}Calls made before the script has loaded are queued and run once it's ready.
If your app sends a CSP header, allow the widget script, its API and the direct upload of recordings:
script-src ... https://uups.dev; connect-src ... https://uups.dev https://*.r2.cloudflarestorage.com;
Screen recording also needs the browser's screen-capture permission. If you send a Permissions-Policy header, don't set display-capture=().
Turn off Show floating button in the project settings and open the widget from your help menu:
<button onClick={() => (window as any).FeedbackWidget?.open({ type: "bug" })}>Report a bug</button>widget.js), and that "Show floating button" is on in the project settings.