Saltar al contenido principal

Landing custom con JavaScript SDK

Construye tu propia landing en tu dominio o CMS y conéctala a una campaña de IncentIA usando el JavaScript SDK. Útil cuando quieres control total de la UX o integrar la captura con tu web existente.

Caso: tienes una landing de marketing ya diseñada en tu CMS (Webflow, Framer, HTML propio) y quieres que un botón "Participa y gana" dispare la ruleta de una campaña IncentIA.

Tiempo: ~30 min · Nivel: intermedio (HTML/JS básico).

Requisitos previos​

  • Una campaña con un juego ya creada (tutorial de juegos).
  • Tu tenant tiene API Key pública habilitada (Admin → Integraciones → API Keys → crear una con scope campaign-participate).
  • Permisos CORS configurados para el dominio de tu landing (Admin → Settings → CORS origins).

1. Incluir el SDK​

Añade en el <head> de tu landing:

<script src="https://cdn.incentia.app/sdk/v1/incentia.min.js"></script>

O instala via npm si tu stack lo permite:

npm install @incentia/sdk

2. Inicializar el cliente​

const incentia = IncentiaSDK.create({
  apiKey: 'pk_live_xxxxx',          // API key pública
  tenant: 'miempresa',              // subdomain del tenant
  baseUrl: 'https://app.incentia.app'
});

El SDK expone métodos asincrónicos para todo el ciclo de participación.

3. Identificar al visitante​

Dos opciones:

a) OTP (el miembro introduce email/teléfono):

// Enviar código
await incentia.auth.sendOtp({ email: 'user@example.com' });

// Verificar código
const session = await incentia.auth.verifyOtp({
  email: 'user@example.com',
  code: '123456'
});

b) Token ya existente (si el visitante viene de tu sistema autenticado):

incentia.auth.setToken(myBackendToken);

4. Registrar la participación​

const participation = await incentia.campaigns.participate({
  campaignSlug: 'verano-25',
});

console.log(participation.id);         // UUID de la participación
console.log(participation.canPlay);    // true si puede tirar
console.log(participation.remaining);  // tiradas restantes

Si el miembro ya agotó sus tiradas, canPlay = false y podrás mostrar el mensaje correspondiente.

5. Disparar el juego​

const result = await incentia.games.play({
  participationId: participation.id,
});

console.log(result.prize);
// { id: 42, name: 'Cupón 10%', code: 'VERANO10', type: 'coupon' }

El backend evalúa la ruleta (respetando probabilidades y stock) y devuelve el premio. Puedes ignorar la lógica y renderizar tu propia animación de ruleta — el resultado está decidido.

6. Renderizar el resultado​

if (result.prize.type === 'coupon') {
  document.getElementById('result').innerHTML = `
    <h2>¡Has ganado ${result.prize.name}!</h2>
    <p>Código: <code>${result.prize.code}</code></p>
    <p>Te lo hemos enviado por email.</p>
  `;
} else if (result.prize.type === 'physical') {
  document.getElementById('result').innerHTML = `
    <h2>¡Has ganado ${result.prize.name}!</h2>
    <p>Te contactaremos para gestionar el envío.</p>
  `;
}

El email con el cupón/instrucciones se envía automáticamente por IncentIA si tienes configurada la plantilla de la campaña.

7. Ejemplo completo (HTML+JS)​

<!DOCTYPE html>
<html>
<head>
  <script src="https://cdn.incentia.app/sdk/v1/incentia.min.js"></script>
</head>
<body>
  <h1>¡Tira la ruleta!</h1>
  <form id="otp-form">
    <input type="email" id="email" placeholder="Tu email" required />
    <button type="submit">Entrar</button>
  </form>
  <div id="game" style="display:none"></div>
  <div id="result"></div>

  <script>
    const incentia = IncentiaSDK.create({
      apiKey: 'pk_live_xxxxx',
      tenant: 'miempresa',
    });

    document.getElementById('otp-form').addEventListener('submit', async (e) => {
      e.preventDefault();
      const email = document.getElementById('email').value;
      await incentia.auth.sendOtp({ email });
      const code = prompt('Código OTP recibido:');
      await incentia.auth.verifyOtp({ email, code });

      const p = await incentia.campaigns.participate({ campaignSlug: 'verano-25' });
      if (!p.canPlay) {
        document.getElementById('result').innerText = 'Ya has participado';
        return;
      }
      document.getElementById('game').style.display = 'block';
      // aquí puedes renderizar tu animación de ruleta...
      const result = await incentia.games.play({ participationId: p.id });
      document.getElementById('result').innerHTML = `¡${result.prize.name}!`;
    });
  </script>
</body>
</html>

8. Personalización avanzada​

El SDK no te obliga a usar su UI — solo orquesta llamadas al backend. Puedes:

  • Usar tu propia animación de ruleta (CSS, canvas, Lottie) y al final mostrar el premio.
  • Usar tu propio sistema de OTP (enviar tú el email) si no quieres usar el de IncentIA.
  • Integrar con Google Analytics / Meta Pixel inyectando eventos en cada paso.

9. Seguridad​

  • La API key pública solo permite acciones acotadas: participate, play, auth. NO accede a datos de otros miembros.
  • El secret NUNCA va en el frontend. Usa solo pk_ (pública).
  • Para operaciones admin (crear campañas, leer métricas) usa API key privada desde tu backend.

10. Debug​

  • Consola del navegador: incentia.debug = true para logs detallados.
  • Admin → Integraciones → API Keys → {tu key} → Logs — ves cada petición con timestamp y status.

Qué has construido​

  • Landing propia con control total de diseño.
  • Identificación de visitantes via OTP.
  • Participación y juego disparados vía SDK.
  • Resultados y premios manejados en tu UI.

Próximos pasos​

  • Server-side integration para operaciones críticas → usa la API REST.
  • Webhooks outbound desde IncentIA a tu sistema cuando alguien juega → Admin → Webhooks.
  • Combina con Shopify para otorgar tiradas por compra → tutorial Shopify.