# Integración con Next.js y SPA React

Instale FlowConsent en una app Next.js (App Router o Pages Router) y active el Modo SPA para comprobar el consentimiento en cada navegación del cliente.

> Canonical: https://www.flowconsent.com/es/doc/nextjs-integration
> Last updated: 2026-05-31
El banner de FlowConsent es un único `<script>` autónomo: el mismo fragmento funciona en Next.js, Nuxt, SvelteKit y cualquier app de código personalizado, igual que en Webflow, Framer o WordPress. Hay **un paso adicional** para las apps de página única: activar el **Modo SPA** para que el consentimiento se vuelva a comprobar en las navegaciones del lado del cliente.

## Por qué una SPA necesita un paso más

En un sitio multipágina clásico, cada navegación recarga la página por completo, por lo que el banner se vuelve a ejecutar y vuelve a bloquear los scripts de seguimiento en cada página. Una Single Page Application (Next.js, React, Vue…) navega con `history.pushState`, **sin recargar la página**, así que sin el Modo SPA, los scripts inyectados tras la primera página no se volverían a bloquear en las rutas siguientes.

El Modo SPA engancha `pushState`, `replaceState` y `popstate` para volver a verificar el consentimiento en cada navegación del lado del cliente.

## Paso 1: Añadir el script

El banner ya incluye los valores predeterminados de Google Consent Mode v2 dentro del bundle, por lo que el fragmento se mantiene mínimo: basta con cargar el script lo antes posible.

### App Router (`app/layout.tsx`)

```tsx
import Script from 'next/script'

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        {children}
        {/* FlowConsent CMP */}
        <Script
          src="https://SU-WORKSPACE.consent.flowconsent.com/cookie-manager.js?code=SU_CODIGO_DE_LICENCIA"
          strategy="beforeInteractive"
        />
      </body>
    </html>
  )
}
```

`strategy="beforeInteractive"` hace que Next.js cargue el script antes de la hidratación, de modo que el bloqueo previo esté activo antes de que se dispare cualquier seguimiento.

### Pages Router (`pages/_document.tsx`)

```tsx
import { Html, Head, Main, NextScript } from 'next/document'

export default function Document() {
  return (
    <Html>
      <Head>
        {/* FlowConsent CMP: colócalo primero en <Head> */}
        <script src="https://SU-WORKSPACE.consent.flowconsent.com/cookie-manager.js?code=SU_CODIGO_DE_LICENCIA" />
      </Head>
      <body>
        <Main />
        <NextScript />
      </body>
    </Html>
  )
}
```

Encontrará su fragmento exacto (con su URL de despliegue y su código de licencia) en **Builder → Despliegue → Integración**, donde una pestaña **Next.js** genera este código en su lugar.

## Paso 2: Activar el Modo SPA

En el Builder, abra la pestaña **Ajustes** y active el **Modo SPA**. Vuelva a desplegar su banner para aplicar el cambio.

Con el Modo SPA activado, FlowConsent hará lo siguiente:

- Interceptar `history.pushState` y `history.replaceState`
- Escuchar los eventos `popstate`
- Volver a bloquear los scripts de seguimiento no cubiertos en cada navegación
- Emitir un evento `flowconsent:navigation` al que puede suscribirse

## Paso 3: Deje que FlowConsent gestione los scripts de seguimiento

**No** cargue los scripts de seguimiento (Google Analytics, Meta Pixel…) con `next/script`. En su lugar, declárelos en **Builder → Services** y deje que FlowConsent los inyecte una vez otorgado el consentimiento.

```tsx
// Evitar: script de seguimiento fuera del control de FlowConsent
<Script src="https://www.googletagmanager.com/gtag/js?id=G-XXXXX" strategy="afterInteractive" />

// Preferir: configura Google Analytics en Builder → Services
```

## Opcional: Reaccionar al consentimiento en su app

FlowConsent emite eventos a los que puede suscribirse:

```tsx
import { useEffect } from 'react'

export function useConsentListener() {
  useEffect(() => {
    const onConsent = (event) => {
      const { preferences } = event.detail
      if (preferences?.analytics) {
        // consentimiento de analytics otorgado: inicializa tu propio analytics
      }
    }
    window.addEventListener('flowconsent:consent', onConsent)
    return () => window.removeEventListener('flowconsent:consent', onConsent)
  }, [])
}
```

## Lista de verificación

- [ ] El script está en `app/layout.tsx` (App Router) o `pages/_document.tsx` (Pages Router)
- [ ] El App Router usa `strategy="beforeInteractive"`
- [ ] El **Modo SPA** está activado en el Builder y el banner se ha vuelto a desplegar
- [ ] Sin `next/script` para los scripts de seguimiento: están configurados en Services
- [ ] El banner aparece en la primera carga
- [ ] Sin peticiones de seguimiento en la pestaña Red antes de hacer clic en **Aceptar**
- [ ] El consentimiento persiste a través de las navegaciones del lado del cliente

## Hacerlo desde un agente de IA (MCP)

FlowConsent cuenta con un servidor MCP oficial, `https://mcp.flowconsent.com`, utilizable desde Claude, ChatGPT o cualquier cliente MCP. La conexión se hace por OAuth 2.0 con la cuenta de FlowConsent, sin clave de API. El agente obtiene el fragmento y las instrucciones de colocación (herramientas `get_banner_snippet` y `get_setup_instructions`), verifica la instalación con un escaneo real (`verify_consent_compliance`) y puede programar una vigilancia periódica (`monitor_compliance`). No modifica el sitio Next.js: pegar el fragmento sigue siendo un paso manual.

Ejemplo de petición: «Dame el fragmento de código de mi banner para mi sitio Next.js y comprueba que está bien instalado en https://misitio.es».

Ver la [guía del servidor MCP](/es/doc/mcp-server) y la página [FlowConsent MCP](/es/mcp).