# 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: el motor de Sypnia (código abierto, en tu propia infraestructura) y Sypnia Cloud (servicio pago). Estado: al lanzar.  
Fuente: https://docs.sypnia.com/es/sdks/browser/

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**

```bash
npm install @sypnia/browser
```

```js
import { init } from '@sypnia/browser';

init({ project: 'YOUR_PROJECT_KEY' });
```

**pnpm**

```bash
pnpm add @sypnia/browser
```

```js
import { init } from '@sypnia/browser';

init({ project: 'YOUR_PROJECT_KEY' });
```

**yarn**

```bash
yarn add @sypnia/browser
```

```js
import { init } from '@sypnia/browser';

init({ project: 'YOUR_PROJECT_KEY' });
```

**bun**

```bash
bun add @sypnia/browser
```

```js
import { init } from '@sypnia/browser';

init({ project: 'YOUR_PROJECT_KEY' });
```

**script tag**

```html
<script async
  src="https://ingest.sypnia.com/v1/sdk.js"
  data-project="YOUR_PROJECT_KEY"></script>
```

Sin paso de compilación y sin llamar a `init`: pégala antes de `</head>`. La etiqueta inicia Sypnia con la llave que va en `data-project`.

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`

```ts
import { init } from '@sypnia/browser';

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

**Alojamiento propio**

Crea la llave con `sypnia project create` o con la [API](https://docs.sypnia.com/es/api/projects-keys-and-tokens), y apunta el SDK a la URL base de tu motor con `endpoint`.

`src/main.ts`

```ts
import { init } from '@sypnia/browser';

init({
  project: 'spk_7d1f0c9e4b8a2f6d3c5e1a9b0f4d8c2e',
  endpoint: 'https://sypnia.example.com',
  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`

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

**Alojamiento propio**

`index.html`

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

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

| Atributo           | Igual a la opción | Obligatorio                 |
| ------------------ | ----------------- | --------------------------- |
| `data-project`     | `project`         | sí                          |
| `data-endpoint`    | `endpoint`        | solo con alojamiento propio |
| `data-environment` | `environment`     | no                          |
| `data-release`     | `release`         | no                          |

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`

```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](https://docs.sypnia.com/es/reference/event-schema).

## Qué se captura sin escribir código

| Qué                          | Cómo                                                                                                                                                                                                 | Evento                    |
| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- |
| Sesiones                     | Una por visita, compartida por todas las pestañas, que termina tras 30 minutos sin actividad.                                                                                                        | `session_start`           |
| Páginas                      | Cargas de página y navegaciones dentro de la app, tiempo en la página y hasta dónde se bajó.                                                                                                         | `page_view`, `page_leave` |
| Clics                        | Cada clic, descrito en palabras: la etiqueta del control, su clase y dónde está. Nunca el valor de un campo.                                                                                         | `click`                   |
| Clics de rabia               | 3 clics o más a menos de 30 px y 1 segundo uno de otro.                                                                                                                                              | `rage_click`              |
| Clics muertos                | Un clic en algo clicable, tras el cual no pasa nada durante 1 segundo.                                                                                                                               | `dead_click`              |
| Errores                      | Errores sin capturar y promesas rechazadas sin manejador, con su pila.                                                                                                                               | `error`                   |
| Llamadas a la API            | Llamadas `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`                 |
| Rendimiento                  | LCP, INP, CLS y TTFB de cada página, con el elemento detrás de cada uno.                                                                                                                             | `vital`                   |
| Fallos de formulario         | Un formulario que el navegador se negó a enviar, con la etiqueta del campo y el motivo.                                                                                                              | `form_invalid`            |
| Grabación                    | La 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 clics | Una 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](https://docs.sypnia.com/es/concepts/events), [Clics de rabia y clics muertos](https://docs.sypnia.com/es/concepts/rage-and-dead-clicks) y [Rendimiento](https://docs.sypnia.com/es/concepts/performance).

### 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)`

```ts
function init(options: InitOptions): void
```

| Opción                         | Tipo                                                | Por defecto                   | Qué hace                                                                                                                                                                                                                                                                 |
| ------------------------------ | --------------------------------------------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `project`                      | `string`                                            | obligatoria                   | La llave de ingesta del proyecto, `spk_…`. Sin ella el SDK no hace nada e imprime un solo aviso.                                                                                                                                                                         |
| `endpoint`                     | `string`                                            | `'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](https://docs.sypnia.com/es/sdks/troubleshooting)).                                                                  |
| `environment`                  | `string`, de 1 a 40 caracteres                      | `'production'`                | El entorno. Las alertas y el resumen diario solo cubren `production`.                                                                                                                                                                                                    |
| `release`                      | `string`, hasta 40 caracteres                       | ninguno                       | La versión (release): usa el commit corto de git. Debe ser el mismo texto con el que subes los source maps.                                                                                                                                                              |
| `enabled`                      | `boolean`                                           | `true`                        | `false` deja el SDK sin efecto. Úsalo en pruebas.                                                                                                                                                                                                                        |
| `debug`                        | `boolean`                                           | `false`                       | Imprime 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) => string`                      | la regla incluida             | Tu 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 `%`.                      |
| `hashRouting`                  | `boolean`                                           | `false`                       | `true` trata el hash como la ruta, para apps que navegan con `#/checkout`.                                                                                                                                                                                               |
| `capture.errors`               | `boolean`                                           | `true`                        | Errores sin capturar y rechazos sin manejar. `reportError` funciona igual.                                                                                                                                                                                               |
| `capture.clicks`               | `boolean`                                           | `true`                        | Clics, clics de rabia y clics muertos.                                                                                                                                                                                                                                   |
| `capture.requests`             | `boolean`                                           | `true`                        | Llamadas a la API, y los encabezados de traza en ellas.                                                                                                                                                                                                                  |
| `capture.requestFailureDetail` | `boolean`                                           | `true`                        | Lee `code` y el mensaje de la respuesta JSON de una llamada fallida (estado 400 o más). `false` registra solo el estado.                                                                                                                                                 |
| `capture.vitals`               | `boolean`                                           | `true`                        | LCP, INP, CLS, TTFB y FCP.                                                                                                                                                                                                                                               |
| `capture.forms`                | `boolean`                                           | `true`                        | Fallos 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.                                                                                                                                                                                |
| `maskAllText`                  | `boolean`                                           | `false`                       | Enmascara 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](https://docs.sypnia.com/es/sdks/privacy-and-masking).                                                  |
| `maskSelector`                 | `string` (selector CSS)                             | ninguno                       | Elementos a enmascarar, además de `[data-sypnia-mask]`.                                                                                                                                                                                                                  |
| `blockSelector`                | `string` (selector CSS)                             | ninguno                       | Elementos que se dejan fuera de las grabaciones, además de `[data-sypnia-block]`, `iframe` y `video`.                                                                                                                                                                    |
| `replay`                       | `false \| { 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](https://docs.sypnia.com/es/sdks/sampling-and-quotas). |
| `snapshots`                    | `boolean`                                           | `true`                        | Capturas de página para los mapas de clics.                                                                                                                                                                                                                              |
| `beforeSend`                   | `(event) => event \| null`                          | ninguno                       | Se 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](https://docs.sypnia.com/es/reference/event-schema).

## 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`

```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](https://docs.sypnia.com/es/sdks/identifying-people).

### `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`

```ts
import { track } from '@sypnia/browser';

track('coupon_applied', { code: 'SPRING10', discount_cents: 640, first_order: false });
```

|         | Límite                                                                                                                                                                     |
| ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`  | De 1 a 80 caracteres                                                                                                                                                       |
| `props` | Hasta 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`

```ts
import { reportError } from '@sypnia/browser';

try {
  await confirmPayment(cart);
} catch (error) {
  reportError(error);
  showMessage('No pudimos tomar el pago. No se cobró nada.');
}
```

| `info`   | Tipo                           | Por defecto | Significado                                                  |
| -------- | ------------------------------ | ----------- | ------------------------------------------------------------ |
| `source` | `'manual' \| 'boundary'`       | `'manual'`  | Usa `'boundary'` desde un límite de errores de tu framework. |
| `digest` | `string`, hasta 100 caracteres | ninguno     | El 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ón                          | Qué 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 \| null` | El 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(): void`                 | Detiene 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(): void`                  | Deshace `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`

```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`

```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](https://docs.sypnia.com/es/guides/source-maps-in-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:

| Encabezado         | Valor                                              | Para qué                                  |
| ------------------ | -------------------------------------------------- | ----------------------------------------- |
| `traceparent`      | `00-<id de traza>-<id de span>-01`, el formato W3C | Tu servidor continúa la misma traza.      |
| `x-sypnia-session` | El id de la sesión                                 | La 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`

```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](https://docs.sypnia.com/es/sdks/node), [Next.js](https://docs.sypnia.com/es/sdks/nextjs) y [OpenTelemetry](https://docs.sypnia.com/es/sdks/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`

```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`](https://docs.sypnia.com/es/sdks/nextjs).

**Vue**

`src/main.ts`

```ts
import { createApp } from 'vue';
import { init, reportError } from '@sypnia/browser';
import App from './App.vue';

init({ project: 'spk_7d1f0c9e4b8a2f6d3c5e1a9b0f4d8c2e' });

const app = createApp(App);
app.config.errorHandler = (error) => {
  reportError(error, { source: 'boundary' });
  console.error(error);
};
app.mount('#app');
```

**Svelte**

En SvelteKit, arranca el SDK y entrega los errores en los hooks del cliente:

`src/hooks.client.ts`

```ts
import { init, reportError } from '@sypnia/browser';
import type { HandleClientError } from '@sveltejs/kit';

init({ project: 'spk_7d1f0c9e4b8a2f6d3c5e1a9b0f4d8c2e' });

export const handleError: HandleClientError = ({ error }) => {
  reportError(error, { source: 'boundary' });
};
```

En Svelte sin SvelteKit, llama a `init` en `src/main.ts` antes de `mount`.

**HTML simple**

Usa la etiqueta script de arriba. No hace falta nada más: cada carga de página es una vista de página, y los errores sin capturar se reportan.

`checkout.html`

```html
<script>
  window.addEventListener('sypnia:ready', () => {
    sypnia.identify({ person: { id: 'u_1042' } });
  });
</script>
```

## Tamaño

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

| Parte                                     | Presupuesto             | Cuándo carga                                                                                                   |
| ----------------------------------------- | ----------------------- | -------------------------------------------------------------------------------------------------------------- |
| El SDK (`@sypnia/browser`, y `sdk.js`)    | menos de 20 kB con gzip | Con tu app.                                                                                                    |
| La grabadora, para grabaciones y capturas | menos de 80 kB con gzip | Despué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](https://docs.sypnia.com/es/reference/planned).

## Sigue con
