JavaScript SDK Guide

Complete documentation for integrating the Ludiks SDK into your application

Installation

npm

npm install @ludiks/sdk

Quick Setup

Get started in 3 simple steps

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

// Configure with your API key
Ludiks.configure('your-api-key');

// Initialize a user
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
});

// Track events
const eventResponse = await Ludiks.trackEvent('user-123', 'login');
console.log('Points earned:', eventResponse.points);

Available Methods

Ludiks.configure()

Initialize the SDK with your API key

Parameters

apiKeyRequired

string

Your Ludiks API key

Example

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

Ludiks.initUser()

Create or update a user in your project

Parameters

idRequired

string

Unique user identifier

fullNameRequired

string

User's full name

emailOptional

string

User's email address

pictureOptional

string

User's profile picture URL

metadataOptional

object

User's metadata

Response

{
  "success": true
}

Example

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()

Send an event to track user progress

Parameters

userIdRequired

string

User identifier

eventNameRequired

string

Name of the event to track

valueOptional

number

Numeric value associated with the event

timestampOptional

Date

Event timestamp

Response

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

Example

// 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()

Retrieve complete user profile and statistics

Parameters

userIdRequired

string

User identifier to retrieve

Response

{
  "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"
}

Example

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);

Error Handling

How to handle errors gracefully

try {
  const response = await Ludiks.trackEvent('user-123', 'invalid-event');
} catch (error) {
  console.error('Ludiks error:', error.message);
  // Handle error gracefully
}

Complete Examples

Complete Integration Example

Example showing complete SDK usage from initialization to event tracking.

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);
}

Next Steps