Search Atlas Help Center

🚀 Installing OTTO Pixel on Next.js Without Errors

Open in
View as Markdown Open in ChatGPT Open in Claude
Camilo Aponte

Camilo Aponte

Last updated on Sep 30, 2026

Overview

OTTO supports two installation methods: direct pixel installation and Google Tag Manager (GTM) deployment. This article explains how to implement either method in a Next.js project so you do not encounter React hydration errors or performance issues.

Why Hydration Errors Happen

React hydration errors occur when the HTML rendered on the server does not match what React expects to render on the client. The OTTO pixel is a client-side script. If it runs during server-side rendering (SSR), it can reference browser-only globals such as window or document that do not exist in the Node.js environment, causing a mismatch. The fix is to ensure the pixel only ever runs in the browser, after the component has mounted.

Supported OTTO Integration Methods

  • Direct pixel installation — Embed the OTTO pixel script directly in your Next.js project using a client-side-safe approach.
  • Google Tag Manager — Deploy the OTTO pixel through a GTM container tag, which fires only in the browser environment.

If you are unsure which method fits your setup, contact the Search Atlas support team and they will help you choose the right approach.

How to Find Your OTTO Pixel Code

Log in to your Search Atlas account and locate your site-specific OTTO pixel snippet inside your project settings. If you are unsure where to find your pixel code, contact our support team and they will guide you to the correct screen.

Method 1: Direct Pixel Installation Using useEffect

The safest way to load the OTTO pixel directly in a Next.js project is to use the useEffect hook, which only runs in the browser after the component has mounted. This prevents any server-side execution.

  1. Create or open a layout or page component where you want the pixel to load globally (for example, _app.js in the Pages Router, or your root layout.js in the App Router).

  2. Import useEffect from React at the top of the file: import { useEffect } from 'react';

  3. Inside the component, add a useEffect block that creates a script element and appends it to the document body:

    • Create the script tag: const script = document.createElement('script');
    • Set the src to your OTTO pixel URL: script.src = 'YOUR_OTTO_PIXEL_URL';
    • Set it to load asynchronously: script.async = true;
    • Append it: document.body.appendChild(script);

  4. Make sure the dependency array is empty ([]) so it runs only once after the initial render.

  5. Save the file, then open your browser's developer console and confirm no hydration errors appear and the pixel fires as expected.

Method 1 Alternative: Using next/script

Next.js provides a built-in Script component from next/script that handles client-safe loading automatically.

  1. Import the Script component: import Script from 'next/script';
  2. Add the Script component to your layout or page, setting the strategy prop to afterInteractive or lazyOnload. Both strategies ensure the script only runs in the browser after the page is interactive: <Script src="YOUR\_OTTO\_PIXEL\_URL" strategy="afterInteractive" />
  3. Verify in the browser developer console that no hydration errors appear and that the pixel fires correctly.

Method 2: Installing via Google Tag Manager

If you prefer to manage the OTTO pixel through GTM, the key is to load the GTM container itself in a browser-safe way within Next.js.

  1. Retrieve your GTM container ID (formatted as GTM-XXXXXXX) from your Google Tag Manager account.
  2. In your Next.js project, add the GTM snippet using the next/script Script component with strategy="afterInteractive" so it only runs in the browser.
  3. Place the GTM <noscript> iframe fallback inside the <body> tag of your layout.
  4. Inside GTM, configure your OTTO pixel as a Custom HTML tag set to fire on All Pages (or your preferred trigger). GTM tags fire in the browser by default, so no additional SSR guard is needed on the tag itself.
  5. Publish your GTM container, then verify in the browser developer console and GTM Preview mode that the OTTO pixel fires without hydration errors.

General Best Practices

  • Always load the OTTO pixel in a way that guarantees it only executes in the browser, not during server-side rendering.
  • If using GTM, ensure the GTM container tag is also loaded in a browser-safe manner within your Next.js project.
  • After installation, verify in your browser's developer console that no hydration errors appear and that the pixel fires as expected.

Getting Help With Your Next.js Integration

Because Next.js projects vary in structure (Pages Router vs. App Router, SSR vs. static export), the correct way to integrate the OTTO pixel depends on your specific setup. If you need tailored guidance, please reach out to our support team. Share details about your Next.js version and rendering approach so the team can advise you on the right integration method. If we were unable to resolve your issue, please contact our support team and we will be happy to help.