Skip to main content
The EngageFabric JavaScript SDK provides a simple, type-safe way to integrate gamification into your applications.

​
Installation

The EngageFabric SDK is currently available for enterprise customers and early access partners. Contact us at support@engagefabric.com to get access.
Once you have access, install via npm: 
npm install @engagefabricsdk/sdk

​
Quick Start

import { EngageFabric } from '@engagefabricsdk/sdk';

// Initialize the client
const client = new EngageFabric({
  apiKey: 'your-api-key',
  projectId: 'your-project-id'
});

// Identify a player
const player = await client.players.identify({
  externalUserId: 'user-123',
  displayName: 'John Doe'
});

// Track an event
await client.events.track({
  playerId: player.id,
  name: 'lesson_completed',
  properties: {
    courseId: 'math-101',
    score: 95
  }
});

​
Configuration

const client = new EngageFabric({
  // Required
  apiKey: 'your-api-key',
  projectId: 'your-project-id',

  // Optional
  baseUrl: 'https://api.engagefabric.com', // Custom API URL
  timeout: 30000, // Request timeout in ms
  retries: 3, // Number of retry attempts
  debug: false // Enable debug logging
});

​
API Reference

​
Players

// Identify/create a player
const player = await client.players.identify({
  externalUserId: 'user-123',
  displayName: 'John Doe',
  metadata: { email: 'john@example.com' }
});

// Get a player
const player = await client.players.get('player-id');

// Get player by external ID
const player = await client.players.getByExternalId('user-123');

// Update a player
const player = await client.players.update('player-id', {
  displayName: 'John Smith'
});

// Grant XP
await client.players.grantXP('player-id', { amount: 100 });

// Grant currency
await client.players.grantCurrency('player-id', {
  currencyId: 'coins',
  amount: 500
});

// Spend currency
await client.players.spendCurrency('player-id', {
  currencyId: 'coins',
  amount: 100
});

​
Events

// Track a single event
await client.events.track({
  playerId: 'player-id',
  name: 'purchase_completed',
  properties: {
    itemId: 'sword-001',
    price: 100
  }
});

// Track with idempotency key
await client.events.track({
  playerId: 'player-id',
  name: 'purchase_completed',
  idempotencyKey: 'purchase-abc123',
  properties: { ... }
});

​
Quests

// Get player's quests
const quests = await client.quests.getPlayerQuests('player-id');

// Get quest details
const quest = await client.quests.get('quest-id');

// Get quest progress
const progress = await client.quests.getProgress('player-id', 'quest-id');

​
Adventures

// Get player's adventures
const adventures = await client.adventures.getPlayerAdventures('player-id');

// Get adventure details
const adventure = await client.adventures.get('adventure-id');

​
Leaderboards

// Get top rankings
const rankings = await client.leaderboards.getRankings('leaderboard-id', {
  limit: 10
});

// Get player's rank
const rank = await client.leaderboards.getPlayerRank(
  'leaderboard-id',
  'player-id'
);

// Get rank with neighbors
const neighbors = await client.leaderboards.getRankWithNeighbors(
  'leaderboard-id',
  'player-id',
  { above: 2, below: 2 }
);

​
Lobbies

// Create a lobby
const lobby = await client.lobbies.create({
  name: 'Game Room 1',
  maxPlayers: 4,
  metadata: { gameMode: 'deathmatch' }
});

// Join a lobby
await client.lobbies.join('lobby-id', 'player-id');

// Leave a lobby
await client.lobbies.leave('lobby-id', 'player-id');

// Set ready status
await client.lobbies.setReady('lobby-id', 'player-id', true);

// Start the lobby
await client.lobbies.start('lobby-id');

​
Chat

// Send a message
await client.chat.sendMessage('channel-id', {
  playerId: 'player-id',
  content: 'Hello everyone!'
});

// Get messages
const messages = await client.chat.getMessages('channel-id', {
  limit: 50
});

​
WebSocket Client

Connect for real-time updates: 
// Connect to WebSocket
const socket = client.realtime.connect();

// Subscribe to player updates
client.realtime.subscribeToPlayer('player-id');

// Listen for events
client.realtime.on('xp_updated', (data) => {
  console.log(`New XP: ${data.xp}`);
});

client.realtime.on('level_up', (data) => {
  console.log(`Reached level ${data.newLevel}!`);
});

client.realtime.on('quest_completed', (data) => {
  console.log(`Quest completed: ${data.questName}`);
});

// Disconnect when done
client.realtime.disconnect();

​
State Management

The SDK includes Zustand stores for state management: 
import { usePlayerStore, useQuestStore } from '@engagefabricsdk/sdk';

// Access player state
const { player, loading, error } = usePlayerStore();

// Access quests
const { quests, fetchQuests } = useQuestStore();

​
TypeScript Support

The SDK is fully typed: 
import type {
  Player,
  Quest,
  Adventure,
  LeaderboardEntry,
  Lobby,
  ChatMessage
} from '@engagefabricsdk/sdk';

const player: Player = await client.players.get('id');

​
Error Handling

import { EngageFabricError } from '@engagefabricsdk/sdk';

try {
  await client.players.get('invalid-id');
} catch (error) {
  if (error instanceof EngageFabricError) {
    console.log(error.code); // 'PLAYER_NOT_FOUND'
    console.log(error.message); // 'Player not found'
    console.log(error.requestId); // For support
  }
}

​
Best Practices

Never expose your API key in client-side code. Use a backend proxy for browser apps.
For important operations like purchases, always use idempotency keys to prevent duplicates.
Implement proper error handling and retry logic for transient failures.
Use the built-in Zustand stores to cache player data and reduce API calls.

​
REST API Alternative

If you prefer direct HTTP calls over using the SDK, you can achieve the same operations via the REST API. This is useful for server-side integrations in any language. 
# Identify a player
curl -X POST "https://api.engagefabric.com/api/v1/players/identify" \
  -H "X-API-Key: ef_live_your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "externalUserId": "user-123",
    "displayName": "John Doe"
  }'

# Track an event
curl -X POST "https://api.engagefabric.com/api/v1/events" \
  -H "X-API-Key: ef_live_your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "playerId": "player-id",
    "name": "lesson_completed",
    "properties": {
      "courseId": "math-101",
      "score": 95
    }
  }'

# Get leaderboard rankings
curl -X GET "https://api.engagefabric.com/api/v1/leaderboards/weekly-xp/rankings?limit=10" \
  -H "X-API-Key: ef_live_your-api-key"
For more language examples (Ruby, PHP) and the full REST API reference, see the SDK Overview and API Reference.