Guide SDK JavaScript

Documentation complète pour intégrer le SDK Ludiks dans votre application

Installation

npm

npm install @ludiks/sdk

Configuration Rapide

Commencez en 3 étapes simples

import { Ludiks } from '@ludiks/sdk';

// Configuration avec votre clé API
Ludiks.configure('your-api-key');

// Initialisation d'un utilisateur
const response = await Ludiks.initUser({
  id: 'user-123',
  fullName: 'John Doe',
  email: 'john@example.com', // Optional
  picture: 'https://example.com/picture.jpg', // Optional
  metadata: {
    plan: 'premium',
    signupSource: 'website'
  } // Optional
});

// Tracking des événements
const eventResponse = await Ludiks.trackEvent('user-123', 'login');
console.log('Points earned:', eventResponse.points);

Méthodes Disponibles

Ludiks.configure()

Initialise le SDK avec votre clé API

Paramètres

apiKeyRequired

string

Votre clé API Ludiks

Exemple

Ludiks.configure("ldk_live_abc123...");

Ludiks.initUser()

Crée ou met à jour un utilisateur dans votre projet

Paramètres

idRequired

string

Identifiant unique de l'utilisateur

fullNameRequired

string

Nom complet de l'utilisateur

emailOptional

string

Adresse email de l'utilisateur

pictureOptional

string

URL de l'image de profil de l'utilisateur

metadataOptional

object

Métadonnées de l'utilisateur

Réponse

{
  "success": true
}

Exemple

const user = await Ludiks.initUser({
  id: 'user-123',
  fullName: 'John Doe',
  email: 'john@example.com', // Optional
  picture: 'https://example.com/picture.jpg', // Optional
  metadata: {
    plan: 'premium',
    signupSource: 'website'
  } // Optional
});

Ludiks.trackEvent()

Envoie un événement pour tracker la progression de l'utilisateur

Paramètres

userIdRequired

string

Identifiant de l'utilisateur

eventNameRequired

string

Nom de l'événement à tracker

valueOptional

number

Valeur numérique associée à l'événement

timestampOptional

Date

Horodatage de l'événement

Réponse

{
  "success": true,
  "stepCompleted": true,
  "points": 150,
  "rewards": [
    {
      "name": "First Login",
      "description": "Welcome bonus for your first login"
    }
  ],
  "circuitCompleted": false,
  "currentStreak": 5
}

Exemple

// Simple event tracking
const response = await Ludiks.trackEvent('user-123', 'login');

// With value and timestamp
const response = await Ludiks.trackEvent(
  'user-123', 
  'purchase', 
  99.99,
  new Date()
);

Ludiks.getProfile()

Récupère le profil complet et les statistiques de l'utilisateur

Paramètres

userIdRequired

string

Identifiant de l'utilisateur à récupérer

Réponse

{
  "id": "user-123",
  "fullName": "John Doe",
  "email": "john@example.com",
  "externalId": "user-123",
  "currentStreak": 5,
  "longestStreak": 12,
  "metadata": {
    "plan": "premium",
    "signupSource": "website"
  },
  "circuitProgress": [
    {
      "id": "circuit-1",
      "circuitName": "Onboarding",
      "status": "completed",
      "points": 500,
      "startedAt": "2024-01-01T00:00:00Z",
      "completedAt": "2024-01-15T10:30:00Z"
    },
    {
      "id": "circuit-2", 
      "circuitName": "Power User",
      "status": "in_progress",
      "points": 250,
      "startedAt": "2024-01-16T00:00:00Z"
    }
  ],
  "createdAt": "2024-01-01T00:00:00Z",
  "lastLoginAt": "2024-01-20T15:30:00Z"
}

Exemple

const profile = await Ludiks.getProfile('user-123');
console.log('Current streak:', profile.currentStreak);
console.log('Circuit points:', profile.circuitProgress[0].points);
console.log('Metadata:', profile.metadata);

Gestion des Erreurs

Comment gérer les erreurs de façon gracieuse

try {
  const response = await Ludiks.trackEvent('user-123', 'invalid-event');
} catch (error) {
  console.error('Ludiks error:', error.message);
  // Gérer l'erreur gracieusement
}

Exemples Complets

Exemple d'Intégration Complète

Exemple montrant l'utilisation complète du SDK, depuis l'initialisation jusqu'au suivi des événements.

import { Ludiks } from '@ludiks/sdk';

// Initialize the SDK
Ludiks.configure('your-api-key');

// Create a new user
try {
  const userResponse = await Ludiks.initUser({
    id: 'user-123',
    fullName: 'Jane Doe',
    email: 'jane@example.com',
    metadata: {
      plan: 'premium',
      signupSource: 'mobile-app'
    }
  });
  
  console.log('User created successfully');
  
  // Track user events
  const loginEvent = await Ludiks.trackEvent('user-123', 'login');
  console.log('Login points:', loginEvent.points);
  
  const purchaseEvent = await Ludiks.trackEvent(
    'user-123', 
    'purchase', 
    299.99
  );
  console.log('Purchase rewards:', purchaseEvent.rewards);
  
  // Get user profile
  const profile = await Ludiks.getProfile('user-123');
  console.log('Current streak:', profile.currentStreak);
  
} catch (error) {
  console.error('SDK Error:', error.message);
}

Prochaines Étapes