@kairos/analytics

SDK d'analytics décentralisé pour dApps web3 et sites web3.
Fonctionne avec ou sans wallet connecté, on-chain et off-chain.

Installation

npm install @kairos/analytics

Usage — Vanilla JS (sites web3 sans framework)

import { init, track, page } from '@kairos/analytics'

// Init une fois au démarrage
await init({
  appId: 'mon-projet',
  mode: 'hybrid',   // 'hybrid' | 'onchain' | 'offchain'
  debug: true,
})

// Track une page view
page()

// Track un event UI
track('cta_clicked', 'ui', { button: 'connect_wallet' })

// Track un event custom
track('feature_used', 'custom', { feature: 'dark_mode' })

Usage — React / Next.js

// _app.tsx ou layout.tsx
import { KairosProvider } from '@kairos/analytics'

export default function App({ children }) {
  return (
    <KairosProvider config={{ appId: 'mon-projet', mode: 'hybrid' }}>
      {children}
    </KairosProvider>
  )
}

// Dans n'importe quel composant
import {
  usePageTracking,
  useTrackClick,
  useTrackTransaction,
  useKairosAnalytics,
} from '@kairos/analytics'

function TradingPage() {
  // Track automatiquement les changements de page
  usePageTracking()

  // Track un click
  const trackSwapClick = useTrackClick('swap_button', { pair: 'ETH/USDC' })

  // Track une tx
  const trackTx = useTrackTransaction()

  // Ou accès direct au SDK
  const analytics = useKairosAnalytics()

  const handleSwap = async () => {
    const tx = await executeSwap()

    trackTx({
      hash: tx.hash,
      chainId: 42161,
      from: userAddress,
      metadata: { pair: 'ETH/USDC', amountIn: '1.0' }
    })
  }

  return <button onClick={trackSwapClick}>Swap</button>
}

Configuration

| Option | Type | Default | Description | |--------|------|---------|-------------| | appId | string | requis | Identifiant unique de votre projet | | mode | 'hybrid' \| 'onchain' \| 'offchain' | 'hybrid' | Mode de transport des events | | debug | boolean | false | Logs détaillés en console | | sampleRate | number | 1 | Taux de sampling (0-1) | | registryAddresses | ChainRegistryMap | auto | Adresses du contrat par chain | | wakuOptions | WakuOptions | auto | Config du nœud Waku |

Architecture

Browser SDK
    │
    ├── Events off-chain (page, ui)
    │       └── Waku P2P network → nœuds indexeurs → merkle root on-chain
    │
    └── Events on-chain (wallet, tx)
            └── Registry Contract (all chains) → The Graph subgraph

Chains supportées

• Ethereum Mainnet (1)
• Optimism (10)
• Polygon (137)
• Base (8453)
• Arbitrum One (42161)
• Avalanche (43114)
• BNB Chain (56)
• Fantom (250)
• Gnosis (100)

Plugins

const myPlugin = {
  name: 'my-plugin',
  onEvent(event) {
    // Modifier l'event
    return { ...event, properties: { ...event.properties, env: 'prod' } }
    // Ou dropper l'event
    // return null
  }
}

const analytics = new KairosAnalytics({ appId: 'mon-projet' })
analytics.use(myPlugin)
await analytics.init()

Roadmap

• [ ] Contrat Registry (Solidity)
• [ ] The Graph subgraph
• [ ] Dashboard Next.js
• [ ] Plugin wagmi v2
• [ ] Plugin viem
• [ ] SDK Python (backend analytics)
• [ ] ZK proof pour privacy-preserving analytics