Skip to main content

​
Overview

Event tracking is the foundation of EngageFabric’s gamification system. When players perform actions in your application, you send events to EngageFabric. The Rules Engine then evaluates these events and automatically triggers rewards like XP, currency, quest progress, and badges.

​
How It Works

​
Tracking Events

​
Basic Event

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

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

// Track a simple event
await client.events.track({
  externalUserId: 'user-123',
  eventType: 'lesson_completed',
  properties: {
    lessonId: 'lesson-456',
    score: 95,
    timeSpent: 300
  }
});

​
Event with Idempotency

Use idempotency keys to prevent duplicate event processing: 
await client.events.track({
  externalUserId: 'user-123',
  eventType: 'purchase_completed',
  idempotencyKey: 'order-789', // Prevents duplicate processing
  properties: {
    orderId: 'order-789',
    amount: 99.99,
    items: ['item-1', 'item-2']
  }
});

​
Common Event Types

Here are recommended event types for different use cases:

​
Learning Platform

// Course progress
await client.events.track({
  externalUserId: 'user-123',
  eventType: 'lesson_completed',
  properties: { lessonId: 'l-1', courseId: 'c-1', score: 85 }
});

// Quiz completion
await client.events.track({
  externalUserId: 'user-123',
  eventType: 'quiz_passed',
  properties: { quizId: 'q-1', score: 90, attempts: 1 }
});

​
E-commerce

// Purchase
await client.events.track({
  externalUserId: 'user-123',
  eventType: 'purchase_completed',
  properties: { orderId: 'o-1', amount: 149.99, category: 'electronics' }
});

// Review submitted
await client.events.track({
  externalUserId: 'user-123',
  eventType: 'review_submitted',
  properties: { productId: 'p-1', rating: 5 }
});

​
Fitness App

// Workout completed
await client.events.track({
  externalUserId: 'user-123',
  eventType: 'workout_completed',
  properties: { type: 'running', duration: 1800, distance: 5000 }
});

// Goal achieved
await client.events.track({
  externalUserId: 'user-123',
  eventType: 'daily_goal_achieved',
  properties: { steps: 10500, caloriesBurned: 450 }
});

​
Batch Events

Send multiple events in a single request for better performance: 
await client.events.trackBatch([
  {
    externalUserId: 'user-123',
    eventType: 'page_viewed',
    properties: { page: '/dashboard' }
  },
  {
    externalUserId: 'user-123',
    eventType: 'feature_used',
    properties: { feature: 'export' }
  }
]);

​
Rules Engine Integration

Events are processed by the Rules Engine to trigger automated rewards.

​
Example Rule Configuration

{
  "name": "Lesson Completion Reward",
  "trigger": {
    "eventType": "lesson_completed"
  },
  "conditions": [
    {
      "type": "property_gte",
      "property": "score",
      "value": 80
    }
  ],
  "actions": [
    {
      "type": "grant_xp",
      "amount": 100
    },
    {
      "type": "grant_currency",
      "currency": "coins",
      "amount": 25
    },
    {
      "type": "progress_quest",
      "questId": "complete-10-lessons"
    }
  ]
}
This rule:
  1. Triggers on lesson_completed events
  2. Checks if score >= 80
  3. Awards 100 XP, 25 coins, and progresses a quest

​
Event Properties

Properties provide context for rule evaluation:
Property TypeExampleUse Case
stringcategory: "science"Filter by category
numberscore: 95Threshold conditions
booleanisPremium: trueUser segmentation
arraytags: ["featured"]Multiple categorization

​
Real-Time Updates

When events trigger rewards, connected clients receive real-time updates via WebSocket: 
// Subscribe to player updates
client.subscribe('player:user-123', (update) => {
  console.log('Player updated:', update);
  // { type: 'xp_updated', xp: 1600, level: 5 }
});

// Track event - subscribers will be notified of changes
await client.events.track({
  externalUserId: 'user-123',
  eventType: 'lesson_completed',
  properties: { score: 90 }
});

​
Best Practices

Consistent Naming

Use snake_case for event types: lesson_completed, purchase_made

Rich Properties

Include relevant context in properties for flexible rule creation

Idempotency Keys

Use idempotency keys for important events to prevent duplicates

Batch When Possible

Batch multiple events together to reduce API calls

​
Debugging Events

​
View Event History

const events = await client.events.list({
  externalUserId: 'user-123',
  eventType: 'lesson_completed',
  limit: 10
});

​
Check Processing Status

const status = await client.events.getStatus('event-id');
console.log(status);
// {
//   id: 'event-id',
//   status: 'processed',
//   rulesTriggered: ['lesson-completion-reward'],
//   actionsExecuted: ['grant_xp', 'grant_currency']
// }

Rules Engine

Configure rules to respond to events

Player Management

Learn about player state and profiles