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.

Tarjeta Settings &gt; API Keys en el panel de Selgeo con las claves publicables de los modos Test y Live

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. Consiga un enlace de referido. Los enlaces de seguimiento los crean los socios en el portal de socios (en Enlaces), no en el panel del comerciante. Para una prueba rápida por su cuenta, inicie sesión en el portal de socios como socio de prueba y cree uno, o pida su enlace a un socio existente.
  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://app.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​