Saltar al contenido principal

Configuración del snippet

Esta página es la guía de instalación HTML / script simple del snippet de seguimiento de Selgeo (selgeo.js) — un archivo JavaScript ligero que se ejecuta en su sitio web, registra los clics de referido de socios y almacena datos de atribución en el navegador del visitante para la correspondencia de conversiones posterior. Utilice esta guía si controla directamente el HTML de su sitio (sitios estáticos, Webflow, Shopify Liquid, páginas personalizadas renderizadas en el servidor o un gestor de etiquetas).

¿Usa un framework?
  • Next.js — consulte la guía de Next.js para el patrón del componente next/script.
  • React (Vite) — consulte la guía de React (Vite) para la colocación en index.html y el respaldo mediante useEffect.
  • WordPress — consulte la guía de WordPress para la colocación mediante Editor del sitio, footer.php y plugins de cabecera-pie de página.

Versión de API: v1

Instalación básica​

Agregue la siguiente etiqueta <script> a cada página de su sitio web, justo antes de la etiqueta de cierre </body>:

<script
  async
  src="https://cdn.selgeo.com/v1/selgeo.js"
  data-merchant="pk_test_YOUR_KEY"
></script>

Reemplace pk_test_YOUR_KEY con su clave API pública del panel de control de Selgeo (Configuración > Claves API).

Atributos requeridos​

AtributoDescripción
srcURL de CDN para el snippet. Use siempre https://cdn.selgeo.com/v1/selgeo.js.
data-merchantSu clave API pública (pk_test_* para modo de prueba, pk_live_* para modo live).
asyncCarga el snippet de forma asíncrona para no bloquear el renderizado de la página.

Atributos opcionales​

AtributoDescripción
data-debugHabilita el registro de depuración en la consola del navegador. Eliminar antes de ir a producción.
data-api-urlAnula la URL del punto de conexión de la API. Solo para uso avanzado (p. ej., proxy personalizado).

Cómo funciona​

Cuando un visitante llega a su sitio con un parámetro ?ref= en la URL (p. ej., https://su-sitio.com/pricing?ref=abc123), el snippet:

  1. Detecta el parámetro de consulta ref.
  2. Registra el clic con la API de Selgeo usando su clave pública.
  3. Almacena el click_id devuelto por la API en el sessionStorage del navegador.
  4. Elimina ?ref= de la URL usando history.replaceState para mantener las URLs limpias.
  5. Reescribe los Stripe Payment Links en la página para incluir client_reference_id=CLICK_ID.

Si no hay parámetro ?ref=, el snippet no hace nada. No tiene overhead en páginas donde no se produce ningún referido.

Mecanismo de almacenamiento​

El snippet almacena datos de atribución en sessionStorage, no en cookies:

ClaveValorTiempo de vida
__selgeo_cidEl click_id (UUID)Hasta que se cierre la pestaña del navegador
__selgeo_vtkUn token de visitante (UUID)Hasta que se cierre la pestaña del navegador

Implicaciones de privacidad:

  • sessionStorage está limitado a la pestaña — no se comparte entre pestañas o ventanas.
  • Los datos se borran automáticamente cuando se cierra la pestaña.
  • No se establecen cookies. No se requiere banner de consentimiento de cookies para el seguimiento de Selgeo.
  • El snippet no envía datos a Selgeo a menos que haya un parámetro ?ref= presente.

Leer el ID de clic​

Su código frontend puede leer el click_id almacenado en cualquier momento:

const clickId = __selgeo.getClickId();
// Devuelve una cadena UUID (p. ej., "f47ac10b-58cc-4372-a567-0e02b2c3d479")
// Devuelve null si no se registró ningún clic de referido en esta sesión

Esto es útil cuando necesita pasar el click_id a su backend — por ejemplo, al crear una Sesión de pago de Stripe o al llamar a la API de conversión.

Métodos disponibles​

MétodoDevuelveDescripción
__selgeo.getClickId()string | nullEl ID de clic actual, o null si no existe ninguno
__selgeo.getVisitorToken()string | nullEl token de visitante actual, o null
__selgeo.checkUrl()voidComprueba manualmente la URL actual en busca de un parámetro ?ref=

Aplicaciones de página única (SPAs)​

El snippet monitorea automáticamente los cambios de URL en aplicaciones de página única. Escucha:

  • Eventos popstate (navegación adelante/atrás del navegador)
  • Llamadas history.pushState y history.replaceState (navegación programática)

Cuando la URL cambia y contiene un nuevo parámetro ?ref=, el snippet captura el clic automáticamente. No se necesita configuración adicional para React, Vue, Angular u otros frameworks SPA.

Comprobación manual de URL​

En casos raros donde la detección automática no se activa, puede decirle manualmente al snippet que vuelva a comprobar:

__selgeo.checkUrl();

Si su página contiene enlaces a Stripe Payment Links (https://buy.stripe.com/...), el snippet agrega automáticamente ?client_reference_id=CLICK_ID cuando hay un clic de referido activo.

<!-- Antes de que se ejecute el snippet -->
<a href="https://buy.stripe.com/test_abc123">Suscribirse</a>

<!-- Después de que se ejecute el snippet (cuando hay un click_id almacenado) -->
<a href="https://buy.stripe.com/test_abc123?client_reference_id=CLICK_ID">Suscribirse</a>

El snippet también vigila los Payment Links añadidos dinámicamente (via MutationObserver) y los reescribe a medida que aparecen. Esto funciona con SPAs y contenido cargado de forma diferida.

Protección contra sobreescritura del comerciante: Si establece client_reference_id en un Payment Link usted mismo, el snippet no sobrescribirá su valor. Su valor explícito siempre tiene prioridad.

Para una guía detallada, vea Stripe Payment Links.

Instalación mediante gestor de etiquetas​

Si usa Google Tag Manager (GTM) u otro gestor de etiquetas, agregue el snippet como una etiqueta HTML personalizada:

  1. Cree una nueva etiqueta HTML personalizado en GTM.
  2. Pegue la etiqueta script: 
    <script
      async
      src="https://cdn.selgeo.com/v1/selgeo.js"
      data-merchant="pk_test_YOUR_KEY"
    ></script>
  3. Establezca el activador en Todas las páginas.
  4. Publique el contenedor.
Temporización del gestor de etiquetas

Al usar un gestor de etiquetas, el snippet puede cargarse ligeramente más tarde que una etiqueta <script> directa. Esto está bien para la mayoría de los casos de uso, pero si necesita el click_id disponible inmediatamente al cargar la página, agregue el snippet directamente a su HTML.

Recomendaciones de colocación​

EscenarioRecomendación
Sitio web estándarAgregar a cada página mediante el layout/template global
SPA (React, Vue, etc.)Agregar una vez a index.html — el snippet gestiona los cambios de ruta
Solo páginas de destinoAgregar solo a las páginas donde aterriza el tráfico de socios
Solo página de pagoNo recomendado — el snippet debe estar en la página de destino para capturar el parámetro ?ref=
El snippet debe estar en la página de destino

El parámetro ?ref= solo está presente en la URL inicial cuando el visitante hace clic en un enlace de socio. Si el snippet no está cargado en esa página, el clic no se registrará y el click_id no estará disponible para la atribución de conversiones posterior.

Verificar su instalación​

  1. Agregue data-debug a la etiqueta script temporalmente.
  2. Visite su sitio con un enlace de seguimiento de prueba: https://su-sitio.com/?ref=SU_REF_PRUEBA
  3. Abra las Herramientas de desarrollador (F12) y compruebe la Consola para: 
    [selgeo] ref detected SU_REF_PRUEBA
    [selgeo] click_id stored xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
  4. Compruebe sessionStorage en la pestaña Aplicación (Chrome) o Almacenamiento (Firefox):
    • __selgeo_cid debe contener un UUID
    • __selgeo_vtk debe contener un UUID
  5. Llame a la API en la consola: 
    __selgeo.getClickId()  // Debe devolver una cadena UUID
  6. Verifique el panel de control — el clic debe aparecer en Analytics en segundos.

Próximos pasos​