Next.js

AdXensor works with both the App Router (Next.js 13+) and the Pages Router. Use the npm package for full TypeScript support and SSR compatibility.

Installation

npm install @adxensor/publisher-sdk

App Router (Next.js 13+)

Create an AdSlot component

The SDK manipulates the DOM, so it must run on the client. Create a reusable AdSlot component:

// components/AdSlot.tsx
'use client';

import { useEffect, useRef } from 'react';
import { AdXensor } from '@adxensor/publisher-sdk';

interface AdSlotProps {
  slot: string;
  format?: string;
  className?: string;
}

export function AdSlot({ slot, format = 'auto', className }: AdSlotProps) {
  const ref = useRef<HTMLElement>(null);

  useEffect(() => {
    if (!ref.current) return;

    const adx = AdXensor.getInstance({
      siteId: process.env.NEXT_PUBLIC_ADXENSOR_SITE_ID!,
    });

    adx.init();
    adx.fill(ref.current, { format: format as any });
  }, [slot, format]);

  return (
    <ins
      ref={ref}
      className={`adxensor${className ? ` ${className}` : ''}`}
      style={{ display: 'block' }}
      data-ad-slot={slot}
      data-ad-format={format}
    />
  );
}

Add your Site ID to the environment

# .env.local
NEXT_PUBLIC_ADXENSOR_SITE_ID=pub-XXXXXXXX

Use the component in any Server or Client component

// app/page.tsx  (Server Component — AdSlot itself is 'use client')
import { AdSlot } from '@/components/AdSlot';

export default function HomePage() {
  return (
    <main>
      <h1>Welcome</h1>

      {/* Leaderboard at the top */}
      <AdSlot slot="header-banner" format="728x90" />

      <article>…your content…</article>

      {/* In-content rectangle */}
      <AdSlot slot="in-content" format="300x250" />
    </main>
  );
}

Pages Router (Next.js 12 and below)

Create the AdSlot component

Same component as above — the 'use client' directive is ignored in the Pages Router and has no effect.

Initialize once in _app.tsx

// pages/_app.tsx
import { useEffect } from 'react';
import type { AppProps } from 'next/app';
import { AdXensor } from '@adxensor/publisher-sdk';
import { useRouter } from 'next/router';

export default function App({ Component, pageProps }: AppProps) {
  const router = useRouter();

  useEffect(() => {
    const adx = AdXensor.getInstance({
      siteId: process.env.NEXT_PUBLIC_ADXENSOR_SITE_ID!,
    });

    adx.init();

    // Re-fill slots after client-side navigation
    const handleRouteChange = () => {
      AdXensor.reset();
      AdXensor.getInstance({
        siteId: process.env.NEXT_PUBLIC_ADXENSOR_SITE_ID!,
      }).init();
    };

    router.events.on('routeChangeComplete', handleRouteChange);
    return () => router.events.off('routeChangeComplete', handleRouteChange);
  }, [router.events]);

  return <Component {...pageProps} />;
}

Place slots on any page

// pages/index.tsx
import { AdSlot } from '@/components/AdSlot';

export default function Home() {
  return (
    <main>
      <AdSlot slot="header-banner" format="728x90" />
      <p>Your content here.</p>
      <AdSlot slot="footer-banner" format="320x50" />
    </main>
  );
}

SPA route changes (App Router)

The App Router handles client-side navigation automatically. If you notice ads not refreshing after navigation, reset the singleton on route changes using the usePathname hook:

// components/AdXensorProvider.tsx
'use client';

import { useEffect } from 'react';
import { usePathname } from 'next/navigation';
import { AdXensor } from '@adxensor/publisher-sdk';

export function AdXensorProvider({ children }: { children: React.ReactNode }) {
  const pathname = usePathname();

  useEffect(() => {
    AdXensor.reset();
    AdXensor.getInstance({
      siteId: process.env.NEXT_PUBLIC_ADXENSOR_SITE_ID!,
    }).init();
  }, [pathname]);

  return <>{children}</>;
}

Mount it in your root layout.tsx:

// app/layout.tsx
import { AdXensorProvider } from '@/components/AdXensorProvider';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html>
      <body>
        <AdXensorProvider>
          {children}
        </AdXensorProvider>
      </body>
    </html>
  );
}

TypeScript types

import type { AdFormat } from '@adxensor/publisher-sdk';

const format: AdFormat = '300x250';

Environment variables

Variable	Description
`NEXT_PUBLIC_ADXENSOR_SITE_ID`	Your Site ID (`pub-XXXXXXXX`)

Because it is prefixed with NEXT_PUBLIC_, it is exposed to the browser. This is intentional — the Site ID is not a secret.

Full configuration options

AdXensor.getInstance({
  siteId:   'pub-XXXXXXXX', // required
  apiKey:   'YOUR_KEY',     // optional — for authenticated publishers
  lazyLoad: true,           // default: true
  debug:    false,          // enables console logs
});

Troubleshooting

Symptom	Solution
Slots remain blank	Check that `NEXT_PUBLIC_ADXENSOR_SITE_ID` is set and the site is approved in the dashboard
Duplicate ads on navigation	Use `AdXensor.reset()` before re-initializing on route change
`window is not defined` SSR error	Ensure the component has `'use client'` and uses `useEffect` — never call SDK methods at module level

→ Full troubleshooting guide

Getting Started

How AdXensor Works

Integration Guides

Reference

Support

Installation

App Router (Next.js 13+)

Pages Router (Next.js 12 and below)

SPA route changes (App Router)

TypeScript types

Environment variables

Full configuration options

Troubleshooting

​Installation

​App Router (Next.js 13+)

​Pages Router (Next.js 12 and below)

​SPA route changes (App Router)

​TypeScript types

​Environment variables

​Full configuration options

​Troubleshooting

Installation

App Router (Next.js 13+)

Pages Router (Next.js 12 and below)

SPA route changes (App Router)

TypeScript types

Environment variables

Full configuration options

Troubleshooting