Quick Start

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.com to get access.

Install the JavaScript SDK via your preferred package manager. Python, Ruby, PHP, and cURL use the REST API directly — no SDK needed.

npm install @engagefabricsdk/sdk

yarn add @engagefabricsdk/sdk

pnpm add @engagefabricsdk/sdk

Step 2: Initialize the Client

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

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

import requests

BASE_URL = "https://api.engagefabric.com/api/v1"
HEADERS = {
    "Authorization": "Bearer your-api-key",
    "Content-Type": "application/json",
    "X-Project-ID": "your-project-id"
}

require 'net/http'
require 'json'

BASE_URL = "https://api.engagefabric.com/api/v1"
HEADERS = {
  "Authorization" => "Bearer your-api-key",
  "Content-Type" => "application/json",
  "X-Project-ID" => "your-project-id"
}

<?php
$baseUrl = "https://api.engagefabric.com/api/v1";
$headers = [
    "Authorization: Bearer your-api-key",
    "Content-Type: application/json",
    "X-Project-ID: your-project-id"
];

export API_KEY="your-api-key"
export PROJECT_ID="your-project-id"
export BASE_URL="https://api.engagefabric.com/api/v1"

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}`);

response = requests.post(
    f"{BASE_URL}/players/identify",
    headers=HEADERS,
    json={
        "externalUserId": "user-123",
        "displayName": "John Doe",
        "metadata": {
            "email": "john@example.com",
            "plan": "premium"
        }
    }
)

player = response.json()
print(f"Player level: {player['level']}")
print(f"Player XP: {player['xp']}")

uri = URI("#{BASE_URL}/players/identify")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Post.new(uri, HEADERS)
request.body = {
  externalUserId: "user-123",
  displayName: "John Doe",
  metadata: {
    email: "john@example.com",
    plan: "premium"
  }
}.to_json

response = http.request(request)
player = JSON.parse(response.body)
puts "Player level: #{player['level']}"
puts "Player XP: #{player['xp']}"

$ch = curl_init("$baseUrl/players/identify");
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    "externalUserId" => "user-123",
    "displayName" => "John Doe",
    "metadata" => [
        "email" => "john@example.com",
        "plan" => "premium"
    ]
]));

$response = curl_exec($ch);
curl_close($ch);

$player = json_decode($response, true);
echo "Player level: " . $player['level'] . "\n";
echo "Player XP: " . $player['xp'] . "\n";

curl -X POST "$BASE_URL/players/identify" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Project-ID: $PROJECT_ID" \
  -d '{
    "externalUserId": "user-123",
    "displayName": "John Doe",
    "metadata": {
      "email": "john@example.com",
      "plan": "premium"
    }
  }'

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
  }
});

requests.post(
    f"{BASE_URL}/events",
    headers=HEADERS,
    json={
        "playerId": player["id"],
        "name": "lesson_completed",
        "properties": {
            "courseId": "math-101",
            "lessonId": "lesson-5",
            "score": 95
        }
    }
)

uri = URI("#{BASE_URL}/events")
request = Net::HTTP::Post.new(uri, HEADERS)
request.body = {
  playerId: player["id"],
  name: "lesson_completed",
  properties: {
    courseId: "math-101",
    lessonId: "lesson-5",
    score: 95
  }
}.to_json

http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
http.request(request)

$ch = curl_init("$baseUrl/events");
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    "playerId" => $player["id"],
    "name" => "lesson_completed",
    "properties" => [
        "courseId" => "math-101",
        "lessonId" => "lesson-5",
        "score" => 95
    ]
]));

$response = curl_exec($ch);
curl_close($ch);

curl -X POST "$BASE_URL/events" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Project-ID: $PROJECT_ID" \
  -d '{
    "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.

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}`);
});

# Get player's quests
quests_response = requests.get(
    f"{BASE_URL}/quests/player/{player['id']}",
    headers=HEADERS
)
quests = quests_response.json()

# Get leaderboard rankings
rankings_response = requests.get(
    f"{BASE_URL}/leaderboards/weekly-xp/rankings?limit=10",
    headers=HEADERS
)
rankings = rankings_response.json()

# Display results
for quest in quests:
    print(f"{quest['name']}: {quest['progress']}/{quest['target']}")

# Get player's quests
uri = URI("#{BASE_URL}/quests/player/#{player['id']}")
request = Net::HTTP::Get.new(uri, HEADERS)
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
quests = JSON.parse(http.request(request).body)

# Get leaderboard rankings
uri = URI("#{BASE_URL}/leaderboards/weekly-xp/rankings?limit=10")
request = Net::HTTP::Get.new(uri, HEADERS)
rankings = JSON.parse(http.request(request).body)

# Display results
quests.each do |quest|
  puts "#{quest['name']}: #{quest['progress']}/#{quest['target']}"
end

// Get player's quests
$ch = curl_init("$baseUrl/quests/player/" . $player["id"]);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$quests = json_decode(curl_exec($ch), true);
curl_close($ch);

// Get leaderboard rankings
$ch = curl_init("$baseUrl/leaderboards/weekly-xp/rankings?limit=10");
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$rankings = json_decode(curl_exec($ch), true);
curl_close($ch);

// Display results
foreach ($quests as $quest) {
    echo $quest['name'] . ": " . $quest['progress'] . "/" . $quest['target'] . "\n";
}

# Get player's quests
curl "$BASE_URL/quests/player/PLAYER_ID" \
  -H "Authorization: Bearer $API_KEY" \
  -H "X-Project-ID: $PROJECT_ID"

# Get leaderboard rankings
curl "$BASE_URL/leaderboards/weekly-xp/rankings?limit=10" \
  -H "Authorization: Bearer $API_KEY" \
  -H "X-Project-ID: $PROJECT_ID"

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 '@engagefabricsdk/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.

Getting Started

Guides

Core Concepts

API Reference

Endpoints

SDKs

Resources

Prerequisites

Step 1: Install the SDK

Step 2: Initialize the Client

Step 3: Identify a Player

Step 4: Track Events

Step 5: Display Player Progress

Next Steps

Player Management

Event Tracking

Quest Design

Leaderboards

Example: Complete Integration

​Prerequisites

​Step 1: Install the SDK

​Step 2: Initialize the Client

​Step 3: Identify a Player

​Step 4: Track Events

​Step 5: Display Player Progress

​Next Steps

Player Management

Event Tracking

Quest Design

Leaderboards

​Example: Complete Integration

Prerequisites

Step 1: Install the SDK

Step 2: Initialize the Client

Step 3: Identify a Player

Step 4: Track Events

Step 5: Display Player Progress

Next Steps

Example: Complete Integration