Documentación del SDK

Inicio rápido

Añade este script al <head> de tu web:

<!-- fluxAB — Anti-flicker + SDK — instalar una vez, nunca más tocar -->
<script>!function(){var e="body{opacity:0!important}",t=document.createElement("style");t.textContent=e,t.id="fluxab-hide",document.head.appendChild(t),window._fluxabShow=function(){var e=document.getElementById("fluxab-hide");e&&e.remove(),document.body.style.opacity=""},setTimeout(window._fluxabShow,800)}();</script>
<link rel="preconnect" href="https://cdn.fluxabtest.com" />
<script async src="https://cdn.fluxabtest.com/client.js" data-project-key="pk_live_xxx"></script>

La pk_live_xxx la encuentras en Configuración de tu proyecto.

Después de instalar el snippet, verifica el dominio en Configuración. Solo los dominios verificados registran asignaciones y conversiones.

getVariant() — Asignación local

La asignación es determinista y local. La primera llamada descarga la configuración (y las variantes si aún no están en caché); después es instantánea. No registra exposición.

// Solo necesitas el <script> en el <head>.
// fluxAB se inicializa automáticamente como window.fluxAB

const result = await fluxAB.getVariant('new-checkout');

if (result.variant === 'B') {
  showNewCheckout();
}

activate() — Registra exposición

Como getVariant() pero registra que el usuario entró al experimento.

document.querySelector('#payment-btn')
  .addEventListener('click', async () => {
    const r = await fluxAB.activate('payment-test');
    showVariant(r.variant);
  });

track() — Conversiones

Envía eventos de conversión. Se agrupan cada 2s.

fluxAB.track('payment_completed');

fluxAB.track('payment_completed', {
  amount: 325.50,
  currency: 'EUR'
});

Hooks — Segment, Mixpanel, GTM

on() entrega cada variante resuelta y cada conversión a tu código, sin depender del proveedor. El hook de variante se dispara una vez por experimento y variante, así que nunca duplica.

// Un solo hook para todo: variant (una vez por experimento) y event.
const off = fluxAB.on((e) => {
  if (e.type === 'event') {
    analytics.track(e.eventName, e.properties);        // Segment
    mixpanel.track(e.eventName, e.properties);         // Mixpanel
  }
  if (e.type === 'variant') {
    analytics.track('Experiment Viewed', {
      experiment: e.experimentKey,
      variant: e.variant,
    });
  }
});

// off();  // cancela la suscripción

Google Analytics 4

Conecta tu propiedad en la configuración del proyecto y fluxAB reenviará cada conversión al Measurement Protocol desde el servidor: el API secret no viaja al navegador. No requiere tocar el código del sitio.

// 1. Panel → Proyecto → Configuración → Google Analytics 4
//    Measurement ID (G-XXXXXXX) + API secret.

// 2. En GA4, la conversión llega como:
//    fluxab_conversion
//      experiment: "precios"
//      variant:    "B"
//      conversion_event: "purchase"
//      page_path:  "/checkout"

// 3. Regístralas como dimensiones personalizadas para verlas
//    en Informes → Involucramiento → Eventos.
//    (Administrar → Definiciones personalizadas → Crear dimensión)

La atribución usa la cookie _ga, así que la etiqueta de GA4 debe estar instalada en las páginas donde se lanzan los tests.

MCP — resultados desde tu agente de IA

fluxAB expone un servidor MCP de solo lectura: tu agente lista proyectos y experimentos, consulta el informe con probabilidad de mejora y lee el embudo y los segmentos. El acceso se limita a la organización del token y no puede escribir nada.

// Panel → Organización → Integraciones → Crear token
// El token se muestra una sola vez y solo permite leer.

// .vscode/mcp.json o cursor/mcp.json
{
  "mcpServers": {
    "fluxab": {
      "type": "http",
      "url": "https://api.fluxabtest.com/mcp",
      "headers": {
        "Authorization": "Bearer mcp_tu_token"
      }
    }
  }
}

// Herramientas disponibles:
//   list_projects
//   list_experiments(project_slug?, status?)
//   experiment_report(project_slug, experiment_key)
//   experiment_funnel(project_slug, experiment_key)
//   experiment_segments(project_slug, experiment_key, dimension)

El token se crea en Organización → Integraciones y se muestra una sola vez. Si revocas el token, el agente deja de tener acceso al instante.

identify() — Vincular usuario

Asocia el ID anónimo con tu ID de cliente. Las asignaciones y conversiones anteriores se reasignan al usuario.

fluxAB.identify('customer_12345');

URL Split — Automático

Aplica la variante cuando la página coincide con la URL o los parámetros configurados. No redirige a otra URL.

const result = await fluxAB.getVariant('landing-test');

if (result.variant === 'B') {
  document.body.classList.add('variant-b');
}

Editor visual — cambios sin código

Cada variante puede llevar una lista de cambios DOM en payload.edits. El editor visual del panel la rellena por ti y el SDK la aplica antes de mostrar la página, así que no hay parpadeo. También puedes escribirla a mano desde la API.

{
  "edits": [
    { "selector": "#hero h1", "text": "Nuevo titular" },
    { "selector": ".cta", "css": "background:#111827;color:#fff" },
    { "selector": ".badge-antiguo", "hide": true }
  ]
}

Recomendado: limita el experimento a la página que editas con el campo «Limitar a una página». Así los cambios no se aplican en el resto del sitio.

Páginas y tráfico

Cada carga de página envía un $pageview automático con la ruta. Con eso el panel ordena tus páginas por visitantes y tasa de conversión. Los eventos de track() y las conversiones se atribuyen a la página donde ocurren.

Si el visitante ya tiene una asignación guardada, el SDK conserva su variante y refresca el payload (los cambios visuales) como máximo cada 5 minutos.

Con ese mismo tráfico el panel genera los mapas de calor: hasta 25 clics por página ($click con la posición en % del documento) y los hitos de scroll 25/50/75/100 ($scroll).

React y Next.js

El paquete npm incluye bindings para React y evaluación en servidor con el mismo hash que el navegador, así el visitante ve la misma variante sin parpadeo.

npm install @fluxab/sdk

// React
import { FluxABProvider, useVariant } from '@fluxab/sdk/react';

function Hero() {
  const { variant } = useVariant('hero-headline');
  return variant === 'B' ? <HeroB /> : <HeroA />;
}

<FluxABProvider projectKey="pk_live_xxx" userId={user?.id}>
  <Hero />
</FluxABProvider>

// Next.js App Router (servidor)
import { createFluxABServer } from '@fluxab/sdk/server';

const fluxab = createFluxABServer({
  projectKey: 'pk_live_xxx',
  origin: 'https://tutienda.com',
});

const { variant } = await fluxab.getVariant('precios', { visitorId });

SPAs y cambios de ruta

Después de un cambio de ruta con pushState o replaceState, llama a refresh(). El SDK escucha popstate (atrás/adelante) automáticamente.

fluxAB.refresh();

QA y preview