Docs

Navegador

Instala @sypnia/browser con un gestor de paquetes o con una etiqueta script, cada opción de init con su tipo y su valor por defecto, qué se captura sin escribir código y las pocas funciones que llamas tú.

Aplica a MotorNube Al lanzar

Ver como Markdown
En esta página
  1. Instalar
  2. Con una etiqueta script, para apps sin paso de compilación
  3. Comprueba que funciona
  4. Qué se captura sin escribir código
  5. Ruido que el SDK deja fuera
  6. Lo que no hace
  7. init(options)
  8. Las funciones que llamas tú
  9. identify(who)
  10. track(name, props?)
  11. reportError(error, info?)
  12. Las demás
  13. Versiones (releases)
  14. Apps de una sola página
  15. Llamadas a tu API, y trazas
  16. Notas por framework
  17. Tamaño
  18. Apps móviles
  19. Sigue con

Esta página es para quien agrega Sypnia a una app web. @sypnia/browser funciona en cualquier app que corre en un navegador: React, Vue, Svelte, HTML simple y apps móviles hechas como vistas web. Tiene licencia MIT y es idéntico para el motor de código abierto y para Sypnia Cloud. Solo cambian dos cosas: a dónde envía y de dónde sale la llave.

Al final tendrás: errores, grabación de sesiones, rendimiento de páginas, llamadas a tu API lentas o fallidas, y clics de rabia y clics muertos llegando desde tu app, sin que nada de lo que una persona escribe salga de su navegador.

Instalar

npm

npm install @sypnia/browser
import { init } from '@sypnia/browser';

init({ project: 'YOUR_PROJECT_KEY' });

Guía de inicio completa

Reemplaza YOUR_PROJECT_KEY por la llave de ingesta de tu proyecto. Empieza por spk_, es pública y solo sirve para enviar datos.

Sypnia Cloud

La llave está en la página de tu proyecto en app.sypnia.com. No pones ninguna dirección: el SDK envía a https://ingest.sypnia.com.

src/main.ts
import { init } from '@sypnia/browser';

init({
  project: 'spk_7d1f0c9e4b8a2f6d3c5e1a9b0f4d8c2e',
  environment: location.hostname === 'shop.example' ? 'production' : 'development',
  release: '4f2a91c',
});

Llama a init una sola vez, apenas arranca tu app, antes de que pinte. Una segunda llamada no hace nada.

Con una etiqueta script, para apps sin paso de compilación

El motor sirve el SDK él mismo, así que no hay nada que instalar.

Sypnia Cloud

index.html
<script async src="https://ingest.sypnia.com/v1/sdk.js" data-project="spk_7d1f0c9e4b8a2f6d3c5e1a9b0f4d8c2e" data-release="4f2a91c"></script>

Pégala antes de </head>. La etiqueta arranca Sypnia sola, con estos atributos:

AtributoIgual a la opciónObligatorio
data-projectprojectsí
data-endpointendpointsolo con alojamiento propio
data-environmentenvironmentno
data-releasereleaseno

El script deja las mismas funciones en window.sypnia y luego lanza el evento sypnia:ready en window. Para usar cualquier otra opción, quita data-project y llama a init tú:

index.html
<script async src="https://ingest.sypnia.com/v1/sdk.js"></script>
<script>
  window.addEventListener('sypnia:ready', () => {
    sypnia.init({ project: 'spk_7d1f0c9e4b8a2f6d3c5e1a9b0f4d8c2e', maskAllText: true });
  });
</script>

Los errores lanzados antes de que el script cargue no se capturan. Es el precio de async; quita async si necesitas cubrir hasta el primer script de la página.

Comprueba que funciona

  1. Abre tu app y haz clic en algo.
  2. Abre las herramientas de desarrollo del navegador, pestaña Network (Red), y filtra por ingest.
  3. En menos de 10 segundos ves un POST a …/v1/ingest/events, respondido con 200 y un cuerpo como {"accepted": 4, "dropped": 0}.

Para leer lo que se envía, pon debug: true: el SDK imprime cada evento en la consola antes de enviarlo. Los cuerpos de más de 2.048 caracteres van comprimidos con gzip, así que la pestaña Network los muestra como binario; la consola los muestra tal cual. La lista completa de campos es el esquema de eventos.

Qué se captura sin escribir código

QuéCómoEvento
SesionesUna por visita, compartida por todas las pestañas, que termina tras 30 minutos sin actividad.session_start
PáginasCargas de página y navegaciones dentro de la app, tiempo en la página y hasta dónde se bajó.page_view, page_leave
ClicsCada clic, descrito en palabras: la etiqueta del control, su clase y dónde está. Nunca el valor de un campo.click
Clics de rabia3 clics o más a menos de 30 px y 1 segundo uno de otro.rage_click
Clics muertosUn clic en algo clicable, tras el cual no pasa nada durante 1 segundo.dead_click
ErroresErrores sin capturar y promesas rechazadas sin manejador, con su pila.error
Llamadas a la APILlamadas fetch y XMLHttpRequest a tu propio origen: método, ruta, estado, duración. En una llamada fallida, el código de error y el comienzo del mensaje de una respuesta JSON. Nunca un cuerpo.request
RendimientoLCP, INP, CLS y TTFB de cada página, con el elemento detrás de cada uno.vital
Fallos de formularioUn formulario que el navegador se negó a enviar, con la etiqueta del campo y el motivo.form_invalid
GrabaciónLa sesión como la vio la persona, en toda sesión donde algo sale mal y en una parte de las demás.se sube aparte
Imágenes para mapas de clicsUna captura enmascarada de una página, máximo una por ruta y cinco por sesión, en la mitad de las sesiones.se sube aparte

Lo que cada regla significa para quien lee un problema está en Eventos, Clics de rabia y clics muertos y Rendimiento.

Ruido que el SDK deja fuera

  • Errores lanzados por extensiones del navegador, y por código de billeteras o de vistas web inyectado en la página.
  • Errores cuya pila está entera en scripts de otros orígenes. Dile al SDK cuál es tu CDN con appFrames.
  • Script error. sin detalle, y el aviso ResizeObserver loop.
  • El mismo error otra vez dentro de 5 segundos, y más de 20 errores en un minuto.

Lo que no hace

No pone cookies. No lee ningún valor escrito. No modifica console. Guarda dos ids en localStorage (sypnia:session, sypnia:device), una decisión de grabación (sypnia:replay) y, si alguien se excluye, sypnia:off. Cada punto de entrada está envuelto para que un fallo dentro del SDK nunca llegue a tu app.

init(options)

TypeScript
function init(options: InitOptions): void
OpciónTipoPor defectoQué hace
projectstringobligatoriaLa llave de ingesta del proyecto, spk_…. Sin ella el SDK no hace nada e imprime un solo aviso.
endpointstring'https://ingest.sypnia.com'A dónde enviar. La URL base de un motor con alojamiento propio, o una ruta de tu propio dominio que rediriges hacia él (mira Solución de problemas).
environmentstring, de 1 a 40 caracteres'production'El entorno. Las alertas y el resumen diario solo cubren production.
releasestring, hasta 40 caracteresningunoLa versión (release): usa el commit corto de git. Debe ser el mismo texto con el que subes los source maps.
enabledbooleantruefalse deja el SDK sin efecto. Úsalo en pruebas.
debugbooleanfalseImprime en la consola cada evento, y cada decisión de no enviar uno.
ignoreRoutes(string | RegExp)[][]Rutas donde el SDK no captura nada. Un texto cubre la ruta y todo lo que cuelga de ella: '/admin' cubre /admin/users.
routeFor(pathname: string) => stringla regla incluidaTu propia forma de convertir una ruta con ids en una ruta genérica. La regla incluida reemplaza por :id los segmentos que son todo dígitos, un UUID, 16 o más caracteres hex, un token de 20 caracteres o más con un dígito, o que contienen %.
hashRoutingbooleanfalsetrue trata el hash como la ruta, para apps que navegan con #/checkout.
capture.errorsbooleantrueErrores sin capturar y rechazos sin manejar. reportError funciona igual.
capture.clicksbooleantrueClics, clics de rabia y clics muertos.
capture.requestsbooleantrueLlamadas a la API, y los encabezados de traza en ellas.
capture.requestFailureDetailbooleantrueLee code y el mensaje de la respuesta JSON de una llamada fallida (estado 400 o más). false registra solo el estado.
capture.vitalsbooleantrueLCP, INP, CLS, TTFB y FCP.
capture.formsbooleantrueFallos de validación de formularios.
traceTargets(string | RegExp)[][]Direcciones fuera de tu origen cuyas llamadas se registran y reciben los encabezados de traza. Un texto coincide con el comienzo de la URL. Tu propio origen siempre está incluido.
recordTargets(string | RegExp)[][]Direcciones fuera de tu origen cuyas llamadas se registran sin agregar ningún encabezado. Para APIs que no controlas.
ignoreRequests(string | RegExp)[][]Llamadas que nunca se registran. Las llamadas a Sypnia nunca se registran.
ignoreErrors(string | RegExp)[][]Los errores cuyo mensaje coincide no se envían. Un texto coincide en cualquier parte del mensaje.
appFrames(string | RegExp)[][]Direcciones de scripts que son tu código aunque se sirvan desde otro origen, como tu CDN.
maskAllTextbooleanfalseEnmascara todo el texto de todas las páginas en grabaciones y capturas, y no envía etiqueta de clic, contexto ni nombre de campo. Mira Privacidad y enmascarado.
maskSelectorstring (selector CSS)ningunoElementos a enmascarar, además de [data-sypnia-mask].
blockSelectorstring (selector CSS)ningunoElementos que se dejan fuera de las grabaciones, además de [data-sypnia-block], iframe y video.
replayfalse | { blockedRoutes?: (string | RegExp)[] }{}false nunca carga la grabadora. blockedRoutes son rutas donde no se graba nada, además de la lista del proyecto. Cuántas sesiones se graban es un ajuste del proyecto, no una opción: mira Muestreo y cuotas.
snapshotsbooleantrueCapturas de página para los mapas de clics.
beforeSend(event) => event | nullningunoSe llama con cada evento antes de encolarlo. Devuélvelo, cambiado o no, para enviarlo; devuelve null para descartarlo. No se llama para el contenido de la grabación.

Límites que no son opciones: un lote cada 10 segundos o al llegar a 50 eventos, máximo 200 eventos y 40.800 caracteres por lote, una cola de 500 eventos en memoria, una sesión termina tras 30 minutos sin actividad. Están en el esquema de eventos.

Las funciones que llamas tú

identify(who)

Dice quién es la persona. Llámala cuando alguien inicia sesión y cuando tu app carga con alguien que ya había iniciado; llama a identify(null) cuando cierra sesión.

src/auth.ts
import { identify } from '@sypnia/browser';

identify({
  person: { id: 'u_1042', name: 'Ada Park', email: 'ada@example.com' },
  account: { id: 'acc_77', name: 'Corner Café' },
});

Solo person.id es obligatorio. Los nombres y correos son datos personales y se guardan solo si los envías. Las reglas están en Identificar personas.

track(name, props?)

Envía un evento propio: algo que importa en tu app y que Sypnia no puede ver por sí solo.

src/checkout/coupon.ts
import { track } from '@sypnia/browser';

track('coupon_applied', { code: 'SPRING10', discount_cents: 640, first_order: false });
Límite
nameDe 1 a 80 caracteres
propsHasta 20. Un nombre tiene máximo 40 caracteres. Un valor es un texto de máximo 200 caracteres, un número finito, un booleano o null. Los objetos y las listas se quitan.

Los eventos propios aparecen en la línea de tiempo de la sesión. No cuentan para el plan. Nunca pongas en una propiedad lo que una persona escribió.

reportError(error, info?)

Reporta un error que tu código capturó. Los errores que nadie captura se reportan sin esto.

src/checkout/checkout.tsx
import { reportError } from '@sypnia/browser';

try {
  await confirmPayment(cart);
} catch (error) {
  reportError(error);
  showMessage('No pudimos tomar el pago. No se cobró nada.');
}
infoTipoPor defectoSignificado
source'manual' | 'boundary''manual'Usa 'boundary' desde un límite de errores de tu framework.
digeststring, hasta 100 caracteresningunoEl id que tu framework le dio al error, si lo hay.

Lo que no es un Error se convierte en uno, para que siempre haya un mensaje. Los límites de frecuencia y de repetición de arriba también aplican aquí.

Las demás

FunciónQué hace
flush(): Promise<void>Envía ahora lo que está esperando. El SDK ya lo hace cuando la pestaña se oculta o se cierra.
getSessionId(): string | nullEl id de la sesión actual, 32 caracteres hex, o null cuando no hay. Ponlo en una solicitud de soporte para encontrar la sesión después.
optOut(): voidDetiene todo en este navegador y lo recuerda (localStorage, sypnia:off). Úsala para una persona que rechaza la analítica, y en pruebas de extremo a extremo.
optIn(): voidDeshace optOut.

Versiones (releases)

Pon en release el commit corto de git de la compilación. La mayoría de empaquetadores puede inyectarlo:

vite.config.ts
import { execSync } from 'node:child_process';
import { defineConfig } from 'vite';

export default defineConfig({
  build: { sourcemap: 'hidden' },
  define: {
    __RELEASE__: JSON.stringify(execSync('git rev-parse --short HEAD').toString().trim()),
  },
});
src/main.ts
declare const __RELEASE__: string;

init({ project: 'spk_7d1f0c9e4b8a2f6d3c5e1a9b0f4d8c2e', release: __RELEASE__ });

Con una versión, un problema puede decir «desde el cambio de ayer». Con los source maps de esa versión, su pila muestra src/checkout/checkout.tsx:142 en vez de checkout-3f9c.js:1:48211. Súbelos en tu compilación: Source maps en CI.

Apps de una sola página

No hay nada que hacer. El SDK sigue la History API, así que cada navegación de un enrutador del lado del cliente es una vista de página, e INP y CLS se miden por página. Un cambio solo de consulta o de hash no es una vista de página; pon hashRouting: true si tu enrutador vive en el hash.

Llamadas a tu API, y trazas

Cada llamada registrada recibe un id de traza. En las llamadas a tu propio origen, y a traceTargets, el SDK agrega dos encabezados:

EncabezadoValorPara qué
traceparent00-<id de traza>-<id de span>-01, el formato W3CTu servidor continúa la misma traza.
x-sypnia-sessionEl id de la sesiónLa parte del servidor se une a la sesión.

Los encabezados que tu código ya puso nunca se reemplazan. Si tu API vive en otro origen, lístala y permite los dos encabezados en su respuesta CORS:

src/main.ts
init({
  project: 'spk_7d1f0c9e4b8a2f6d3c5e1a9b0f4d8c2e',
  traceTargets: ['https://api.shop.example'],
});
HTTP
Access-Control-Allow-Headers: content-type, authorization, traceparent, x-sypnia-session

El lado del servidor está en Node, Next.js y OpenTelemetry.

Notas por framework

La instalación es igual en todos: init una vez, antes de que la app pinte. Cambia dónde se entregan los errores que el framework captura.

React

React captura los errores lanzados al pintar. Repórtalos desde tu límite de errores:

src/ErrorBoundary.tsx
import { Component, type ReactNode } from 'react';
import { reportError } from '@sypnia/browser';

export class ErrorBoundary extends Component<{ children: ReactNode }, { failed: boolean }> {
  state = { failed: false };
  static getDerivedStateFromError() {
    return { failed: true };
  }
  componentDidCatch(error: Error) {
    reportError(error, { source: 'boundary' });
  }
  render() {
    return this.state.failed ? <p>Algo salió mal. Recarga la página.</p> : this.props.children;
  }
}

En React 19 puedes pasar onCaughtError y onUncaughtError a createRoot y llamar a reportError ahí. Para Next.js usa @sypnia/next.

Tamaño

Estos son presupuestos con los que el SDK se compromete, y que su compilación revisa en cada versión:

PartePresupuestoCuándo carga
El SDK (@sypnia/browser, y sdk.js)menos de 20 kB con gzipCon tu app.
La grabadora, para grabaciones y capturasmenos de 80 kB con gzipDespués, en su propio archivo, cuando el navegador está libre. Nunca con replay: false y snapshots: false.

Arrancar el SDK solo hace trabajo barato antes de que tu app pinte: instala sus escuchas y envía la vista de página. La medición de rendimiento y la grabadora empiezan cuando el navegador está libre.

Apps móviles

Una app hecha como vista web (Capacitor, Cordova, una app web envuelta) funciona con este SDK tal cual. Los SDK nativos de iOS y Android están Planeado; mira Planeado.

Sigue con

Secciones

Empieza aquíQué es Sypnia, cómo funciona, qué es código abierto y qué es la nube de pago, y las dos maneras de recibir tu primer problema en palabras claras.ConceptosLas diez ideas de las que está hecho Sypnia, cada una definida con precisión, desde un proyecto y sus llaves hasta los problemas, las trazas y las alertas.SDKCómo envía tu app los datos a Sypnia. Un SDK para el navegador, uno para Node, uno para Next.js, y la entrada de OpenTelemetry para cualquier otro backend.El agenteCómo analiza Sypnia un problema, qué escribe, qué le envía a un modelo y qué nunca hace.MCP y skillsConecta tu agente de código a Sypnia para que pregunte qué está fallando en producción, lea lo que necesita para arreglarlo y configure Sypnia por ti.Referencia de la APILa API HTTP de Sypnia: una sola API para el motor de código abierto y para Sypnia Cloud, con cada endpoint, parámetro, respuesta y error.Referencia de la CLIEl comando sypnia: cómo instalarlo, qué variables lee, qué significan sus códigos de salida y dónde está documentado cada comando.Alojamiento propioQué corres cuando alojas tú mismo el motor de Sypnia, qué necesitas, cuánto cuesta y qué no tienes frente a Sypnia Cloud.Cómo está construido el motorTodo el motor de Sypnia en una página, desde un clic en tu app hasta la frase que lee tu agente de código, con las reglas de diseño y el código que las sostiene.Sypnia CloudCómo funciona el servicio pago, desde las organizaciones y los roles hasta los planes, los límites, la facturación, dónde viven tus datos, la GitHub App y el soporte.Privacidad y seguridadQué recoge Sypnia de tu app y de sus usuarios, qué no recoge nunca, cómo funciona el enmascarado, cómo eliminar datos y cómo se protege el servicio.LicenciasQué licencia cubre cada parte de Sypnia, qué puedes hacer con ella, cómo se puede usar el nombre, y los términos de una contribución.GuíasRecetas paso a paso para las formas comunes de usar Sypnia, desde apps hechas con constructores de IA y Next.js en Vercel hasta Supabase, source maps en CI, correos de alerta desde tu propio motor, y venir desde Sentry.ReferenciaLas páginas donde se consulta, desde el esquema de eventos y el glosario hasta lo planeado, el registro de cambios y las preguntas frecuentes.
↑↓ para moverte↵ para abrirEsc para cerrar