WebmasterID Docs

WebmasterID in Next.js

There are two ways to add WebmasterID to a Next.js app. The next/script method is universally supported and recommended. An optional component package is a convenience if it is available in your project.

Method 1 — next/script (recommended)

Use the built-in next/script component. In the App Router, add it once to app/layout.tsx:

import Script from "next/script";

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>
        {children}
        <Script
          id="webmasterid-tracker"
          src="https://webmasterid.com/tracker.iife.min.js"
          strategy="afterInteractive"
          data-wmid="wm_xxxxxxxxxxxxxxxx"
          data-endpoint="https://webmasterid-ingest-api.vercel.app/api/events"
        />
      </body>
    </html>
  );
}

In the Pages Router, add the same <Script> to a custom pages/_app.tsx. strategy="afterInteractive" keeps it off the critical path. Adding it in the layout/_app means it loads once per route automatically.

Method 2 — component package (optional, if available)

If the @webmasterid/sdk-next package is available in your project, it offers a component wrapper around the same tracker:

import { WebmasterID } from "@webmasterid/sdk-next";

<WebmasterID
  siteId="wm_xxxxxxxxxxxxxxxx"
  endpoint="https://webmasterid-ingest-api.vercel.app/api/events"
/>

This is the preferred integration if your project supports the package. If the package is not available, use Method 1 — it works in every Next.js version and is the method this site’s ecosystem relies on. Do not assume package-specific APIs beyond siteId and endpoint unless your installed version documents them.

Consent-safe in Next.js

For GDPR / ePrivacy, render the script only after analytics consent — for example, return it from a client consent provider once the analytics category is granted, instead of placing it unconditionally in the layout. See Privacy & GDPR for the consent-gated pattern.

Troubleshooting

  • Loaded twice: ensure the Script is in the layout/_app once, not inside a component that renders on every page.
  • Module not found: the optional package is not installed — use Method 1.
  • No events in production: confirm consent gating actually grants, and the endpoint is allowed by your CSP.

FAQ

Which Next.js method should I use?

next/script is universally supported and works in any Next.js version. The package component is an optional convenience if it is available in your project.

App Router or Pages Router?

Both work. App Router: add the Script to the root layout. Pages Router: add it to _app. Add it once so it loads on every route exactly once.

How do I keep it consent-safe in Next.js?

Render or inject the script only after analytics consent — e.g. from a consent provider effect — rather than unconditionally in the layout.

Related

Installation overview · HTML installation · Privacy & GDPR · What is WebmasterID?