@betaworks/insight (0.1.0)

Published 2026-11-19 09:54:39 +00:00 by betaworks

Installation

@betaworks:registry=
npm install @betaworks/insight@0.1.0
"@betaworks/insight": "0.1.0"

About this package

@betaworks/insight

Avhengighetsfri SDK for Betaworks Insight: produktanalyse, feilsporing og rådata (brede hendelser) i én pakke.

  • @betaworks/insight – nettleser
  • @betaworks/insight/node – Node-tjenester (Express, Socket.io)

Begge finnes som ESM og CommonJS.

Installasjon

Pakken ligger i Forgejo sitt npm-registry. Legg til i appens .npmrc:

@betaworks:registry=https://git.betaworks.no/api/packages/betaworks/npm/

Er pakken privat, trengs også et token med read:package:

//git.betaworks.no/api/packages/betaworks/npm/:_authToken=${FORGEJO_NPM_TOKEN}
npm install @betaworks/insight

Nettleser

import {
  init, track, identify, setContext, sessionHeaders, recordApi, recordSocket,
} from "@betaworks/insight";

init({
  key: "pub_xxx",                          // public_key fra prosjektet
  endpoint: "https://insight.betaworks.no",
  source: "web",                           // standard "web"
  release: "abc123",
  environment: "production",
});

identify("u_9f…");                         // pseudonym ID (HMAC), null ved utlogging
setContext({ role: "host", game: "123" }); // på alle senere hendelser; null fjerner
track("quiz_created", { questions: 10 });

// Koble API-kall og socket til fanen
fetch("/api/quiz", { headers: { ...sessionHeaders() } });
recordApi({ method: "GET", route: "/api/quiz/:id", status: 200, ms: 41 });
recordSocket({ event: "join_player", result: "ok", ms: 30 });

Automatisk:

  • Sidevisninger, også SPA-ruting (pushState/popstate).
  • Feil (onerror, unhandledrejection) og Web Vitals.
  • Klikk på button, a, [role=button], input[type=submit|button|checkbox|radio] og [data-insight]. Etiketten er data-insight, ellers aria-label, ellers synlig tekst (maks 60 tegn). Verdien i et felt sendes aldri. Elementer inni [data-insight-ignore] hoppes over.

Hver hendelse har session (fane-ID), uid, kontekst, source, release, env og enhetsinfo (screen, viewport, dpr, lang, tz, connection).

API

Funksjon
init(config) Kall én gang ved oppstart
track(name, props?) Egen hendelse
pageview(url?) Manuell sidevisning
captureException(err, context?) Feilrapport
identify(uid | null) Bruker-ID på senere hendelser
setContext(ctx) Slår sammen kontekst; null fjerner en nøkkel
getSessionId() Fane-ID (bare i minnet)
sessionHeaders() { "x-insight-session": id }, tomt før init
recordApi({method, route, status, ms, error?}) Ett API-kall (api)
recordSocket({event, result, ms?}) Én socket-hendelse (socket), result er "ok" eller en feilkode
flush() Send køen nå

Konfig

Felt Standard
key – Public key
endpoint – Basis-URL til Insight
source "web" Kilde
release – Versjon
environment – F.eks. production
autoPageviews true
autoErrors true
autoVitals true
autoClicks true
batchSize 20 Hendelser før flush
flushIntervalMs 5000

Node

const { createInsight } = require("@betaworks/insight/node"); // eller import

const insight = createInsight({
  endpoint: "https://insight.betaworks.no",
  key: process.env.INSIGHT_SECRET_KEY,   // secret_key, sendes i x-insight-key
  source: "mothership",
  release: process.env.GIT_SHA,
  environment: "production",
});

app.use(insight.expressMiddleware({ uid: (req) => req.insightUid }));

insight.track("game_created", { questions: 10 }, { uid, game: "123" });
insight.captureException(err, { game: "123", extra: { route: "/api/x" } });
insight.metric("event_loop_lag_ms", 3.2, { node: "alfa" });

process.on("SIGTERM", () => insight.shutdown());
  • expressMiddleware registrerer request ved res.finish: method, route (req.baseUrl + req.route.path, ellers "(ingen rute)", aldri rå URL), status, ms, session fra x-insight-session, uid fra opts.uid og error fra res.locals.insightError. Stier som starter med /health hoppes over (endre med skip).
  • Kontekst: { session?, uid?, game?, player?, requestId? }.
  • flush() sender nå; shutdown() sender og stopper timeren (som er unref()-et).
  • Kø: maks maxQueue (5000), eldste droppes. Batch: maxBatch (200), hvert flushMs (5000).
  • enabled: false, eller mangler key/endpoint, gjør alt til no-op. Kaster aldri.

Personvern

  • Fane-ID-en ligger bare i minnet. Ingen cookies eller localStorage.
  • Nøklene username, email, name, pin, password, text og body fjernes fra props og kontekst (to nivåer), både i SDK-en og i ingest.
  • Rå IP lagres aldri. Server-SDK-ens IP og UA brukes ikke.

Source maps

Last opp fra CI etter bygg (med prosjektets secret_key):

for map in dist/assets/*.js.map; do
  base=$(basename "$map" .map)
  curl -fsS -XPOST https://insight.betaworks.no/api/sourcemaps \
    -H "x-secret-key: $INSIGHT_SECRET_KEY" -H "content-type: application/json" \
    -d "{\"release\":\"$RELEASE\",\"filename\":\"$base\",\"content\":$(cat "$map")}"
done

Publisering (vedlikeholdere)

Bump version, commit og push taggen sdk-v<versjon>. Workflowen publish-sdk.yml bygger og publiserer.

Dependencies

Development dependencies

ID Version
@types/node ^22.19.20
tsup ^8.3.5
tsx ^4.19.2
typescript ^5.6.3
Details
npm
2026-11-19 09:54:39 +00:00
10
latest
10 KiB
Assets (1)
Versions (2) View all
0.1.0 2026-11-19
0.0.1 2026-06-11