Player Management

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 '@engagefabricsdk/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'
  }
});

curl -X POST https://api.engagefabric.com/api/v1/players \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "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');

Admin Operations

These endpoints are available to authenticated admin users via the Admin Console or JWT authentication.

Player Activity Log

View a complete activity history for a player, including client events and system events:

curl -X GET "https://api.engagefabric.com/api/v1/players/{playerId}/activity?limit=50&offset=0" \
  -H "Authorization: Bearer your-jwt-token"

Response:

{
  "events": [
    {
      "id": "evt-123",
      "type": "CLIENT",
      "name": "lesson_completed",
      "properties": { "courseId": "math-101", "score": 95 },
      "createdAt": "2025-12-01T10:30:00Z",
      "status": "COMPLETED"
    },
    {
      "id": "evt-124",
      "type": "SYSTEM",
      "name": "xp_granted",
      "properties": { "amount": 100, "source": "rule" },
      "createdAt": "2025-12-01T10:30:01Z",
      "status": "COMPLETED"
    }
  ],
  "total": 156,
  "limit": 50,
  "offset": 0
}

Admin XP Adjustment

Admins can manually adjust player XP with an audit trail:

curl -X POST "https://api.engagefabric.com/api/v1/players/{playerId}/adjust-xp" \
  -H "Authorization: Bearer your-jwt-token" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 500,
    "reason": "Customer support compensation"
  }'

Negative amounts are allowed for XP deductions. All adjustments are logged to the audit trail.

Admin Currency Adjustment

Admins can adjust any currency balance:

curl -X POST "https://api.engagefabric.com/api/v1/players/{playerId}/adjust-currency" \
  -H "Authorization: Bearer your-jwt-token" \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "coins",
    "amount": 1000,
    "reason": "Promotional bonus"
  }'

All admin adjustments are recorded in the Audit Log with the admin’s identity, timestamp, and reason. This ensures accountability and enables compliance reporting.

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

Getting Started

Guides

Core Concepts

API Reference

Endpoints

SDKs

Resources

Overview

Creating Players

Retrieving Players

Get by External User ID

Get Player State

Updating Players

Update Profile

Add XP

Modify Currencies

Player Metadata

Listing Players

Deleting Players

Admin Operations

Player Activity Log

Admin XP Adjustment

Admin Currency Adjustment

Best Practices

Use Consistent IDs

Batch Operations

Cache Player State

Handle Conflicts

Event Tracking

Game Economy

​Overview

​Creating Players

​Retrieving Players

​Get by External User ID

​Get Player State

​Updating Players

​Update Profile

​Add XP

​Modify Currencies

​Player Metadata

​Listing Players

​Deleting Players

​Admin Operations

​Player Activity Log

​Admin XP Adjustment

​Admin Currency Adjustment

​Best Practices

Use Consistent IDs

Batch Operations

Cache Player State

Handle Conflicts

​Related

Event Tracking

Game Economy

Overview

Creating Players

Retrieving Players

Get by External User ID

Get Player State

Updating Players

Update Profile

Add XP

Modify Currencies

Player Metadata

Listing Players

Deleting Players

Admin Operations

Player Activity Log

Admin XP Adjustment

Admin Currency Adjustment

Best Practices

Related