@jichio/core

@jichio/core est la seule source de vérité pour le comportement offline-first, le batching et l’enrichissement des événements. Les adaptateurs ne font que du wiring autour de cette bibliothèque.

Installation

pnpm add @jichio/core

En usage direct (sans adaptateur), le source par défaut est sdk-core.

API publique

import { createAnalytics } from "@jichio/core";

const analytics = createAnalytics({
  apiKey: "...",
  endpoint: "https://ingest.example.com",
  source: "sdk-react", // fourni par l'adaptateur ; "sdk-core" en usage direct
});

analytics.track("checkout_started", { plan: "pro", amount: 5000 });
analytics.identify(userId, { email, plan });
analytics.page({ url, referrer, title }); // pageview manuel ou enrichi par l'adaptateur
analytics.flush();   // flush best-effort immédiat
analytics.destroy(); // retire les listeners DOM / timers

Méthode	Rôle
`createAnalytics(config)`	Retourne une instance isolée (pas de singleton global obligatoire).
`track(eventName, properties)`	Événement custom ; propriétés JSON sérialisables.
`identify(userId, traits)`	Associe les événements suivants à un utilisateur.
`page(properties?)`	Événement `pageview` ; sans argument, lit `window.location` / `document`.
`flush()`	Tente un envoi immédiat de la file (best-effort).
`destroy()`	Nettoie listeners et timers.

Chaque événement est enrichi automatiquement : eventId, anonymousId, sessionId, timestamp, source, et des namespaces dans properties (sdk, session, page, …). Voir Modèle d’événement.

Configuration

string

requis

Clé projet, envoyée dans l’en-tête X-API-Key.

string

requis

Base URL d’ingestion. Le SDK y ajoute /v1/events.

string

défaut:"sdk-core"

Identifiant du connecteur, injecté dans chaque événement. Fourni par l’adaptateur.

boolean

défaut:"true"

Active l’auto-capture DOM (pageview MPA initial + clics).

boolean

défaut:"false"

Logs console ; en true, l’événement identify est aussi enfilé dans la file.

number

défaut:"5000"

Intervalle entre deux flushs de la file.

number

défaut:"10"

Seuil d’événements déclenchant un flush anticipé.

number

défaut:"10"

Nombre maximal de tentatives d’envoi d’un batch.

number

défaut:"1000"

Délai de base du backoff exponentiel.

number

défaut:"60000"

Plafond du délai de backoff.

Auto-capture DOM

Gérée dans le core pour tout environnement navigateur (React, WordPress, vanilla). Le scope est volontairement restreint en V1 :

Événement	Déclencheur	Payload
`pageview`	Chargement MPA (`init` / `load`) ; complété par l’adaptateur pour la SPA	`url`, `referrer`, `title`, `timestamp`
`click`	Clic sur `a`, `button`, `[data-track]`	`selector` ou `data-track`, `text` tronqué, `url`, `timestamp`

Hors scope V1 : scroll depth, soumissions de formulaire auto-détectées, capture d’erreurs JS, session replay. Tout cela reste trackable manuellement via track().

Les adaptateurs ne réimplémentent pas le listener de clics : ils peuvent désactiver l’auto-capture (autoCapture: false) et gérer eux-mêmes certains événements.

Offline-first

Chaque événement est écrit immédiatement dans une file locale (IndexedDB, fallback localStorage) avant toute tentative d’envoi.
Chaque événement porte un UUID client → déduplication côté ingestion (ON CONFLICT DO NOTHING), rejouable sans doublon.
Envoi par batch (intervalle N secondes ou seuil N événements).
Échec réseau : backoff exponentiel ; purge uniquement après ACK (eventIds acceptés).
Flush sur visibilitychange / pagehide (best-effort, keepalive / sendBeacon).

Détails : Offline-first.

Structure des modules

constants.ts, utils.ts, types.ts, create-analytics.ts
identity/          storage.ts, session-state.ts
event/             build-event.ts, sanitize.ts
event/context-collectors/   page, device, viewport, locale, network, campaign, element, pointer
queue/             event-queue.ts, indexed-db-queue.ts, local-storage-queue.ts
transport/         send-batch.ts, retry-policy.ts
scheduler/         flush-scheduler.ts, lifecycle-flush.ts
capture/           auto-capture.ts

Build

Formats ESM + UMD (AnalyticsCore global), bundle minifié visé < 5 Ko gzip.
Le UMD sert WordPress (<script>) et vanilla.
Aucune dépendance vers apps/api, apps/web ou un adaptateur framework.

Prise en main

SDK

Concepts

Guides

Installation

API publique

Configuration

Auto-capture DOM

Offline-first

Structure des modules

Build

​Installation

​API publique

​Configuration

​Auto-capture DOM

​Offline-first

​Structure des modules

​Build

Installation

API publique

Configuration

Auto-capture DOM

Offline-first

Structure des modules

Build