Skip to main content

​
Prerequisites

Before you begin, you’ll need:
  • An EngageFabric account (sign up here)
  • A project created in the admin console
  • Your API key (found in Project Settings > API Keys)

​
Step 1: Install the SDK

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

​
Step 2: Initialize the Client

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

const client = new EngageFabric({
  apiKey: 'your-api-key',
  projectId: 'your-project-id'
});
Never expose your API key in client-side code for production applications. Use a backend proxy or serverless functions to make API calls.

​
Step 3: Identify a Player

When a user logs into your application, identify them with EngageFabric: 
const player = await client.players.identify({
  externalUserId: 'user-123',
  displayName: 'John Doe',
  metadata: {
    email: 'john@example.com',
    plan: 'premium'
  }
});

console.log(`Player level: ${player.level}`);
console.log(`Player XP: ${player.xp}`);

​
Step 4: Track Events

Track user actions to trigger gamification rules: 
// Track a simple event
await client.events.track({
  playerId: player.id,
  name: 'lesson_completed',
  properties: {
    courseId: 'math-101',
    lessonId: 'lesson-5',
    score: 95
  }
});
Events are processed asynchronously and can trigger rules that award XP, progress quests, update leaderboards, and more.

​
Step 5: Display Player Progress

Fetch and display the player’s current state: 
// Get player's quests
const quests = await client.quests.getPlayerQuests(player.id);

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

// Display in your UI
quests.forEach(quest => {
  console.log(`${quest.name}: ${quest.progress}/${quest.target}`);
});

​
Next Steps

Player Management

Learn how to manage player profiles, XP, and currencies

Event Tracking

Deep dive into event tracking and rule triggers

Quest Design

Create engaging quests and adventures

Leaderboards

Set up competitive leaderboards

​
Example: Complete Integration

Here’s a complete example integrating EngageFabric into a React application: 
import { useEffect, useState } from 'react';
import { EngageFabric } from '@engagefabric/sdk';

const client = new EngageFabric({
  apiKey: process.env.ENGAGEFABRIC_API_KEY,
  projectId: process.env.ENGAGEFABRIC_PROJECT_ID
});

function PlayerDashboard({ userId }) {
  const [player, setPlayer] = useState(null);
  const [quests, setQuests] = useState([]);

  useEffect(() => {
    async function loadPlayer() {
      // Identify the player
      const p = await client.players.identify({
        externalUserId: userId
      });
      setPlayer(p);

      // Load their quests
      const q = await client.quests.getPlayerQuests(p.id);
      setQuests(q);
    }
    loadPlayer();
  }, [userId]);

  if (!player) return <div>Loading...</div>;

  return (
    <div>
      <h1>Welcome, {player.displayName}!</h1>
      <p>Level {player.level} ({player.xp} XP)</p>

      <h2>Your Quests</h2>
      {quests.map(quest => (
        <div key={quest.id}>
          <strong>{quest.name}</strong>
          <progress
            value={quest.progress}
            max={quest.target}
          />
        </div>
      ))}
    </div>
  );
}
Congratulations! You’ve successfully integrated EngageFabric into your application.