@kundai/tracking-sdk

SDK de tracking KundAi — sessions, UTM, conversions, identify.
Framework-agnostique : fonctionne dans n'importe quelle page web (Vanilla JS, Angular, React, Vue) et côté serveur (Node.js / NestJS).

Prérequis

• Une instance KundAi déployée (microservice tracking accessible)
• Une clé API de tracking générée depuis le dashboard KundAi (Settings > API Keys, scope tracking)

Intégration 1 — Balise <script> (Vanilla JS, CMS, landing pages)

C'est le mode le plus simple. Le fichier JS est servi directement par votre instance KundAi.

<!-- Dans le <head> de votre page -->
<script src="https://api.votre-domaine.com/v1/tracking/sdk/kundai-tracker.min.js"></script>
<script>
  window.KundAi.init({
    baseUrl: 'https://api.votre-domaine.com/v1/tracking',
    apiKey: 'kundai_xxxxxxxxxxxx',
    appId: 'web'
  }).then(function(tracker) {

    // Événement comportemental
    tracker.track('signup_form_view');

    // Après connexion de l'utilisateur
    tracker.identify('user_123', { email: '[email protected]' });

    // Après un paiement
    tracker.trackConversion({
      amount: 29.0,
      currency: 'XOF',
      planId: 'pro_monthly'
    });

  });
</script>

Intégration Angular (index.html)

<!-- apps/your-app/src/index.html -->
<head>
  <script src="https://api.votre-domaine.com/v1/tracking/sdk/kundai-tracker.min.js"></script>
  <script>
    window.__kundaiReady = window.KundAi.init({
      baseUrl: 'https://api.votre-domaine.com/v1/tracking',
      apiKey: 'kundai_xxxxxxxxxxxx',
      appId: 'angular-app'
    });
  </script>
</head>

Puis dans votre service Angular :

// tracking.service.ts
import { Injectable } from '@angular/core';

declare const window: Window & {
  __kundaiReady?: Promise<KundAiTrackerGlobal>;
};

interface KundAiTrackerGlobal {
  track(event: string, opts?: { properties?: Record<string, unknown> }): Promise<void>;
  identify(userId: string, opts?: { email?: string }): Promise<void>;
  trackConversion(opts?: { amount?: number; currency?: string; planId?: string }): Promise<void>;
}

@Injectable({ providedIn: 'root' })
export class TrackingService {
  private tracker: KundAiTrackerGlobal | null = null;

  async init(): Promise<void> {
    if (window.__kundaiReady) {
      this.tracker = await window.__kundaiReady;
    }
  }

  track(event: string, properties?: Record<string, unknown>): void {
    this.tracker?.track(event, { properties }).catch(() => undefined);
  }

  identify(userId: string, email?: string): void {
    this.tracker?.identify(userId, { email }).catch(() => undefined);
  }

  conversion(amount: number, currency: string, planId?: string): void {
    this.tracker?.trackConversion({ amount, currency, planId }).catch(() => undefined);
  }
}

Intégration 2 — Package npm (TypeScript / ESM)

Installation

npm install @kundai/tracking-sdk

Usage TypeScript (React, Vue, Angular, Node)

import { KundAi } from '@kundai/tracking-sdk';

const tracker = await KundAi.init({
  baseUrl: 'https://api.votre-domaine.com/v1/tracking',
  apiKey: 'kundai_xxxxxxxxxxxx',
  appId: 'react-app',
  timeoutMs: 5000,
});

// Événement comportemental
await tracker.track('page_view', {
  properties: { page: '/pricing', plan: 'pro' },
});

// Liaison utilisateur connecté
await tracker.identify('user_123', { email: '[email protected]' });

// Conversion (avec retry automatique x3)
await tracker.trackConversion({
  amount: 9900,   // en centimes ou unité locale
  currency: 'XOF',
  planId: 'starter',
});

// Déconnexion
tracker.clearUser();

Angular — Service complet avec router

// src/app/core/tracking/kundai-tracking.service.ts
import { Injectable, inject } from '@angular/core';
import { Router, NavigationEnd } from '@angular/router';
import { filter } from 'rxjs';
import { KundAi, KundAiTracker } from '@kundai/tracking-sdk';
import { environment } from '../../../environments/environment';

@Injectable({ providedIn: 'root' })
export class KundaiTrackingService {
  private tracker: KundAiTracker | null = null;
  private readonly router = inject(Router);

  async init(): Promise<void> {
    this.tracker = await KundAi.init({
      baseUrl: environment.trackingUrl,
      apiKey: environment.trackingApiKey,
      appId: 'angular',
    });

    // Tracking automatique des changements de route
    this.router.events
      .pipe(filter(e => e instanceof NavigationEnd))
      .subscribe(() => {
        this.tracker?.recordPageView().catch(() => undefined);
      });
  }

  track(event: string, properties?: Record<string, unknown>): void {
    this.tracker?.track(event, { properties }).catch(() => undefined);
  }

  identify(userId: string, email?: string): void {
    this.tracker?.identify(userId, { email }).catch(() => undefined);
  }

  conversion(amount: number, currency: string, planId?: string): void {
    this.tracker?.trackConversion({ amount, currency, planId }).catch(() => undefined);
  }
}

// src/app/app.component.ts
import { Component, OnInit, inject } from '@angular/core';
import { KundaiTrackingService } from './core/tracking/kundai-tracking.service';

@Component({ selector: 'app-root', template: '<router-outlet />' })
export class AppComponent implements OnInit {
  private readonly tracking = inject(KundaiTrackingService);

  ngOnInit(): void {
    this.tracking.init().catch(() => undefined);
  }
}

React

// src/hooks/useTracking.ts
import { useEffect, useRef } from 'react';
import { KundAi, KundAiTracker } from '@kundai/tracking-sdk';

export function useTracking() {
  const trackerRef = useRef<KundAiTracker | null>(null);

  useEffect(() => {
    KundAi.init({
      baseUrl: import.meta.env.VITE_TRACKING_URL,
      apiKey: import.meta.env.VITE_TRACKING_API_KEY,
      appId: 'react-app',
    }).then(t => { trackerRef.current = t; }).catch(() => undefined);
  }, []);

  return {
    track: (event: string, props?: Record<string, unknown>) =>
      trackerRef.current?.track(event, { properties: props }),
    identify: (userId: string, email?: string) =>
      trackerRef.current?.identify(userId, { email }),
    conversion: (amount: number, currency: string, planId?: string) =>
      trackerRef.current?.trackConversion({ amount, currency, planId }),
  };
}

Intégration 3 — Backend NestJS (server-side tracking)

Pour tracker des événements côté serveur (webhooks, paiements Stripe/Flutterwave, etc.) sans passer par le navigateur.

Installation

npm install @kundai/tracking-sdk

Module NestJS

// tracking-client.module.ts
import { Module, Global } from '@nestjs/common';
import { ConfigService } from '@nestjs/config';
import { KundAiTracker } from '@kundai/tracking-sdk';

export const KUNDAI_TRACKER = 'KUNDAI_TRACKER';

@Global()
@Module({
  providers: [
    {
      provide: KUNDAI_TRACKER,
      inject: [ConfigService],
      useFactory: (config: ConfigService) =>
        new KundAiTracker({
          baseUrl: config.get<string>('KUNDAI_TRACKING_URL')!,
          apiKey: config.get<string>('KUNDAI_TRACKING_API_KEY')!,
          appId: 'backend',
        }),
    },
  ],
  exports: [KUNDAI_TRACKER],
})
export class TrackingClientModule {}

// payment.service.ts
import { Injectable, Inject } from '@nestjs/common';
import { KundAiTracker } from '@kundai/tracking-sdk';
import { KUNDAI_TRACKER } from './tracking-client.module';

@Injectable()
export class PaymentService {
  constructor(
    @Inject(KUNDAI_TRACKER) private readonly tracker: KundAiTracker,
  ) {}

  async handlePaymentSuccess(payment: {
    userId: string;
    sessionId: string;
    amount: number;
    currency: string;
    planId: string;
  }): Promise<void> {
    // Initialise le tracker sans démarrer de session navigateur
    // (le sessionId vient du frontend via le payload du paiement)
    this.tracker.sessionId = payment.sessionId;
    this.tracker.userId = payment.userId;

    await this.tracker.trackConversion({
      amount: payment.amount,
      currency: payment.currency,
      planId: payment.planId,
      event: 'purchase',
    });
  }
}

Configuration

| Option | Type | Défaut | Description | |---|---|---|---| | baseUrl | string | — | URL du microservice tracking (ex. https://api.votre-domaine.com/v1/tracking) | | apiKey | string | — | Clé API de tracking (header X-API-Key) | | appId | string | "web" | Identifiant de l'application source | | timeoutMs | number | 5000 | Timeout des requêtes fetch en ms |

Méthodes

| Méthode | Description | |---|---| | KundAi.init(config) | Initialise le tracker, démarre la session, capture les UTM | | tracker.track(event, opts?) | Enregistre un événement comportemental | | tracker.trackConversion(opts?) | Enregistre une conversion avec retry x3 | | tracker.identify(userId, opts?) | Lie l'utilisateur connecté à la session | | tracker.recordPageView() | Enregistre une vue de page manuellement (SPA) | | tracker.clearUser() | Déconnecte l'identité locale | | tracker.end() | Clôture la session (appelé automatiquement sur pagehide) |

Publication npm

# Depuis la racine du monorepo
npx nx run tracking-sdk:build-browser

# Publier
cd dist/libs/tracking-sdk/npm
npm publish --access public

Licence

MIT © KundAi