Cualquier sitio web

Instalar npm install @blipit/browser

El SDK de navegador de Blipit pesa 10 KB. Captura los errores no capturados, los rechazos de promesas no gestionados y las peticiones fallidas, guarda los clics y las peticiones que llevaron a cada error, registra las web vitals, pone un botón Reportar un error en cada página y puede grabar un session replay cuando ocurre un error. Instálalo desde npm en una app empaquetada, o añade una etiqueta script a cualquier página.

Pégalo en Claude Code, Cursor o cualquier asistente de programación con IA. Incluye los pasos y el código. En app.blipit.io, en Claves de API, el mismo prompt viene con tu clave ya puesta.
Vídeo: instalar Blipit en cualquier stack, desde 0:32

1Obtén tus claves

Inicia sesión en app.blipit.io y abre Claves API en la barra lateral y luego tu proyecto. Cada proyecto tiene dos claves. La clave pública empieza por blipit_pk_: va en el código del navegador y de las apps, solo puede enviar eventos y cualquiera puede verla sin riesgo. La clave secreta empieza por blipit_sk_: se queda en tu servidor o en Odoo, nunca en un navegador, porque también puede leer y cambiar incidencias. La clave secreta solo se muestra una vez, justo al crearla, así que cópiala entonces; si la pierdes, pulsa Crear una nueva clave secreta y la anterior deja de funcionar al instante. Algunos SDKs también necesitan el id del proyecto, que aparece en la misma página.

Claves API en app.blipit.io: la clave pública (blipit_pk_) para el código del navegador y la clave secreta (blipit_sk_) para servidores y Odoo.
Claves API en app.blipit.io: la clave pública (blipit_pk_) para el código del navegador y la clave secreta (blipit_sk_) para servidores y Odoo.
Una nueva clave secreta se muestra una sola vez. Cópiala ahora: se guarda con hash y no se puede volver a mostrar.
Una nueva clave secreta se muestra una sola vez. Cópiala ahora: se guarda con hash y no se puede volver a mostrar.

2Con npm

Llama a init una vez en tu archivo de entrada, antes de que la app se renderice, con la clave pública. Con Vite (React, Vue, Svelte), guarda la clave en .env como VITE_BLIPIT_KEY; solo las variables VITE_ llegan al navegador, y el servidor de desarrollo lee .env solo al arrancar.

sh
npm install @blipit/browser
.env
VITE_BLIPIT_KEY=blipit_pk_your_public_key
src/main.js
import * as Blipit from "@blipit/browser";

Blipit.init({
  key: import.meta.env.VITE_BLIPIT_KEY,
  environment: import.meta.env.MODE,
  release: "2026.09.28",
  replay: { onErrorSampleRate: 1 },
});

3Sin bundler: una etiqueta script

Pega esto en el <head> de cada página, o en el espacio para código personalizado de tu plataforma, con tu clave pública escrita. No pasa nada: la clave pública solo puede enviar eventos.

html
<script src="https://blipit.io/sdk/blipit.js"></script>
<script>
  Blipit.init({ key: "blipit_pk_your_public_key", environment: "production", release: "2026.09.28", replay: { onErrorSampleRate: 1 } });
</script>

4Mantén las claves fuera de git

Guarda las claves en variables de entorno o en los ajustes de secretos de tu hosting, nunca en código que subas con commit, y añade tus archivos .env a .gitignore. Una clave pública en una página web es normal. Si alguna vez una clave secreta acaba en git, en una página pública, en una captura o en un chat, abre Claves API, pulsa Crear una nueva clave secreta y pega la nueva clave donde se usaba la anterior: la clave anterior deja de funcionar al instante.

.gitignore
.env
.env.local
.env.*.local

5Dile a Blipit quién es el usuario (opcional)

Tras el inicio de sesión, adjunta el usuario para que las incidencias muestren quién se vio afectado y los replays puedan buscarse por usuario.

js
Blipit.setUser({ id: "42", email: "ana@example.com" });

6React, Vue, Angular y Svelte: reporta los errores capturados

Los frameworks capturan los errores dentro de los componentes antes de que el navegador los vea, así que pásalos también a Blipit. Los errores no capturados en cualquier otro sitio se reportan solos.

React 19 (src/main.tsx)
createRoot(document.getElementById("root")!, {
  onCaughtError: (error) => Blipit.captureException(error),
  onUncaughtError: (error) => Blipit.captureException(error),
}).render(<App />);
O, React 18 y anteriores: un error boundary
class ErrorBoundary extends React.Component<{ children: React.ReactNode }, { failed: boolean }> {
  state = { failed: false };
  static getDerivedStateFromError() {
    return { failed: true };
  }
  componentDidCatch(error: Error) {
    Blipit.captureException(error);
  }
  render() {
    return this.state.failed ? <p>Something went wrong.</p> : this.props.children;
  }
}
Vue (src/main.ts)
const app = createApp(App);
app.config.errorHandler = (err) => Blipit.captureException(err);
app.mount("#app");
Angular (app.config.ts)
import { ErrorHandler } from "@angular/core";
import * as Blipit from "@blipit/browser";

class BlipitErrorHandler implements ErrorHandler {
  handleError(error: unknown) {
    Blipit.captureException(error);
    console.error(error);
  }
}

export const appConfig = { providers: [{ provide: ErrorHandler, useClass: BlipitErrorHandler }] };
SvelteKit (src/hooks.client.ts)
import * as Blipit from "@blipit/browser";
import type { HandleClientError } from "@sveltejs/kit";

export const handleError: HandleClientError = ({ error }) => {
  Blipit.captureException(error);
};

7Informes de errores: el botón Reportar un error

En cuanto el SDK arranca con tu clave pública, aparece un botón Reportar un error en la esquina inferior derecha de cada página, en el idioma del visitante. Un clic abre el formulario de reporte: una captura de la página para marcar, un selector de elementos, una grabación de pantalla opcional y un título y una descripción. Cambia la posición, el estilo, el texto, el color y el atajo de teclado en el código, como se muestra abajo, o para todos tus sitios a la vez en app.blipit.io, Ajustes del proyecto, Widget de informes de errores; las opciones del código tienen prioridad. La guía del botón de informes de errores muestra cada opción con capturas y una demo en vivo.

js
Blipit.init({
  key: import.meta.env.VITE_BLIPIT_KEY,
  feedbackWidget: {
    position: "bottom-left",
    style: "icon",
    text: "Report Issue",
    color: "#E11D48",
    shortcut: "ctrl+shift+b",
  },
});
El botón Reportar un error por defecto, abajo a la derecha.
El botón Reportar un error por defecto, abajo a la derecha.
El formulario de reporte: una captura marcada, el título y lo que pasó.
El formulario de reporte: una captura marcada, el título y lo que pasó.

8Abre el formulario de reporte desde tu propio botón

Para poner un botón Reportar un error en tu propio encabezado o menú, usa el oficial: Blipit.reportButton() devuelve un botón listo con el icono de Blipit y Reportar un error en el idioma del visitante, y las apps de React pueden mostrar <BlipitReportButton /> desde @blipit/nextjs/react (npm install @blipit/nextjs). ¿Prefieres tu propio diseño? Llama a openReport() desde cualquier manejador de clic, o a attachReport(element) para conectar un elemento que ya existe. En ambos casos el formulario se abre igual que desde el botón flotante. El icono de Blipit solo puede usarse junto a Reportar un error, como muestra el botón oficial.

Botón oficial, HTML simple
<nav id="help-menu"></nav>
<script>
  document.getElementById("help-menu").append(Blipit.reportButton());
</script>
Botón oficial, React
import { BlipitReportButton } from "@blipit/nextjs/react";

export function Header() {
  return (
    <header>
      <a href="/">Acme</a>
      <BlipitReportButton variant="outline" size="sm" />
    </header>
  );
}
Botón oficial, Vue
<script setup>
import { onMounted, ref } from "vue";
import { reportButton } from "@blipit/browser";

const slot = ref();
onMounted(() => slot.value.append(reportButton({ variant: "outline", size: "sm" })));
</script>

<template>
  <span ref="slot"></span>
</template>
HTML simple
<button id="report-issue">Report Issue</button>
<script>
  Blipit.attachReport(document.getElementById("report-issue"));
</script>

<button onclick="Blipit.openReport()">Report Issue</button>
React
import { openReport } from "@blipit/browser";

export function ReportIssue() {
  return <button onClick={() => openReport()}>Report Issue</button>;
}
Vue
<script setup>
import { openReport } from "@blipit/browser";
</script>

<template>
  <button @click="openReport()">Report Issue</button>
</template>
El botón oficial Reportar un error en el encabezado de un sitio.
El botón oficial Reportar un error en el encabezado de un sitio.
Un botón personalizado Report Issue en la cabecera de la página abre el formulario de reporte de Blipit.
Un botón personalizado Report Issue en la cabecera de la página abre el formulario de reporte de Blipit.

9Ocultar el botón por defecto

Para quedarte solo con tu propio botón, desactiva el flotante con feedbackWidget: false en el código (feedbackWidget={false} en <Blipit />), o desactiva Mostrar el botón de informes en los ajustes del Widget de informes de errores del proyecto para ocultarlo en todos los sitios que usan la clave. openReport() y attachReport() siguen funcionando en cualquier caso.

js
Blipit.init({ key: import.meta.env.VITE_BLIPIT_KEY, feedbackWidget: false });

10Rellena el formulario de reporte y añade contexto

Llama a setUser tras el inicio de sesión: el nombre y el correo de quien reporta se rellenan solos, y recibe un correo cuando respondes o cambias el estado. setReportMetadata añade tus propios campos, como el plan o el tamaño del carrito, a cada reporte; se ejecuta cuando se envía un reporte, así que los valores están al día.

js
Blipit.setUser({ id: "42", username: "Ana Lima", email: "ana@example.com" });

Blipit.setReportMetadata(() => ({ plan: "pro", cartItems: cart.length }));

11Todas las opciones y funciones

  • key: la clave pública (blipit_pk_). Obligatoria.
  • environment y release: se muestran en cada evento; release habilita las regresiones y los source maps. environment toma por defecto production.
  • debug: true registra en la consola lo que hace el SDK, con líneas que empiezan por [blipit].
  • sampleRate (de 0 a 1), ignoreErrors (cadenas o patrones) y beforeSend (edita un evento, o devuelve null para descartarlo) controlan lo que se envía. autoMuteExtensions (activado por defecto) descarta los errores que solo vienen de extensiones del navegador.
  • webVitals (activado por defecto), replay ({ sessionSampleRate, onErrorSampleRate }) y autoSessionTracking (tasas sin fallos, necesita release).
  • feedbackWidget: false oculta el botón Reportar un error, o un objeto con position, style, text, color, font, match y shortcut lo cambia. theme: "light", "dark" o "auto" define el tema del formulario de reporte.
  • user ({ id, name, email }) y company (un nombre o { id, name }) rellenan el formulario de reporte y se añaden a los reportes.
  • endpoint: solo para una ingesta self-hosted; el valor por defecto es https://in.blipit.io/api/v1/events.
  • Funciones: captureException(error), captureMessage(text, level), setUser, setTag(key, value), addBreadcrumb({ category, message }), openReport(), attachReport(element), reportButton(options), updateWidget(options), setReportMetadata(fn), showFeedback() y flush(), que devuelve una promesa cuando se han enviado los eventos en cola.
  • Los cambios en los ajustes del widget hechos en el panel llegan a los navegadores en menos de una hora, porque el SDK los guarda ese tiempo; una ventana privada muestra el cambio al instante.

12Comprueba que funciona

Recarga tu sitio. El botón Reportar un error aparece en la esquina inferior derecha y, en menos de un minuto, la vista de página aparece en Web vitals en app.blipit.io. Después envía un evento de prueba: llama una vez a captureMessage desde tu código o, con la etiqueta script, ejecuta la línea de abajo en la consola del navegador. Aparece en Incidencias en unos segundos.

js
Blipit.captureMessage("Hello from " + location.host, "info");

13Si el botón o los eventos no aparecen

  • Abre la consola del navegador y busca las líneas que empiezan por [blipit]. Activa debug (debug: true en init, o debug en <Blipit />) para ver si el botón se mostró, se desactivó en el código o lo ocultó el ajuste del proyecto.
  • Next.js solo envía al navegador las variables cuyo nombre empieza por NEXT_PUBLIC_, así que usa NEXT_PUBLIC_BLIPIT_KEY. Vite solo envía las variables VITE_, así que usa VITE_BLIPIT_KEY. Con cualquier otro nombre la clave queda vacía en el navegador y Blipit no arranca.
  • Reinicia el servidor de desarrollo después de añadir o cambiar .env o .env.local. Solo los lee al arrancar.
  • En Vercel o en cualquier otro hosting, añade la misma variable en las variables de entorno del proyecto y vuelve a desplegar. Los valores NEXT_PUBLIC_ y VITE_ se escriben en el build, así que un despliegue en marcha nunca ve un valor añadido después.
  • Usa la clave pública (blipit_pk_). Una clave secreta (blipit_sk_) se rechaza en el navegador con un error en la consola; si alguna vez estuvo en una página, crea una nueva clave secreta.
  • En Next.js, <Blipit /> va en el app/layout.tsx raíz (o en pages/_app.tsx) para que se ejecute en todas las páginas. En otras apps, llama a init una vez en el archivo de entrada, antes de que la app se renderice.
  • Mostrar el botón de informes tiene que estar activado en app.blipit.io, Ajustes del proyecto, Widget de informes de errores, y tu código no debe pasar feedbackWidget: false. El SDK guarda los ajustes del proyecto hasta una hora, así que prueba los cambios en una ventana privada.
  • Los bloqueadores de anuncios y las extensiones de privacidad pueden bloquear in.blipit.io. Prueba en una ventana privada con las extensiones desactivadas.
  • Si tu sitio envía una Content Security Policy, permite script-src https://blipit.io, connect-src https://in.blipit.io, img-src data: y media-src blob:. El editor del reporte se carga desde blipit.io/sdk con el primer clic, la captura se dibuja a partir de una imagen data: y las grabaciones de pantalla también se suben a in.blipit.io. Con debug activado, la consola indica cuándo la política bloqueó la captura. Para que las grabaciones de pantalla tengan voz, la cabecera Permissions-Policy de tu sitio debe permitir microphone=(self), y display-capture=(self) para grabar la pantalla; con microphone=() las grabaciones funcionan sin sonido.
  • Comprueba qué versión está instalada con npm ls @blipit/browser @blipit/nextjs (o pnpm list @blipit/browser @blipit/nextjs) y compárala con el registro de cambios. pnpm 11 espera un día antes de instalar una versión nueva (minimum-release-age), así que el día del lanzamiento pnpm add instala sin avisar la versión anterior. Para obtener la nueva enseguida: pnpm add @blipit/browser@<version> @blipit/nextjs@<version> --config.minimum-release-age=0.
  • ¿Sigue sin funcionar? Escribe a support@blipit.io con las líneas [blipit] de la consola.

Conviene saber

  • Opciones: sampleRate (0 a 1), ignoreErrors (cadenas o patrones), beforeSend para descartar o editar un evento, maxBreadcrumbs, webVitals (activado por defecto), autoSessionTracking para tasas sin fallos (necesita release).
  • blipit.io/sdk/blipit.js siempre sirve la última versión (0.3.23). Las versiones fijas están en blipit.io/sdk/0.3.23/blipit.js si quieres controlar las actualizaciones.
  • Si tu sitio envía una Content Security Policy, permite script-src https://blipit.io (la etiqueta script, y el editor del reporte y el complemento de replay, que se cargan desde blipit.io/sdk/<version>/ la primera vez que se usan), connect-src https://in.blipit.io (los eventos, las capturas y las grabaciones de pantalla van todos a in.blipit.io), img-src data: (la captura se dibuja a partir de una imagen de la página) y media-src blob: (las grabaciones se reproducen en el reporte). La captura vuelve a cargar las imágenes y fuentes de la página, así que sus hosts también deben estar en connect-src; si no, quedan en blanco. No hace falta cambiar style-src. Con la etiqueta script, llama a Blipit.init desde tu propio archivo .js o da un nonce al script en línea, porque una política estricta bloquea los scripts en línea. Para que las grabaciones de pantalla tengan voz, la cabecera Permissions-Policy de tu sitio debe permitir microphone=(self), y display-capture=(self) para grabar la pantalla; con microphone=() las grabaciones funcionan sin sonido.
  • Mantener Blipit actualizado: la guía Mantener Blipit actualizado (docs.blipit.io/updates) explica el banner de actualización, los correos para versiones importantes, el aviso en tu consola de desarrollo y el comando de actualización para esta plataforma.
  • Un proyecto por app y plataforma: cada proyecto elige su plataforma al crearse (Android, iOS, React Native, Flutter, Web, Backend u Odoo) y Blipit rechaza con un error claro los datos de cualquier otra plataforma, así que una app de iOS y una de Android necesitan dos proyectos con dos claves. Las versiones, las compilaciones, las tasas de fallos y las builds de tienda son distintas en cada plataforma, y mezclarlas en un proyecto hace que todas sean incorrectas. Un proyecto Web también acepta la parte de servidor de la misma app web (el servidor de Next.js o Node), y un proyecto de React Native o Flutter también acepta sus propios informes de fallos nativos de Android e iOS.

¿Atascado? Escribe a support@blipit.io. Las claves y el id de cada proyecto están en Claves API en app.blipit.io.