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
const sdk = new LudustackSDK({
  apiKey: 'your-api-key'
});

Key Features

  • Game Management - Create and manage games
  • Player 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
);

Get Leaderboard

Retrieve a leaderboard and its entries:

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

Manage Game

Create, update, and manage game state:

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

// Update game status
await sdk.game.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
  baseURL: 'https://ludustack.com/api',  // Optional, defaults to production
  timeout: 5000,   // Optional, request timeout in milliseconds
  headers: {       // Optional, additional headers
    'Custom-Header': 'value'
  }
});

SDK Configuration

The SDK configuration includes the API version:

// Initialize the SDK
const gamification = new LuduStack({
  apiKey: 'your-api-key',
  gameId: 'your-game-id',
  baseURL: 'https://ludustack.com/api',  // Optional, defaults to production
  // Current API version: v2
});

For React applications, check out our React SDK documentation.

For full API reference, visit the API Reference section.