veo-sdk

SDK oficial de Veo para web apps. Captura eventos de analytics y muestra guías in-app (tooltips, modales, walkthroughs).

Stack

• TypeScript estricto
• Cero dependencias en runtime
• 3 formatos: ESM, CJS, IIFE (CDN)
• < 10KB gzipped

Instalación

npm

npm install veo-sdk    # o: pnpm add veo-sdk / yarn add veo-sdk

import { init } from 'veo-sdk';

// Solo en el navegador (usa localStorage/DOM). En Next: client component.
const veo = init({
  apiKey: 'pk_xxx',
  guides: true,   // opt-in: renderiza guías in-app
  // apiUrl es OPCIONAL: por defecto apunta al backend gestionado de Veo.
  // Solo se pasa para self-hosted / otra región.
});

veo.identify({ visitor: { id: 'user_123', traits: { email: '[email protected]' } } });
veo.track('button_clicked');

CDN (sin bundler)

Cargá veo.js desde unpkg y llamá init en el onload del <script> (NO uses un stub con cola: el drain del IIFE saltea el init encolado):

<script
  src="https://unpkg.com/[email protected]/dist/veo.js"
  onload="window.veo.init({ apiKey: 'pk_xxx', guides: true });
          window.veo.identify({ visitor: { id: 'user_123' } });">
</script>

apiUrl es opcional (default = backend gestionado). Fijá la versión (@0.2.1) para no romperte con un release futuro. También por jsDelivr: https://cdn.jsdelivr.net/npm/[email protected]/dist/veo.js.

Editor visual de guías (modo builder)

El dashboard de Veo puede abrir tu app en un editor visual para diseñar guías sobre ella (elegir el elemento ancla, previsualizar). Para eso abre tu app en un <iframe> con ?veoBuilder=<token> y necesita cargar el bundle del builder (veo-builder.js) para hacer el handshake. Solo se descarga cuando la URL trae ese token: tus usuarios finales nunca lo cargan.

CDN (<script>)

Funciona sin configurar nada: el SDK deriva la URL de veo-builder.js a partir del <script> que cargó veo.js.

Bundler (Next / Vite / React)

Funciona sin configurar nada: con init({ guides: true }) el SDK carga el builder con un import() dinámico cuando la app se abre con ?veoBuilder. Tu bundler lo code-splitea, así que no se descarga para tus usuarios finales y no tenés que copiar veo-builder.js ni setear builderUrl.

init({ apiKey: 'pk_xxx', guides: true });

builderUrl sigue disponible como override manual (CDN propio, CSP estricto), pero ya no hace falta.

App con login (Supabase, Clerk, …)

Si tu app tiene login, el editor no puede autenticarse dentro del iframe (Google OAuth = 403, cookies de terceros). Para diseñar sobre páginas protegidas hace falta un "modo diseño" en tu app: dejar que Veo la embeba + entrar como usuario demo. El SDK trae los helpers (veoBuilderProxy, ensureVeoDesignSession en veo-sdk/next) y la receta completa con Supabase (2 archivos, copiable) está en docs/integrations/visual-editor-embed.md.

API

(En desarrollo. Implementación completa en sprints siguientes.)

• init(config) - inicializa el SDK
• identify(payload) - identifica un usuario
• track(name, properties?) - emite evento custom
• pageview(path?) - emite pageview (automático en SPAs)
• reset() - limpia identidad
• flush() - fuerza envío de la queue

Autocaptura

Al hacer init(), el SDK captura automáticamente clicks, submits y changes del DOM (sin código por evento), estilo Pendo/PostHog. Cada interacción genera un track('$autocapture', …) con metadata del elemento (tag, id, clases "humanas", texto, atributos, selector CSS y ancestros). Va por la misma queue (mismo batching/retry) que el resto de eventos.

Privacidad agresiva por defecto: nunca se captura el value de inputs, ni el texto de campos de entrada, y se ignoran inputs sensibles (password, email, tel, datos de tarjeta, campos con name/id tipo password/ssn/credit/card).

Opt-out de un elemento (y su subárbol)

<button data-veo-ignore>No me trackees</button>
<div class="veo-ignore"> … nada aquí se captura … </div>

Nombre semántico (tagging)

data-veo-tag da un nombre estable al elemento (prioritario en el selector, ideal para definir "features" en el dashboard aunque cambien clases/estructura):

<button data-veo-tag="checkout-cta">Comprar</button>

Configuración

init({
  apiKey: 'pk_xxx',
  apiUrl: 'https://api.veo.io',
  autocapture: {
    captureClicks: true,      // default
    captureSubmits: true,     // default
    captureChanges: true,     // default (solo selects y checkbox/radio)
    maskAllText: false,       // true → no capturar texto visible
    blockSelectors: ['.private', '#chat-widget'], // ignorar selectores propios
    throttleMs: 100,          // anti-spam por elemento
    maxTextLength: 200,       // truncado de textos
    captureAncestors: 5,      // niveles de ancestros (máx 10)
  },
});

// Deshabilitar por completo:
init({ apiKey: 'pk_xxx', apiUrl: '…', autocapture: false });

Desarrollo

# Setup
pnpm install

# Desarrollo (watch)
pnpm dev

# Build
pnpm build

# Tests
pnpm test

# Ver tamaño del bundle
pnpm size

# Lint
pnpm lint

Roadmap

• ✅ Sprint 1: Core (identify, track, pageview, SPA router)
• ✅ Sprint A: Autocaptura de clicks/submits/changes (PII-safe)
• ⬜ Sprint 4: Guías in-app (tooltips, modales, banners)
• ⬜ Sprint 5: Walkthroughs multi-paso
• ⬜ Futuro: Session replay

Licencia

UNLICENSED (proyecto privado)