Menu

Documentation

Menu
Guides

JavaScript SDK

The official JavaScript SDK for LuduStack, enabling easy integration of gamification features into your JavaScript applications.

Installation

Install the SDK using npm or yarn:

npm install @ludustack/sdk

Getting Started

Initialize the SDK with your API key and game ID:

import { LuduStack } from '@ludustack/sdk';

// Initialize the SDK - gameId is required
const sdk = new LudustackSDK({
  apiKey: 'your-api-key',
  gameId: 'your-game-id' // Required - all operations will use this game
});

Key Features

  • Games Management - Create and manage games
  • Players Management - Create and manage player profiles
  • Leaderboards - Create and manage leaderboards
  • Game Operations - Perform operations like giving points to players

Usage Examples

Give Points to a Player

Give points to a player:

await sdk.operations.givePoints(
  'player-123',    // Player ID
  100,             // Points to add
  'level_completed' // Optional: The reason for the points
);

Process Achievement

Process achievement progress or completion:

// Process achievement progress
await sdk.operations.processAchievement(
  'player-123',      // Player ID
  'first_login',     // Achievement ID
  {
    progress: 1,     // Progress amount (optional)
    forceComplete: false, // Force completion (optional)
    operation: 'progress' // Operation type
  }
);

// Force complete an achievement
await sdk.operations.processAchievement(
  'player-123',
  'achievement-id',
  { forceComplete: true }
);

Get Leaderboard

Retrieve a leaderboard and its entries:

// Get leaderboard by ID
const leaderboard = await sdk.leaderboards.getById('leaderboard-123');

Manage Game

Create, update, and manage game state:

// Create a new game
const newGame = await sdk.games.create({
  name: 'My Game',
  description: 'A great game'
});

// Update game status
await sdk.games.updateStatus(newGame.id, 'active');

Error Handling

The SDK uses standard Promise-based error handling:

try {
  // Give points to a player
  await sdk.operations.givePoints(
    'player-123',    // Player ID
    100,             // Points to add
    'level_completed' // Optional: The reason for the points
  );
  console.log('Points added successfully');
} catch (error) {
  console.error('Error adding points:', error.message);
  // Handle specific error codes
  if (error.code === 'invalid_player') {
    // Handle invalid player error
  }
}

Configuration Options

The SDK supports these configuration options:

const sdk = new LudustackSDK({
  apiKey: 'your-api-key',   // Required
  gameId: 'your-game-id',   // Required - all operations will use this game
});

SDK Configuration

The SDK configuration includes the API version:

// Initialize the SDK
const gamification = new LuduStack({
  apiKey: 'your-api-key',
  gameId: 'your-game-id',
  // Current API version: v2
});

For React applications, check out our React SDK documentation.

For full API reference, visit the API Reference section.