SDK del navegador

Antes de instalar

Obtén del responsable los identificadores públicos, el origen del collector y una política local revisada. La clave pública identifica y limita el proyecto; no autoriza lecturas privadas. La instalación no habilita automáticamente el proyecto ni sustituye su política central.

Esta edición se distribuye como archivo privado ESM y un IIFE para HTML. No uses una instrucción de instalación desde un registro público que tu equipo no haya publicado.

# Recibe el archivo y su SHA-256 por el canal autorizado de tu equipo.
# Guarda el archivo verificado en ./distribuciones/.
npm install --ignore-scripts ./distribuciones/reks-sdk-browser-0.4.0.tgz

Un mínimo que permite sólo lo revisado

import { installBugSDK } from "@reks/sdk-browser";

// Sustituye estos identificadores y orígenes por tu configuración pública aprobada.
export function startReks() {
  return installBugSDK({
    organizationId: "TU_ORGANIZACION",
    projectId: "TU_PROYECTO",
    publicKey: "TU_CLAVE_PUBLICA_DE_PROYECTO",
    environment: "preview",
    serviceId: "web",
    releaseId: "TU_RELEASE",
    collectorOrigin: "https://collector.example.test",
    privacyPolicy: {
      policyVersion: 1,
      projectId: "TU_PROYECTO",
      allowedRouteTemplates: ["/panel"],
      prohibitedRoutePrefixes: ["/privado"],
      allowedActionSelectors: [],
      prohibitedSelectors: ["[data-reks-private]", "[data-client-signal-private]"],
    },
    currentRouteTemplate: () => location.pathname === "/panel" ? "/panel" : null,
    requestRouteTemplate: () => null, // Sin capturas de red no revisadas.
  });
}

const sdk = startReks();
// Conecta el router real si necesitas registrar una navegación permitida.
sdk.recordNavigation();
// Función local: el host DEBE llamarla antes de cambiar sesión/organización
// y al desmontar; no se ejecuta inmediatamente al instalar.
export function stopReks() { sdk.stop(); }

El ejemplo permite una plantilla fija, bloquea acciones DOM y no captura solicitudes de red. Amplía esa lista únicamente después de revisar cada ruta y selector. El router debe devolver una plantilla estable o null; no conviertas IDs, query strings o texto de una página en un evento.

Conecta stopReks a los eventos reales de desmontaje y cambio de identidad; el ejemplo no instala ese listener por ti. Una ruta prohibida bloquea nuevas capturas, pero no borra los eventos seguros ya encolados: si ese límite requiere vaciar memoria, llama stop() y reinstala deliberadamente después. Importar ESM durante SSR no accede al DOM. Instalar sin window devuelve un handle desactivado con reason=ssr. En servidor no compartas un handle de navegador entre solicitudes.

React, HTML y plantillas PHP

import { useEffect } from "react";
import { installBugSDK, type BugSDKConfig } from "@reks/sdk-browser";

type Props = {
  config: BugSDKConfig;
  // Función de tu aplicación: avisa ANTES del cambio real de identidad.
  subscribeBoundary: (stop: () => void) => () => void;
};
export function ReksCapture({ config, subscribeBoundary }: Props) {
  useEffect(() => {
    const sdk = installBugSDK(config);
    const unsubscribe = subscribeBoundary(() => sdk.stop());
    return () => { unsubscribe(); sdk.stop(); };
  }, [config, subscribeBoundary]);
  return null;
}
// Mantén ambas props estables para la misma identidad. El callback síncrono
// de tu auth/org detiene captura antes del cambio, aunque la URL no cambie.
// El cleanup de React es adicional; no sustituye ese límite real.

Config debe ser estable para una misma identidad. subscribeBoundary es una función de tu aplicación que notifica de forma síncrona antes del cambio real de sesión/organización; no basta con esperar al cleanup de un efecto. El teardown debe ocurrir antes de la reinstalación. React StrictMode puede montar y desmontar más de una vez; no lo resuelvas creando registros paralelos.

<!-- Copia el IIFE privado a una URL inmutable propia.
     Sustituye el integrity por el SHA-384 de SU manifiesto verificado. -->
<script defer src="/vendor/reks-bugs-0.4.0.js"
  integrity="SHA384_DEL_MANIFIESTO" crossorigin="anonymous"></script>
<script defer src="/vendor/reks-init.js"></script>
<script defer src="/assets/tu-aplicacion.js"></script>
<!-- reks-init.js usa ReksBugs.installBugSDK(configPublicaAprobada).
     No pongas credenciales de servidor en configPublicaAprobada. -->

El SDK actúa sobre el HTML resultante; no necesita ejecutarse dentro de PHP. Conserva el orden defer: SDK, inicialización local y aplicación. Los errores anteriores a instalar los hooks quedan fuera de cobertura. Para SRI entre orígenes necesitas CORS del servidor de assets. Revisa script-src para el asset y connect-src para el collector; no requiere unsafe-eval o unsafe-inline.

Logs explícitos con códigos estáticos

export const structuredLogs = {
  schemaVersion: 1,
  minLevel: "info",
  definitions: [{
    code: "panel_saved",
    category: "system",
    attributes: { result: { values: ["ok", "failed"] } },
  }],
} as const;
// Añade esta política revisada a privacyPolicy.structuredLogs.
// No se habilitan logs si esa política no existe.

import type { BugSDK } from "@reks/sdk-browser";

export async function recordSaved(sdk: BugSDK) {
  sdk.logger.info("panel_saved", { result: "ok" });
  // Un intento acotado. "sent" no significa salud de la aplicación.
  const result = await sdk.flush();
  return result; // "empty" | "sent" | "failed" | "closed"
}

La política instalada permite como máximo 64 códigos y 8 atributos por evento: enums estáticos, booleanos o enteros acotados. No aceptes mensajes libres, textos de error, stacks, cause, argumentos, cookies, headers, cuerpos ni un volcado de console. Sin structuredLogs, el logger no se habilita.

logger.captureException(error, code, attrs) es un log estructurado permitido. sdk.captureException(error) es una ocurrencia de error del navegador sin texto ni stack. No uses ambas antes de volver a lanzar un error global si eso duplica la misma observación; decide qué captura necesita tu aplicación.

Trazas y contexto sin autoridad implícita

sdk.startTrace(code, attributes?, parent?) devuelve una operación con logger, fetch y end. La propagación requiere un origen HTTPS exacto permitido por tracePropagationOrigins, rutas de origen/destino revisadas y requestRouteTemplate. Respeta un traceparent existente y no propaga identidad, baggage o cookies adicionales.

La operación sólo aplica mientras la plantilla actual coincide con la inicial. El host debe llamar end() al abandonar esa operación y stop() antes de un cambio de identidad; end()/stop() impiden volver a usarla. Una coincidencia de trace ID no concede lectura ni demuestra causalidad. Event IDs e idempotencia tampoco son una relación causal.

• Referencia de métodos y límitesAPIs de operación, políticas y entrega por SDK.

Cola, reintentos y fallo de plataforma

flush() devuelve empty, sent, failed o closed y hace un intento acotado. La visibilidad hidden/pagehide usa fetch keepalive; CSP, red, cierre o crash pueden perder datos. Un retry conserva el ID del lote y reconcilia duplicados; no hay entrega exactamente una vez.

enabled indica instalación activa. snapshot y diagnostics son contadores locales, no cobertura remota, salud de la aplicación o prueba de recepción. Si Reks falla, la aplicación debe seguir funcionando sin depender de esa entrega.

Logout, cambio de organización y desinstalación

1. Llama stop() al desmontar y antes de cambiar sesión, organización, proyecto o entorno, aunque la URL sea idéntica.
2. Destruye también el widget/bridge de esa identidad. No transfieras drafts o colas al siguiente usuario.
3. Instala explícitamente el nuevo SDK con su política revisada. El registro compartido impide instalaciones paralelas; no actualiza un SDK antiguo al cargar otro archivo.
4. Para retirarlo, stop(), elimina el init/import/script y su dependencia local cuando tu aplicación ya no lo use.

import type { BugSDK } from "@reks/sdk-browser";
export function pauseCapture(sdk: BugSDK, revision: number) {
  return sdk.applyCaptureConfig({
    schemaVersion: 1,
    revision,
    captureEnabled: false,
    sampleRate: 0,
  });
}
// Reduce-only. No amplía rutas, selectores ni permisos; no reactiva un handle
// detenido. El host aporta la configuración por un canal confiable.

applyCaptureConfig sólo reduce tasa o detiene captura desde un canal confiable del host. No hace polling remoto automático, no tiene una firma nueva implícita, no amplía rutas/selectores y no reactiva un handle detenido. Los counters acumulados no vuelven a cero por un cambio de tasa.