Guía de integración de Argumentum

Todo lo necesario para integrar Argumentum en cualquier aplicación web — HTML plano, React, Vue, Angular o lo que venga — y sacarle valor desde el primer día: analítica de uso (páginas, clicks, funnels, paths, adopción, clientes/tenants) y guías in-app (tooltips, lightboxes, banners, checklists).

1. Instalación (5 minutos)

1.1 Crea la aplicación en el panel

Panel → Apps e integración → escribe el nombre de tu web → Crear app. Copia la app key (sk_…). Cada web/bundle que instrumentes lleva su propia key; todas comparten el mismo servidor y la misma base analítica.

1.2 Pega el snippet en tu web

En el <head> (o al final del <body>) de todas las páginas:

<script src="https://TU-ARGUMENTUM/agent.js"
        data-key="sk_xxxxxxxxx"
        data-endpoint="https://TU-ARGUMENTUM"></script>

• data-endpoint es opcional si el agente se sirve del mismo origen que la API. En despliegues con dominio propio, será tu dominio.
• El agente es first-party: sírvelo desde tu dominio (o el del servidor) y no será bloqueado por ad-blockers ni pierde cookies de terceros.
• Sin más configuración ya está auto-capturando: páginas vistas y clicks (con selector resuelto), y auto-registrando páginas nuevas.

1.3 (Recomendado) Identifica a tus usuarios

Sin identificar, todo funciona con visitantes anónimos. Con identify activas: segmentación de guías por rol/plan/lo-que-quieras, la vista de Clientes (tenants) y filtros por usuario.

// en el momento en que sabes quién es el usuario (tras login, bootstrap, etc.)
argumentum('identify', {
  visitorId: user.id,            // estable y único por usuario
  tenantId:  user.orgId,         // opcional: id de su empresa/cliente (SaaS multitenant)
  visitor:   { rol: user.role, idioma: user.locale },   // metadata de usuario
  tenant:    { plan: user.plan, sector: user.sector }   // metadata de la empresa
});

// eventos de negocio con propiedades
argumentum('track', 'proyecto_creado', { plantilla: 'marketing' });
argumentum('track', 'checkout_completado', { importe: 49.9, moneda: 'EUR' });

Reglas de la metadata:

• Los campos que envíes quedan disponibles para segmentar (audiencias de guías, filtros del panel, estimates de segmentos).
• Nunca envíes PII libre (email, DNI, teléfono) como valor de campo: usa ids o categorías. El esquema recomendado: rol, idioma (visitor) y nombre, plan, sector, pais, fecha_alta (tenant).
• visitorId debe ser estable entre sesiones (el id de tu base de datos). Si no lo envías, el agente genera uno anónimo en localStorage.

2. Etiquetado preciso (Pages y Features)

El tagging conecta el tráfico capturado con conceptos de producto. Es la base de clickmaps, funnels, adopción y paths. Se gestiona en Panel → Páginas y features (o por API, sección 5).

2.1 Pages: qué cuenta como página

Una page agrupa URLs bajo un nombre. Reglas posibles (una page puede tener varias; se evalúan en OR, basta con que una encaje):

Una cadena sin prefijo ("checkout") equivale a contiene:checkout.

Buenas prácticas

1. General después de específica: el matcher devuelve la primera page cuyas reglas encajen (puedes reordenarlas). Crea primero las pages específicas (exacta:/app/fact/nueva → «Nueva factura») y al final la genérica (prefijo:/app/fact/ → «Facturación»).
2. Normaliza ids variables con regex: para /fact/1234 usa regex:^/fact/[0-9]+$ en vez de contiene:/fact/, que también capturaría /facturacion.
3. Excluye lo que no es producto: en Apps → Ámbito de tracking puedes excluir rutas (prefijo:/panel-admin, regex:^/legal/). Lo excluido no genera datos.
4. Auto-registro: si llega tráfico de una ruta sin página, el servidor crea una page automática (exacta:ruta). Revísalas en Páginas y features y renómbralas o fusiónalas añadiendo su regla a otra page.

2.2 Features: qué elemento es cada cosa

Una feature es un elemento concreto de la UI (botón, enlace, pestaña, toggle). Se define por selector CSS. La adopción, los clickmaps y los funnels cuentan clicks que caen dentro del elemento seleccionado.

Cómo escribir un selector que no se rompa (por orden de preferencia):

1. Data-atributo propio — el más estable: [data-sv='crear-proyecto'], [data-testid='exportar']. Si controlas el frontend, añade data-* semánticos a los elementos importantes. Es la práctica que hace el tagging inmune a rediseños.
2. #id si es único y estable: #btn-exportar.
3. [aria-label='…'] para botones icónicos accesibles.
4. Ruta CSS corta como último recurso: nav > button:nth-of-type(2). Frágil ante cualquier cambio de maquetación: úsala solo como respaldo.

Cada feature admite respaldos (selector.respaldo): lista ordenada de selectores alternativos. El agente usa el primero que encuentre en el DOM.

Verifica siempre tu selector antes de guardarlo, en la consola del navegador sobre la página real:

document.querySelectorAll("[data-sv='crear-proyecto']").length   // debe ser exactamente 1

(1 = perfecto; >1 = coge el primero visible; 0 = no existe en esa página).

Captura con el modo diseñador: en Páginas y features, escribe la URL de tu web y pulsa 🎯: se abre tu web con el agente en modo selección; al hacer click en un elemento, el selector se rellena en el formulario. También puedes abrir directamente https://tu-web?argumentum_designer=feature.

Detalles por framework (el agente es vanilla JS y funciona igual en todos):

• Vue: los atributos scoped (data-v-3f2a1b) cambian entre builds — taggea con data-* propios, no con los generados.
• React: los className generados (CSS modules, styled-components tipo Button-sc-1x2y3z) cambian en cada build — usa data-testid o id.
• Angular: evita _ngcontent-xxx/_nghost-xxx (cambian por compilación); data-* propios o aria-label.
• Elementos dentro de Shadow DOM: el autocapture no los ve; usa argumentum('track', …) para ellos.

2.3 Track events (lo que no es un click)

Para hitos de negocio que no son interacciones de UI (compras, importaciones, validaciones), usa argumentum('track', nombre, props). Aparecen en la vista Adopción/top como «eventos» y son pasos válidos de funnels y paths (tipo: "track").

3. Guías in-app

3.1 Crear y publicar

Panel → Guías → Nueva guía:

1. Pasos: cada paso tiene tipo (tooltip / lightbox / banner), título, cuerpo, texto del botón y ancla (selector CSS, opcional). Con «🎯 Elegir ancla» el modo diseñador captura el selector sobre tu web real.

• Paso sin ancla: tooltip centrado (o banner si es de tipo banner).
• Ancla obligatorio: true: si el elemento no está en la página, el paso no se muestra (nunca molestar sin contexto).

1. Audiencia: reglas sobre la metadata (tenant.plan es Enterprise, visitor.rol es admin), páginas donde aparece (reglas de URL, vacío = todas) y frecuencia (siempre / una_vez / sesión).
2. Programa: fechas de visibilidad. No hay distinción de entornos: solo lo publicada llega al bundle (para probar en otra web, crea otra app con su propia key).
3. Publicar: regenera el bundle GET /v1/config; los usuarios lo reciben al recargar o navegar. Guardar como borrador o staged para pruebas.

El throttle global de la app (Ajustes: máx. guías por usuario y ventana, por defecto 2/semana) evita saturar: si dos guías compiten por el mismo usuario, gana la de menor prioridad.

Tipos: tooltip (anclado con flecha), lightbox (centrado con fondo), banner (barra superior) y checklist (widget fijo con progreso; cada tarea lanza su paso anclado y cuenta como completada).

3.2 Por API (sin panel)

curl -X PUT https://TU-ARGUMENTUM/v1/panel/guides/sk_xxx \
  -H "Authorization: Bearer ADMIN_TOKEN" -H "Content-Type: application/json" \
  -d '{
    "id": "g-onboarding-1",
    "nombre": "Tour de bienvenida",
    "tipo": "tooltip",
    "estado": "publicada",
    "prioridad": 1,
    "paginas": ["prefijo:/app/"],
    "frecuencia": { "tipo": "una_vez" },
    "segmentoReglas": [{ "campo": "visitor.rol", "operador": "es", "valor": "editor" }],
    "steps": [
      { "tipo": "tooltip", "contenido": { "titulo": "Bienvenido", "cuerpo": "3 pasos y fuera.", "cta": "Empezar" }, "anclaje": null },
      { "tipo": "tooltip", "contenido": { "titulo": "Crea tu primer proyecto", "cuerpo": "Con este botón.", "cta": "Siguiente" },
        "anclaje": { "selector": "[data-sv='crear']", "obligatorio": true } }
    ]
  }'

Estados: borrador → staged → publicada → pausada (DELETE elimina la guía). Un PUT guarda el def completo y sobrescribe lo anterior: no hay histórico de versiones (lo que se fue, se fue; usa borrador hasta tenerlo claro). POST /v1/panel/guides/:appKey/:id/publish pasa la guía a publicada, y el bundle GET /v1/config se regenera por ETag.

3.3 Métricas de guías

Impresiones, avances y completación por guía: vista Guías del panel o POST /v1/query/guias. Eventos generados por el agente: impresion, siguiente, atras, cta, cierre, completo.

4. Importar desde Pendo

1. Conexión directa: Panel → Guías → Importar desde Pendo → pega la integration key → el servidor descarga guías, pages, features y metadata → selecciona qué importar.
2. CLI: node tools/pendo-export/export.mjs --key KEY (volcado) y node tools/pendo-import.mjs --app-key sk_xxx --dir pendo-export-….

Detalle del mapeo, estados y deduplicación: sección «Importar desde Pendo» del README y docs/pruebas-finales.md.

5. API de consulta (BI, informes, tu propio código)

Autenticación: Authorization: Bearer ADMIN_TOKEN (o el token de sesión del panel). Todas aceptan appKey (obligatorio), tenantId (opcional, filtra a un cliente), rango (24h|7d|30d|12w|6m; un valor desconocido cae al defecto 12w) y from/to ISO explícitos.

Ejemplo con fetch:

const r = await fetch("https://TU-ARGUMENTUM/v1/query/funnel", {
  method: "POST",
  headers: { "Content-Type": "application/json", Authorization: "Bearer " + TOKEN },
  body: JSON.stringify({
    appKey: "sk_xxx", tenantId: "cliente-42", rango: "30d",
    ventanaHoras: 168,                       // conversión dentro de 7 días
    ventanaModo: "inicio",                   // o "paso": ventana entre pasos consecutivos
    pasos: [
      { tipo: "page",    id: "/app/inicio" },
      { tipo: "feature", id: "f-crear" },
      { tipo: "track",   id: "proyecto_creado" }
    ]
  })
});

Ingesta server-side (eventos que no pasan por el navegador: backend, ERP…):

curl -X POST https://TU-ARGUMENTUM/v1/events -H "X-Api-Key: sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{"lote":[{"tipo":"track","ts":1760000000000,"visitorId":"u-1",
       "tenantId":"cliente-42","path":"/api/proceso","trackName":"import_completa"}]}'

Smoke test completo de un despliegue: ADMIN_TOKEN=… node tools/api-smoke.mjs --server https://TU-ARGUMENTUM

6. Resolución de problemas

7. Seguridad y privacidad (producción)

• Fija siempre ADMIN_TOKEN fuerte (el token de desarrollo solo avisa en log).
• La ingesta autentica con la app key (pública por diseño, como cualquier herramienta client-side); el rate de ingesta lo fija la cuota de la organización de la app (reqPorMinuto, 600/min por defecto, 0 = sin límite) y frena abusos.
• HTTPS obligatorio vía tu proxy inverso; el agente no envía cookies.
• No se capturan valores de inputs (diseño del agente, no desactivable).
• Datos en TU infraestructura; sin terceros. Exporta o borra a tu criterio (los eventos son filas de ClickHouse).