Saltar al contenido principal

Next.js

Instale el snippet de seguimiento de Selgeo en una aplicación Next.js usando el componente nativo next/script del framework. Esta guía cubre tanto el App Router (app/layout.tsx) como el Pages Router (pages/_app.tsx).

Versión de API: v1

Si no usa Next.js, consulte la guía HTML / script plano, la guía de React (Vite) o la guía de WordPress.

¿Por qué next/script?​

Una etiqueta <script> simple dentro de un componente React no se comporta como en HTML plano — Next.js empaqueta JavaScript por ruta e hidrata las páginas de forma incremental. El componente oficial next/script:

  • Carga el snippet exactamente una vez a través de las navegaciones del lado del cliente (sin ejecución duplicada).
  • Respeta una strategy de carga que usted controla (usamos afterInteractive).
  • Funciona bien con el SSR en streaming de Next.js y el Partial Prerendering.

Usamos strategy="afterInteractive" en lugar de lazyOnload para que el snippet esté listo antes de procesar el primer parámetro ?ref=. La precisión de la atribución prevalece sobre una ganancia marginal de Lighthouse — lazyOnload arriesga perder un clic temprano que convierte inmediatamente.

Instalación — App Router (app/layout.tsx)​

Para proyectos en Next.js 13+ que usan el directorio app/.

Paso 1: Agregue el snippet al layout raíz​

Abra app/layout.tsx y agregue el import de Script y el elemento JSX:

import Script from 'next/script';

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>
        {children}
        <Script
          async
          src="https://cdn.selgeo.com/v1/selgeo.js"
          data-merchant="pk_test_YOUR_KEY"
          strategy="afterInteractive"
        />
      </body>
    </html>
  );
}

Reemplace pk_test_YOUR_KEY con su clave pública de API desde Ajustes > Claves de API en el panel de Selgeo.

Página Settings &gt; API Keys en el panel de Selgeo con el campo de la clave pública resaltado

Paso 2: Guardar y ejecutar​

pnpm dev
# o
npm run dev

Abra su sitio en el navegador. El snippet ahora se carga en cada página renderizada por el App Router.

Instalación — Pages Router (pages/_app.tsx)​

Para proyectos en el directorio legado pages/.

Paso 1: Agregue el snippet al componente App personalizado​

Abra (o cree) pages/_app.tsx:

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

export default function App({ Component, pageProps }: AppProps) {
  return (
    <>
      <Component {...pageProps} />
      <Script
        async
        src="https://cdn.selgeo.com/v1/selgeo.js"
        data-merchant="pk_test_YOUR_KEY"
        strategy="afterInteractive"
      />
    </>
  );
}

Paso 2: Reinicie el servidor de desarrollo​

pnpm dev

Los proyectos con Pages Router deben reiniciar el servidor de desarrollo cuando se crea _app.tsx por primera vez. Las ediciones posteriores se recargan en caliente normalmente.

La tarjeta Tracking Snippet en Settings mostrando la pestaña Next.js con los bloques de import y componente listos para copiar

Atributos requeridos y opcionales​

AtributoRequeridoDescripción
srcSíURL del CDN. Siempre https://cdn.selgeo.com/v1/selgeo.js.
data-merchantSíSu clave pública de API (pk_test_* o pk_live_*).
asyncSíCarga asíncrona; no bloquea la hidratación.
strategySíUse "afterInteractive". No cambie a "lazyOnload" — los clics tempranos de referido podrían perderse.
data-debugNoHabilita el registro verboso en la consola. Eliminar antes de salir en vivo.
data-api-urlNoSobrescribe el endpoint de la API. Solo presente en espacios de trabajo de staging / desarrollo — el panel de Selgeo lo inyecta automáticamente cuando es necesario.

Verificar la instalación​

  1. Compile y ejecute su proyecto (pnpm dev o pnpm build && pnpm start).
  2. Cree un enlace de seguimiento en el panel de Selgeo en Programas > Enlaces de seguimiento.
  3. Visite su sitio con el enlace de seguimiento, por ejemplo: 
    https://su-sitio.com/?ref=SU_REF_DE_PRUEBA
  4. Abra las Herramientas para desarrolladores (F12) y revise la Consola. Con data-debug agregado temporalmente, debería ver: 
    [selgeo] ref detected SU_REF_DE_PRUEBA
    [selgeo] click_id stored xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
  5. En la consola del navegador, ejecute: 
    __selgeo.getClickId()
    Esto debería retornar un string UUID. null significa que el snippet no detectó un parámetro ?ref=.
  6. Abra el panel de Selgeo. El clic debería aparecer en Analytics en pocos segundos.

Vista de Analytics de Selgeo mostrando la actividad reciente de clics y los principales partners

Solución de problemas​

El snippet no carga​

  • Confirme que app/layout.tsx (App Router) o pages/_app.tsx (Pages Router) realmente contienen el bloque <Script> — la duplicación accidental en un archivo de página individual es el error más común.
  • Verifique que src sea exactamente https://cdn.selgeo.com/v1/selgeo.js. Un error tipográfico hace que el script falle silenciosamente.
  • Abra la pestaña Network y filtre por selgeo.js. Una entrada en rojo con estado 0 o un error CORS normalmente indica una violación de CSP — vea más abajo.
  • Si ejecuta con exportación estática (output: 'export'), confirme que el snippet esté incluido en el HTML exportado. next/script con strategy="afterInteractive" se preserva en la exportación estática.

El clic no se rastrea​

  • El visitante debe llegar con ?ref=… en la carga inicial de la página. Una vez que el snippet captura el clic, la URL se reescribe y el parámetro deja de aparecer. Recargue la página con un enlace de seguimiento nuevo si ya consumió el actual.
  • Confirme que data-merchant contenga una clave pk_test_* o pk_live_* válida. Un valor truncado o con espacios al inicio hará que el snippet no haga nada silenciosamente.
  • Si usa React Strict Mode, asegúrese de que el snippet esté en app/layout.tsx o pages/_app.tsx, no dentro de un efecto que pueda ejecutarse dos veces. next/script ya deduplica correctamente.
  • Verifique el modo del panel de Selgeo (test vs. live). Una clave pk_live_* en un enlace de seguimiento emitido en modo test no registrará el clic.

Bloqueo por CSP​

Si su proyecto Next.js establece una cabecera Content-Security-Policy (vía next.config.js headers(), middleware o una entrada en vercel.json), permita los orígenes de Selgeo:

script-src 'self' https://cdn.selgeo.com;
connect-src 'self' https://api.selgeo.com;

Para espacios de trabajo de staging / desarrollo donde data-api-url apunta a otro lugar, agregue también ese origen a connect-src. Si no puede relajar la CSP, considere enrutar el snippet a través de su propio origen (avanzado, fuera del alcance de esta guía).

Próximos pasos​