Spin Wheel - Eska Platform Documentation

Overview

The Spin Wheel feature is a core gamification element that provides users with an engaging way to earn rewards. It combines visual appeal with strategic timing through cooldown mechanisms.

Interactive Wheel

Canvas-based spinning wheel with smooth animations and visual feedback

Cooldown System

Strategic timing system to prevent abuse and maintain engagement

Multiple Prize Types

Points, bonuses, mystery rewards, and special items

Probability System

Weighted probability distribution for balanced reward allocation

How It Works

1

Check Availability

System checks if user can spin based on cooldown timer and availability

2

Execute Spin

User clicks spin button, triggering API call to determine prize

3

Prize Selection

Backend calculates prize based on weighted probabilities

4

Animation & Result

Wheel spins with smooth animation and lands on winning segment

5

Reward Distribution

Prize is awarded, cooldown timer starts, and activity is logged

Prize Types

The Spin Wheel offers various types of rewards with different probabilities and values:

Points

Direct points added to user's balance

50 pts 100 pts 250 pts

Bonus

Multiplier bonuses for trading activities

2x Bonus 5x Bonus

Mystery

Special mystery rewards with unknown values

Mystery Box Surprise Gift

Special Items

Rare items, badges, or exclusive rewards

Golden Badge VIP Access

Cooldown System

The cooldown system prevents abuse and maintains strategic engagement:

Cooldown Features

Time-based Restrictions: Users must wait between spins
Dynamic Cooldown: Cooldown duration can be configured
Real-time Updates: Timer updates every second
Concurrent Protection: Prevents multiple simultaneous spins

Cooldown States

Available: User can spin immediately

Cooldown: User must wait for timer to expire

Spinning: Wheel is currently in motion

Technical Implementation

Frontend Components

`SpinWheel.vue`

Main wheel component with canvas-based rendering and animation

`SpinWheelWidget.vue`

Dashboard widget version with compact display

`SpinResultModal.vue`

Modal component for displaying spin results

Backend Architecture

Controller Layer

SpinWheelController - Handles spin execution and configuration

Model Layer

UserSpinCooldown - Manages user cooldown states

SpinWheelConfiguration - Stores wheel settings and prizes

Service Layer

Prize calculation, probability distribution, and reward processing

API Endpoints

GET /spin-wheel

Display the spin wheel page with current configuration and cooldown status

Response:

{
  "config": {
    "segments": [...],
    "last_win": {...},
    "reset_at": "2024-01-01T00:00:00Z"
  },
  "spinCooldown": {
    "can_spin": true,
    "next_spin_at": null,
    "time_remaining": null,
    "last_spin_at": null
  }
}

POST /api/spin/execute

Execute a spin and return the prize result

Request: POST with CSRF token
Response:

{
  "success": true,
  "prize": {
    "label": "100 pts",
    "value": 100,
    "type": "points"
  },
  "next_spin_at": "2024-01-01T02:00:00Z"
}

GET /api/spin/config

Get current spin wheel configuration

Response: Current wheel segments, probabilities, and settings

Data Structure

Spin Wheel Configuration

{
  "segments": [
    {
      "label": "100 pts",
      "value": 100,
      "type": "points",
      "color": "#FF6B6B",
      "probability": 0.3
    },
    {
      "label": "2x Bonus",
      "value": 2,
      "type": "bonus",
      "color": "#4ECDC4",
      "probability": 0.1
    }
  ],
  "last_win": {
    "prize": "100 pts",
    "time": "2 mins ago"
  },
  "reset_at": "2024-01-01T00:00:00Z"
}

User Spin Cooldown

{
  "user_id": 123,
  "last_spin_at": "2024-01-01T00:00:00Z",
  "next_spin_at": "2024-01-01T02:00:00Z",
  "cooldown_hours": 2,
  "can_spin": false,
  "time_remaining": "1h 30m"
}

Spin Result

{
  "success": true,
  "prize": {
    "label": "100 pts",
    "value": 100,
    "type": "points"
  },
  "activity_id": 456,
  "transaction_id": 789,
  "next_spin_at": "2024-01-01T02:00:00Z"
}

User Experience

Visual Design

Canvas-based Wheel: Smooth, high-quality graphics with custom colors
Responsive Design: Adapts to different screen sizes
Accessibility: Supports reduced motion preferences
Loading States: Clear feedback during spin execution

Animation System

Smooth Rotation: Eased animation with multiple full rotations
Reduced Motion: Quick spin for users with motion sensitivity
Visual Feedback: Button states and loading indicators
Result Display: Modal popup with prize information

Error Handling

Cooldown Messages: Clear indication of when next spin is available
Network Errors: Graceful handling of API failures
Concurrent Protection: Prevents double-spinning
Fallback Results: Demo mode for testing and development

Configuration

Wheel Segments

Configure wheel segments with custom labels, values, colors, and probabilities:

Example Configuration

const segments = [
  { label: "50 pts", value: 50, type: "points", color: "#FF6B6B", probability: 0.4 },
  { label: "100 pts", value: 100, type: "points", color: "#4ECDC4", probability: 0.3 },
  { label: "2x Bonus", value: 2, type: "bonus", color: "#45B7D1", probability: 0.15 },
  { label: "Mystery", value: 1, type: "mystery", color: "#FFA07A", probability: 0.1 },
  { label: "Special", value: 1, type: "special", color: "#98D8C8", probability: 0.05 }
];

Cooldown Settings

Default Cooldown: Configurable hours between spins
Dynamic Adjustment: Can be modified based on user tier or activity
Reset Schedule: Daily or custom reset periods

Probability Distribution

Weighted System: Each segment has configurable probability
Balanced Rewards: Ensures fair distribution of prizes
Rare Items: Lower probability for high-value rewards

Integration

Dashboard Integration

The Spin Wheel is integrated into the main dashboard as a widget:

Compact Display: Shows current spin status and cooldown
Quick Access: Direct link to full spin wheel page
Status Updates: Real-time cooldown timer updates

Activity Logging

All spin activities are logged for tracking and analytics:

Activity Records: Detailed logs of each spin attempt
Transaction Records: Point transactions for point-based prizes
Metadata Storage: Prize details, timestamps, and user context

Reward System Integration

Point Balance: Direct integration with user point system
Bonus Application: Trading bonuses applied to future activities
Special Rewards: Integration with achievement and badge systems

Best Practices

User Engagement

Balanced Cooldowns: Not too short (abuse) or too long (disengagement)
Varied Rewards: Mix of common and rare prizes to maintain interest
Visual Appeal: Attractive colors and smooth animations
Clear Feedback: Immediate and clear result display

Technical Considerations

Concurrent Protection: Prevent multiple simultaneous spins
Error Handling: Graceful degradation for network issues
Performance: Efficient canvas rendering and animation
Accessibility: Support for reduced motion preferences

Security Measures

Server-side Validation: All prize calculations on backend
Rate Limiting: Prevent abuse through cooldown system
CSRF Protection: Secure API endpoints
Transaction Integrity: Atomic operations for reward distribution