Saltar al contenido principal

Inicio rápido

Configure su programa de afiliados en menos de 30 minutos. Esta guía le explica cómo agregar el snippet de seguimiento de Selgeo a su sitio web, conectarlo a Stripe y verificar su primera conversión de prueba.

Versión de API: v1

Requisitos previos​

  • Una cuenta de comerciante Selgeo
  • Acceso al HTML de su sitio web (o a un gestor de etiquetas)
  • Una cuenta de Stripe conectada a Selgeo (para el seguimiento de conversiones basado en Stripe)

Paso 1: Obtener sus claves API​

Inicie sesión en el panel de control de comerciante Selgeo y navegue a Configuración > Claves API. Verá dos pares de claves:

Tipo de claveFormatoPropósito
Clave pública (prueba)pk_test_*Snippet JS en su sitio web (modo de prueba)
Clave pública (live)pk_live_*Snippet JS en su sitio web (modo live)
Clave secreta (prueba)sk_test_*Llamadas API del lado del servidor (modo de prueba)
Clave secreta (live)sk_live_*Llamadas API del lado del servidor (modo live)

Las claves públicas (pk_*) son seguras para incluir en el código frontend. Solo pueden registrar clics.

Las claves secretas (sk_*) nunca deben exponerse al navegador. Úselas solo en su servidor.

Empiece con claves de prueba

Use pk_test_* y sk_test_* durante la integración. El modo de prueba realiza el seguimiento de todo de la misma manera pero no crea comisiones reales. Cambie a claves live cuando esté listo para ir en producción.

Paso 2: Agregar el snippet de seguimiento​

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 pública real del Paso 1.

Para su framework, consulte la guía dedicada​

La etiqueta <script> anterior funciona en cualquier página HTML. Si construye sobre un stack frontend moderno, la integración equivalente se encuentra en una de las siguientes guías:

  • HTML / script plano — sitios estáticos, gestores de etiquetas, páginas renderizadas en el servidor.
  • Next.js — next/script para App Router y Pages Router.
  • React (Vite) — colocación en index.html, con respaldo mediante useEffect.
  • WordPress — Editor del sitio, footer.php o un plugin de cabecera y pie de página.

Lo que hace el snippet:

  1. Cuando un visitante llega a través de un enlace de referido de socio (p. ej., https://su-sitio.com/?ref=abc123), el snippet registra el clic en Selgeo y almacena un click_id en el sessionStorage del navegador.
  2. Si usa Stripe Payment Links, el snippet agrega automáticamente el click_id a esos enlaces como client_reference_id — no se necesita trabajo de backend.
  3. El snippet no usa cookies. Utiliza solo sessionStorage, que se borra cuando se cierra la pestaña del navegador. No se requiere banner de consentimiento de cookies.

Paso 3: Verificar su instalación​

  1. Cree un enlace de seguimiento en el panel de control de Selgeo en Programas > Enlaces de seguimiento.
  2. Abra una nueva pestaña del navegador y visite su sitio usando el enlace de seguimiento, p. ej.: 
    https://su-sitio.com/?ref=SU_REF_SEGUIMIENTO
  3. Abra las Herramientas de desarrollador de su navegador (F12) y verifique la pestaña Consola. Si agregó data-debug a su etiqueta script, verá mensajes de registro del snippet: 
    [selgeo] ref detected SU_REF_SEGUIMIENTO
    [selgeo] click_id stored xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
  4. Para habilitar temporalmente el modo de depuración, agregue el atributo data-debug: 
    <script
      async
      src="https://cdn.selgeo.com/v1/selgeo.js"
      data-merchant="pk_test_YOUR_KEY"
      data-debug
    ></script>
  5. Verifique que el click_id esté almacenado ejecutando esto en la consola del navegador: 
    __selgeo.getClickId()
    Esto debe devolver una cadena UUID. Si devuelve null, el snippet no detectó un parámetro ?ref= en la URL.
  6. Verifique el panel de control de Selgeo — el clic debería aparecer en Analytics en pocos segundos.
Eliminar data-debug antes de ir a producción

El atributo data-debug es solo para desarrollo. Elimínelo en producción para mantener la consola del navegador limpia.

Paso 4: Rastrear conversiones a través de Stripe​

Selgeo admite tres rutas de integración de Stripe. Elija la que se adapte a su configuración:

Si usa Stripe Payment Links (URLs buy.stripe.com), el snippet maneja todo automáticamente.

Cómo funciona: El snippet detecta todas las etiquetas <a> que apuntan a https://buy.stripe.com/... y agrega ?client_reference_id=CLICK_ID. Cuando el cliente completa el pago, Stripe incluye el client_reference_id en el payload del webhook, y Selgeo lo asocia al socio que refirió el clic.

No se necesita código de backend. Solo asegúrese de que el snippet esté cargado en la página donde aparece el Payment Link.

<!-- Su Payment Link existente — el snippet lo reescribe automáticamente -->
<a href="https://buy.stripe.com/test_abc123">Suscribirse ahora</a>

Después de que el snippet se ejecute, el enlace se convierte en:

https://buy.stripe.com/test_abc123?client_reference_id=CLICK_ID

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

Opción B: Stripe Checkout (una línea de código frontend)​

Si crea Sesiones de pago de Stripe en su servidor, necesita pasar el click_id del navegador a su backend.

Frontend — leer el ID de clic del snippet:

const clickId = __selgeo.getClickId();

// Enviarlo a su backend cuando el usuario inicia el pago
fetch('/api/create-checkout', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    priceId: 'price_xxx',
    clickId: clickId, // puede ser null si no hay referido
  }),
});

Backend — pasarlo como client_reference_id al crear la Sesión de pago:

const stripe = require('stripe')('sk_test_YOUR_STRIPE_KEY');

app.post('/api/create-checkout', async (req, res) => {
  const session = await stripe.checkout.sessions.create({
    mode: 'subscription',
    line_items: [{ price: req.body.priceId, quantity: 1 }],
    success_url: 'https://su-sitio.com/success',
    cancel_url: 'https://su-sitio.com/cancel',
    client_reference_id: req.body.clickId || undefined,
  });
  res.json({ url: session.url });
});

Selgeo lee client_reference_id automáticamente del webhook de Stripe. Para la guía completa, vea la guía de Stripe Checkout.

Opción C: Conversiones no-Stripe (API de conversión)​

Para conversiones que no pasan por Stripe (envíos de formularios, pruebas gratuitas, eventos personalizados), use la API de conversión para reportarlas desde su servidor:

curl -X POST https://api.selgeo.com/api/v1/conversions \
  -H "Authorization: Bearer sk_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "click_id": "CLICK_ID_DEL_FRONTEND",
    "external_transaction_id": "signup_12345",
    "event_type": "signup",
    "amount_cents": 0
  }'

Paso 5: Probar una conversión de extremo a extremo​

Recorra el ciclo completo en modo de prueba para confirmar que todo funciona:

  1. Cree un programa de prueba en el panel de control de Selgeo con al menos un socio y un enlace de seguimiento.
  2. Haga clic en el enlace de seguimiento en una nueva pestaña del navegador. Esto registra un clic y almacena un click_id.
  3. Complete una compra usando uno de los métodos anteriores:
    • Payment Links: Haga clic en un Stripe Payment Link en su sitio. Use la tarjeta de prueba de Stripe 4242 4242 4242 4242.
    • Checkout: Active su flujo de pago. El click_id se pasa como client_reference_id.
    • API de conversión: Envíe una solicitud POST /api/v1/conversions desde su servidor con el click_id.
  4. Verifique el panel de control: Navegue a Analytics en el panel de control de Selgeo. Debería ver:
    • El clic registrado bajo el socio
    • La conversión atribuida al socio
    • Una comisión calculada (si se configuraron reglas de comisión)
Tarjetas de prueba de Stripe

Use los números de tarjeta de prueba de Stripe para simular pagos sin cargos reales. El más común es 4242 4242 4242 4242 con cualquier fecha de vencimiento futura y cualquier CVC.

Próximos pasos​