Référence SDK

Le SDK @bettermeter/node est sans dépendance (utilise fetch et crypto intégrés). Nécessite Node.js 18+.

Constructeur

const bm = new BetterMeter(config);

siteIdrequis

string

Domaine ou identifiant enregistré dans BetterMeter

apiKeyrequis

string

Clé API (jeton Bearer) depuis les paramètres du tableau de bord

apiUrl

string

URL de l'API BetterMeter. Par défaut : "https://bettermeter.com". Les URL distantes personnalisées sont bloquées sauf autorisation explicite.

allowCustomApiUrl

boolean

Autoriser une URL d'API HTTPS personnalisée. À utiliser uniquement pour des déploiements auto-hébergés de confiance.

disabled

boolean

Désactiver tout le suivi. Par défaut : false

batch

boolean

Mettre les événements en file d'attente et vider à intervalle. Par défaut : false

batchInterval

number

Intervalle de vidage en ms. Par défaut : 5000

hashUserId

boolean

Hasher les identifiants utilisateur personnalisés avant l'envoi. Par défaut : true.

redactProperties

boolean

Masquer les clés de propriétés sensibles comme tokens, secrets, mots de passe, cookies et clés API. Par défaut : true.

Les valeurs par défaut de sécurité sont conservatrices : les clés API sont requises pour l'ingestion SDK, les valeurs de flags sont supprimées, les propriétés personnalisées ne peuvent pas remplacer les champs SDK de confiance, les identifiants utilisateur sont hachés par défaut et les clés de propriétés sensibles sont masquées avant l'envoi.

trackCommand(options)

commandrequis

string

Nom de la commande

subcommand

string

Sous-commande (ex. : "deploy preview")

flags

string[]

Noms des drapeaux utilisés (valeurs supprimées)

version

string

Version du CLI

durationMs

number

Durée d'exécution en millisecondes

exitCode

number

Code de sortie du processus (0 = succès)

isCi

boolean

Exécution dans un environnement CI

userId

string

Identifiant utilisateur personnalisé

properties

object

Propriétés personnalisées supplémentaires

trackTool(options)

toolrequis

string

Nom de l'outil MCP

client

string

Nom du client IA (ex. : "claude-code", "cursor")

protocolVersion

string

Version du protocole MCP

durationMs

number

Durée d'exécution en millisecondes

success

boolean

Indique si l'appel a réussi

errorType

string

Classification de l'erreur (ex. : "validation_error")

inputTokens

number

Nombre de tokens en entrée

outputTokens

number

Nombre de tokens en sortie

userId

string

Identifiant utilisateur personnalisé

properties

object

Propriétés personnalisées supplémentaires

trackApi(options)

methodrequis

string

Méthode HTTP (GET, POST, etc.)

endpointrequis

string

Modèle d'endpoint (utilisez :param pour les segments dynamiques)

statusCode

number

Code de statut de la réponse HTTP

durationMs

number

Temps de réponse en millisecondes

userId

string

Identifiant utilisateur personnalisé

properties

object

Propriétés personnalisées supplémentaires

Encapsuleurs automatiques

`wrapCommander(program, options?)`

S'accroche au postAction de Commander.js pour suivre automatiquement toutes les commandes.

`wrapMcpServer(server)`

Patch dynamique de server.tool() pour encapsuler tous les gestionnaires avec chronométrage et suivi des erreurs.

`expressMiddleware()`

Retourne un middleware Express/Connect qui suit chaque requête sur res.end.

Détection de robots côté serveur

La plupart des robots n'exécutent pas JavaScript, donc le script de suivi ne se déclenche jamais pour eux. Utilisez reportBotVisit() dans votre middleware serveur pour détecter les robots au niveau de la requête.

middleware.ts

// Next.js middleware
import { reportBotVisit } from "@bettermeter/node/middleware";

export function middleware(request) {
  reportBotVisit(request, "my-site.com", { apiKey: "bm_..." });
  // ... rest of your middleware
}

requestrequis

Request

Requête entrante (NextRequest, Request, etc.)

siteIdrequis

string

Votre identifiant de site BetterMeter

options.apiUrl

string

URL de l'API BetterMeter. Par défaut : https://bettermeter.com

options.apiKey

string

Clé API utilisée pour authentifier les rapports de bots côté serveur

options.allowCustomApiUrl

boolean

Autoriser une URL d'API HTTPS personnalisée. À utiliser uniquement pour des déploiements auto-hébergés de confiance.

Compatible avec l'edge (sans dépendances Node.js). Non bloquant -- n'ajoute aucune latence aux réponses. Ignore automatiquement les ressources statiques, les routes API et les fichiers internes Next.js.

Cycle de vie

`flush(): Promise<void>`

Envoyer immédiatement tous les événements en file d'attente.

`shutdown(): Promise<void>`

Arrêter le minuteur de lot et vider les événements restants. Appeler avant la fin du processus.