Next.js

Add pagent as a plain <script> tag in the document <head>, with data-await-hydration="true". pagent recognizes Next.js hydration in both routers, and follows client-side navigation on its own.

Don’t use next/script, not even with strategy="beforeInteractive". Next.js adds those scripts with its own JavaScript, so they don’t block the page from showing. The page can show before pagent runs, and visitors see the original flash.

App Router

Add the tag to the <head> of your root layout:

app/layout.tsx

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <head>
        {/* eslint-disable-next-line @next/next/no-sync-scripts -- pagent must run before the page shows */}
        <script
          src="https://cdn.pagent.ai/js/sdk.js"
          data-client-key="YOUR_CLIENT_KEY"
          data-await-hydration="true"
        />
      </head>
      <body>{children}</body>
    </html>
  );
}

Pages Router

Add the tag to the <Head> of your custom document:

pages/_document.tsx

import { Html, Head, Main, NextScript } from "next/document";

export default function Document() {
  return (
    <Html lang="en">
      <Head>
        {/* eslint-disable-next-line @next/next/no-sync-scripts -- pagent must run before the page shows */}
        <script
          src="https://cdn.pagent.ai/js/sdk.js"
          data-client-key="YOUR_CLIENT_KEY"
          data-await-hydration="true"
        />
      </Head>
      <body>
        <Main />
        <NextScript />
      </body>
    </Html>
  );
}

Recommendations

Keep data-await-hydration="true". Without it, hydration can undo a variant right after pagent applied it.
Slow pages: if your pages hydrate slowly, raise the wait with data-hydration-timeout="800". Try it first on a preview link with ?pagent_hydration_timeout=800.
Streaming and Suspense: pagent waits for Suspense boundaries that have already arrived, not for ones that are still streaming. Test variants on content inside late Suspense boundaries with a preview link.
Navigation: route changes with <Link> and router.push are tracked automatically. Don’t call navigate yourself, or the page view counts twice.

See Frameworks for the shared rules and the Content Security Policy.

Check it worked

Deploy, then open your site in a private browser window.
Back in pagent, click Check connection in the install step.
Open a test’s preview link and check that the variant shows and stays after the page has finished loading.

Get started

Shop platforms

Frameworks

Other ways

Cookie banners

App Router

Pages Router

Recommendations

Check it worked

​App Router

​Pages Router

​Recommendations

​Check it worked

App Router

Pages Router

Recommendations

Check it worked