Saltar al contenido principal

React (Vite)

Instale el snippet de seguimiento de Selgeo en una aplicación React de página única construida con Vite. La ruta recomendada es una etiqueta <script> simple en index.html — la misma línea única que renderiza el panel. Al final de esta página se documenta una alternativa basada en useEffect para proyectos que no pueden editar index.html.

Versión de API: v1

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

¿Por qué index.html?​

En una SPA con Vite, index.html es el punto de entrada canónico: se envía al navegador antes de que se ejecute cualquier código React, todas las rutas se sirven desde el mismo archivo y el navegador maneja la deduplicación de <script> automáticamente. Colocar el snippet aquí significa:

  • El snippet está disponible antes de que React hidrate, por lo que un ?ref=… inicial se captura incluso con caché frío.
  • Sin useEffect, sin riesgo de doble montaje, sin sorpresas con React Strict Mode.
  • Una única fuente de verdad — no es necesario recordar inyectar el snippet en cada componente de layout.

Como el snippet no usa cookies y se basa en sessionStorage, es seguro cargarlo en cada página de una SPA con Vite sin cambiar el comportamiento de su aplicación React.

Instalación — Ruta recomendada​

Paso 1: Abra index.html​

Los proyectos Vite mantienen index.html en la raíz del proyecto (junto a vite.config.ts), no dentro de public/. Ábralo en su editor.

Paso 2: Agregue el snippet antes del módulo de la aplicación​

Coloque el <script> de Selgeo antes de <script type="module" src="/src/main.tsx"></script> para que la petición async del snippet esté en curso antes de que el módulo de la aplicación React empiece a evaluarse. Esto es lo que permite a Selgeo ver el ?ref=… inicial en el primer paint, antes de que React, el enrutador o cualquier reescritura del lado del cliente toquen la URL.

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>Your App</title>
  </head>
  <body>
    <div id="root"></div>

    <script
      async
      src="https://cdn.selgeo.com/v1/selgeo.js"
      data-merchant="pk_test_YOUR_KEY"
    ></script>
    <script type="module" src="/src/main.tsx"></script>
  </body>
</html>

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

index.html abierto en el editor con la etiqueta script de Selgeo añadida encima del script del módulo de la aplicación

Paso 3: Reinicie el servidor de desarrollo​

pnpm dev
# o
npm run dev

Vite recoge los cambios de index.html en el arranque en frío. El recargado en caliente de módulos a veces omite las ediciones de HTML, por lo que un reinicio es lo más seguro.

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 de React.
data-debugNoRegistro 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.

El snippet escucha los eventos popstate, history.pushState e history.replaceState. Si usa TanStack Router, React Router u otro enrutador del lado del cliente, no se necesita configuración adicional — un parámetro ?ref=… introducido en cualquier ruta se captura automáticamente.

Verificar la instalación​

  1. Inicie el servidor de desarrollo (pnpm dev).
  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. Abra el enlace de seguimiento en una pestaña nueva del navegador: 
    http://localhost:5173/?ref=SU_REF_DE_PRUEBA
  4. Abra las Herramientas para desarrolladores (F12) y revise la Consola. Con data-debug agregado temporalmente, verá: 
    [selgeo] ref detected SU_REF_DE_PRUEBA
    [selgeo] click_id stored xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
  5. Ejecute en la consola: 
    __selgeo.getClickId()
    Esto debería retornar un string UUID.
  6. Abra el panel de Selgeo. El clic debería aparecer en Analytics en pocos segundos.

Consola de DevTools del navegador mostrando las líneas de depuración selgeo ref detected y selgeo click_id stored

Alternativa: inyección basada en useEffect​

Use esta ruta solo si no puede editar index.html — por ejemplo, si su index.html lo genera un framework de nivel superior, o si está incrustando el snippet dentro de un micro-frontend cuya capa HTML no controla.

Este patrón conlleva una preocupación adicional: en React 18+ Strict Mode (predeterminado en las plantillas de Vite), los efectos se ejecutan dos veces en desarrollo. Sin una protección, el snippet se inyectaría dos veces y podría registrarse un clic duplicado. Use un id estable de elemento más un cortocircuito con document.getElementById:

// src/components/SelgeoSnippet.tsx
import { useEffect } from 'react';

const SELGEO_SCRIPT_ID = 'selgeo-snippet';

export function SelgeoSnippet() {
  useEffect(() => {
    if (document.getElementById(SELGEO_SCRIPT_ID)) {
      return;
    }

    const script = document.createElement('script');
    script.id = SELGEO_SCRIPT_ID;
    script.async = true;
    script.src = 'https://cdn.selgeo.com/v1/selgeo.js';
    script.setAttribute('data-merchant', 'pk_test_YOUR_KEY');
    document.body.appendChild(script);
  }, []);

  return null;
}

Monte <SelgeoSnippet /> una sola vez cerca de la raíz de su árbol de componentes (típicamente en App.tsx, junto a su proveedor de enrutador).

Por qué importa la protección:

  • React 18+ Strict Mode invoca intencionalmente los efectos dos veces en desarrollo para sacar a la luz errores de efectos secundarios.
  • Sin el cortocircuito de document.getElementById, se añadirían dos elementos <script>, ambos se ejecutarían y el snippet registraría dos clics para el mismo visitante.
  • El id="selgeo-snippet" estable permite que la protección funcione a través de recargados en caliente, cambios de ruta y remontajes de componentes.

Este patrón también es útil cuando la gestión de consentimiento o los feature flags deben condicionar la carga del snippet — envuelva el cuerpo del efecto en su condicional.

Solución de problemas​

El snippet no carga​

  • Confirme que el <script> esté dentro de <body>, no en <head> (el index.html de Vite ya debería tener <body>).
  • Ejecute pnpm build e inspeccione dist/index.html. El snippet debería aparecer en el HTML compilado.
  • Si usa un plugin de Vite personalizado que reescribe index.html, asegúrese de que preserve las etiquetas <script> añadidas por el usuario.
  • Verifique en la pestaña Network del navegador la petición a selgeo.js — un error CORS o CSP indica un problema de configuración (vea más abajo).

El clic no se rastrea​

  • El visitante debe llegar con ?ref=… en la carga inicial de la página. Las recargas eliminan el parámetro (el snippet reescribe la URL al capturar) — emita un enlace de seguimiento nuevo si ya consumió el actual.
  • Confirme que data-merchant contiene una clave pk_test_* o pk_live_* válida.
  • Si usa la alternativa con useEffect, confirme que la protección con document.getElementById está implementada y que SELGEO_SCRIPT_ID es único en la página.
  • Verifique el modo del panel (test vs. live) — un desajuste descarta el clic silenciosamente.

Bloqueo por CSP​

Si establece una Content-Security-Policy mediante un plugin de Vite, una meta-etiqueta o el servidor de origen, 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.

Próximos pasos​