Skip to main content

​
Overview

Players are the core entities in EngageFabric. Each player represents a user in your application who can earn XP, level up, complete quests, and appear on leaderboards.

​
Creating Players

Players are identified by an externalUserId - typically the user ID from your own system. 
import { EngageFabric } from '@engagefabric/sdk';

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

// Create or get existing player
const player = await client.players.upsert({
  externalUserId: 'user-123',
  displayName: 'John Doe',
  avatarUrl: 'https://example.com/avatar.jpg',
  metadata: {
    email: 'john@example.com',
    tier: 'premium'
  }
});

​
Retrieving Players

​
Get by External User ID

const player = await client.players.getByExternalId('user-123');
console.log(player);
// {
//   id: 'player-uuid',
//   externalUserId: 'user-123',
//   displayName: 'John Doe',
//   xp: 1500,
//   level: 5,
//   currencies: { coins: 100, gems: 10 },
//   ...
// }

​
Get Player State

Retrieve comprehensive player state including XP, level, currencies, and active quests: 
const state = await client.players.getState('user-123');
console.log(state);
// {
//   xp: 1500,
//   level: 5,
//   xpToNextLevel: 500,
//   levelProgress: 0.75,
//   currencies: { coins: 100, gems: 10 },
//   lives: { current: 5, max: 5 },
//   activeQuests: [...],
//   badges: [...]
// }

​
Updating Players

​
Update Profile

await client.players.update('user-123', {
  displayName: 'John D.',
  avatarUrl: 'https://example.com/new-avatar.jpg',
  metadata: {
    tier: 'gold'
  }
});

​
Add XP

XP is typically awarded through the Rules Engine via events, but you can also add it directly: 
await client.players.addXp('user-123', {
  amount: 100,
  reason: 'Manual reward'
});

​
Modify Currencies

// Add currency
await client.players.addCurrency('user-123', {
  currency: 'coins',
  amount: 50,
  reason: 'Daily bonus'
});

// Deduct currency
await client.players.deductCurrency('user-123', {
  currency: 'coins',
  amount: 25,
  reason: 'Item purchase'
});

​
Player Metadata

Metadata allows you to store custom data with each player. This is useful for:
  • Storing user preferences
  • Tracking subscription tiers
  • Custom segmentation
  • Integration with your app’s data
// Update specific metadata fields (merge)
await client.players.updateMetadata('user-123', {
  preferredLanguage: 'en',
  notificationsEnabled: true
});

// Replace all metadata
await client.players.setMetadata('user-123', {
  preferredLanguage: 'es'
});

​
Listing Players

const { players, total, page } = await client.players.list({
  page: 1,
  limit: 20,
  sortBy: 'xp',
  sortOrder: 'desc'
});

​
Deleting Players

Deleting a player removes all their progress, quest completions, and leaderboard entries. This action cannot be undone.
await client.players.delete('user-123');

​
Best Practices

Use Consistent IDs

Always use the same externalUserId format across your application to avoid duplicate players.

Batch Operations

When updating multiple players, use batch endpoints to reduce API calls and improve performance.

Cache Player State

Cache player state on the client side and use webhooks to invalidate when changes occur.

Handle Conflicts

Use upsert operations when player creation might race with other operations.

Event Tracking

Learn how to track player actions and trigger rewards

Game Economy

Understand XP, levels, and currencies