Event Tracking

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

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

Triggers on lesson_completed events
Checks if score >= 80
Awards 100 XP, 25 coins, and progresses a quest

Event Properties

Properties provide context for rule evaluation:

Property Type	Example	Use Case
`string`	`category: "science"`	Filter by category
`number`	`score: 95`	Threshold conditions
`boolean`	`isPremium: true`	User segmentation
`array`	`tags: ["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

Getting Started

Guides

Core Concepts

API Reference

Endpoints

SDKs

Resources

Overview

How It Works

Tracking Events

Basic Event

Event with Idempotency

Common Event Types

Learning Platform

E-commerce

Fitness App

Batch Events

Rules Engine Integration

Example Rule Configuration

Event Properties

Real-Time Updates

Best Practices

Consistent Naming

Rich Properties

Idempotency Keys

Batch When Possible

Debugging Events

View Event History

Check Processing Status

Rules Engine

Player Management

​Overview

​How It Works

​Tracking Events

​Basic Event

​Event with Idempotency

​Common Event Types

​Learning Platform

​E-commerce

​Fitness App

​Batch Events

​Rules Engine Integration

​Example Rule Configuration

​Event Properties

​Real-Time Updates

​Best Practices

Consistent Naming

Rich Properties

Idempotency Keys

Batch When Possible

​Debugging Events

​View Event History

​Check Processing Status

​Related

Rules Engine

Player Management

Overview

How It Works

Tracking Events

Basic Event

Event with Idempotency

Common Event Types

Learning Platform

E-commerce

Fitness App

Batch Events

Rules Engine Integration

Example Rule Configuration

Event Properties

Real-Time Updates

Best Practices

Debugging Events

View Event History

Check Processing Status

Related