3 Min. Lesedauer

Next.js Integration

Add Zenovay analytics to your Next.js application using the built-in Script component for optimal loading.

App Router (Next.js 13+)

Add the Script component to your root layout:

app/layout.tsxTSX

import Script from 'next/script';

export default function RootLayout({
children,
}: {
children: React.ReactNode;
}) {
return (
  <html lang="en">
    <head>
      <Script
        src="https://api.zenovay.com/z.js"
        data-tracking-code="YOUR_TRACKING_CODE"
        strategy="afterInteractive"
      />
    </head>
    <body>{children}</body>
  </html>
);
}

Replace YOUR_TRACKING_CODE with your tracking code from the Zenovay Dashboard.

Pages Router (Legacy)

For the Pages Router, add the script to _app.tsx:

pages/_app.tsxTSX

import type { AppProps } from 'next/app';
import Script from 'next/script';

export default function App({ Component, pageProps }: AppProps) {
return (
  <>
    <Script
      src="https://api.zenovay.com/z.js"
      data-tracking-code="YOUR_TRACKING_CODE"
      strategy="afterInteractive"
    />
    <Component {...pageProps} />
  </>
);
}

Script Strategies

Next.js provides different loading strategies:

Strategy	Description	Use Case
`afterInteractive`	Loads after page becomes interactive	Recommended for analytics
`lazyOnload`	Loads during browser idle time	Non-critical scripts
`beforeInteractive`	Loads before page hydration	Critical scripts only

Recommended StrategyTSX

<Script
src="https://api.zenovay.com/z.js"
data-tracking-code="YOUR_TRACKING_CODE"
strategy="afterInteractive"
/>

Environment Variables

Use environment variables for the tracking code:

app/layout.tsxTSX

import Script from 'next/script';

export default function RootLayout({
children,
}: {
children: React.ReactNode;
}) {
const trackingCode = process.env.NEXT_PUBLIC_ZENOVAY_ID;

return (
  <html lang="en">
    <head>
      {trackingCode && (
        <Script
          src="https://api.zenovay.com/z.js"
          data-tracking-code={trackingCode}
          strategy="afterInteractive"
        />
      )}
    </head>
    <body>{children}</body>
  </html>
);
}

.env.localBash

NEXT_PUBLIC_ZENOVAY_ID=ZV_ABC123XYZ

First-Party Tracking (Bypass Ad Blockers)

For better accuracy, use first-party tracking:

app/layout.tsxTSX

import Script from 'next/script';

export default function RootLayout({
children,
}: {
children: React.ReactNode;
}) {
return (
  <html lang="en">
    <head>
      <Script
        src="https://metrics.yourdomain.com/z.js"
        data-tracking-code="YOUR_TRACKING_CODE"
        strategy="afterInteractive"
      />
    </head>
    <body>{children}</body>
  </html>
);
}

First-party tracking requires a CNAME DNS record. See First-Party Tracking Guide for setup instructions.

Static Export (Cloudflare Pages)

For static exports, the Script component works the same way:

next.config.jsJavaScript

/** @type {import('next').NextConfig} */
const nextConfig = {
output: 'export',
// ... other config
};

module.exports = nextConfig;

The tracking script will be embedded in the generated HTML pages.

Server Components

The tracking script works automatically with React Server Components. No special configuration needed.

Middleware & Edge Runtime

For apps using Edge runtime, the client-side Script component handles tracking as usual. Server-side analytics can use the API integration.

Verification

After installation:

Build and deploy your Next.js app
Open DevTools → Network tab
Look for requests to api.zenovay.com
Check your Zenovay Dashboard for incoming data

Troubleshooting

Script not loading in development?

The script loads on page navigation, not initial load in dev mode
Build and preview (npm run build && npm start) to test properly

Duplicate script tags?

Only add the Script once in your root layout
Don't add it in individual pages

Hydration mismatch warnings?

Use strategy="afterInteractive" to avoid SSR issues
Ensure script is in the <head> section

Content Security Policy issues?

Add api.zenovay.com to your CSP script-src directive
For first-party: add your CNAME subdomain