> ## Documentation Index
> Fetch the complete documentation index at: https://docs.engagefabric.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Quick Start

> Integrate EngageFabric gamification in 5 minutes. Install the SDK, track events, award XP, and display player progress with JavaScript, Python, Ruby, PHP, or cURL.

## Prerequisites

Before you begin, you'll need:

* An EngageFabric account ([sign up here](https://engagefabric.com/signup))
* A project created in the admin console
* Your API key (found in Project Settings > API Keys)

## Step 1: Install the SDK

<Note>
  The EngageFabric SDK is currently available for enterprise customers and early access partners.
  Contact us at [support@engagefabric.com](mailto:support@engagefabric.com) to get access.
</Note>

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

<CodeGroup>
  ```bash npm theme={null}
  npm install @engagefabricsdk/sdk
  ```

  ```bash yarn theme={null}
  yarn add @engagefabricsdk/sdk
  ```

  ```bash pnpm theme={null}
  pnpm add @engagefabricsdk/sdk
  ```
</CodeGroup>

## Step 2: Initialize the Client

<CodeGroup>
  ```javascript JavaScript theme={null}
  import { EngageFabric } from '@engagefabricsdk/sdk';

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

  ```python Python theme={null}
  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"
  }
  ```

  ```ruby Ruby theme={null}
  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 PHP theme={null}
  <?php
  $baseUrl = "https://api.engagefabric.com/api/v1";
  $headers = [
      "Authorization: Bearer your-api-key",
      "Content-Type: application/json",
      "X-Project-ID: your-project-id"
  ];
  ```

  ```bash cURL theme={null}
  export API_KEY="your-api-key"
  export PROJECT_ID="your-project-id"
  export BASE_URL="https://api.engagefabric.com/api/v1"
  ```
</CodeGroup>

<Warning>
  Never expose your API key in client-side code for production applications.
  Use a backend proxy or serverless functions to make API calls.
</Warning>

## Step 3: Identify a Player

When a user logs into your application, identify them with EngageFabric:

<CodeGroup>
  ```javascript JavaScript theme={null}
  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}`);
  ```

  ```python Python theme={null}
  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']}")
  ```

  ```ruby Ruby theme={null}
  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']}"
  ```

  ```php PHP theme={null}
  $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";
  ```

  ```bash cURL theme={null}
  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"
      }
    }'
  ```
</CodeGroup>

## Step 4: Track Events

Track user actions to trigger gamification rules:

<CodeGroup>
  ```javascript JavaScript theme={null}
  // Track a simple event
  await client.events.track({
    playerId: player.id,
    name: 'lesson_completed',
    properties: {
      courseId: 'math-101',
      lessonId: 'lesson-5',
      score: 95
    }
  });
  ```

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

  ```ruby Ruby theme={null}
  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)
  ```

  ```php PHP theme={null}
  $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);
  ```

  ```bash cURL theme={null}
  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
      }
    }'
  ```
</CodeGroup>

<Info>
  Events are processed asynchronously and can trigger rules that award XP,
  progress quests, update leaderboards, and more.
</Info>

## Step 5: Display Player Progress

Fetch and display the player's current state:

<CodeGroup>
  ```javascript JavaScript theme={null}
  // 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}`);
  });
  ```

  ```python Python theme={null}
  # 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']}")
  ```

  ```ruby Ruby theme={null}
  # 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
  ```

  ```php PHP theme={null}
  // 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";
  }
  ```

  ```bash cURL theme={null}
  # 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"
  ```
</CodeGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Player Management" icon="user" href="/guides/player-management">
    Learn how to manage player profiles, XP, and currencies
  </Card>

  <Card title="Event Tracking" icon="bolt" href="/guides/event-tracking">
    Deep dive into event tracking and rule triggers
  </Card>

  <Card title="Quest Design" icon="scroll" href="/guides/quest-design">
    Create engaging quests and adventures
  </Card>

  <Card title="Leaderboards" icon="trophy" href="/guides/leaderboard-setup">
    Set up competitive leaderboards
  </Card>
</CardGroup>

## Example: Complete Integration

Here's a complete example integrating EngageFabric into a React application:

```jsx theme={null}
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>
  );
}
```

<Check>
  Congratulations! You've successfully integrated EngageFabric into your application.
</Check>