Gamifly Docs

Gamifly is an API-first gamification engine designed to bridge the gap between administrative logic and real-time player experience. Deploy high-stakes missions, global tournaments, and self-sustaining economies into any application with sub-millisecond precision.

{
  "playerId": "David_007",
  "transactionId": "TX_99182",
  "action_type": "wager",
  "amount": 5.00,
  "currency": "EUR",
  "game_context": {
    "provider": "Pragmatic",
    "category": "Slots",
    "multiplier": 2.5
  }
}

Managing the Arena

Gamifly Tournaments are designed to drive high-intensity volume through real-time rank competition. Below is the configuration logic for creating your first enterprise tournament.

1. Selection of Criteria

Choose the mathematical rule that governs player scoring. Gamifly supports complex win-condition aggregates handled by our streaming engine.

2. Prize Budgeting & Tiers

Configure automated prize distribution across player ranks. Gamifly supports multi-currency rewards including Gems, Gold, and External Reward IDs (Bonuses).

Blueprinting Journeys

Missions are the narrative backbone of the Gamifly experience. Follow this operational guide to deploy a new sequence of player milestones.

Mission Forge Worlds

Missions aren't just progress bars—they are journeys. The **Mission Forge** allows you to deploy 3D-accelerated landscapes that change based on player progress.

Campaign Blueprints

Don't reinvent the wheel. Start with our industry-validated templates designed for specific KPI outcomes.

Advanced SDK Integration

Beyond the drop-in overlay, Gamifly provides hooks to deeply integrate the engagement state into your own UI.

Real-time State Subscription

Listen for "Achievement Unlocked" or "Node Cleared" events to trigger your own celebration animations or sound effects.

Copy// Subscribe to player progress updates
engine.on('node_cleared', (data) => {
  console.log(`Player completed ${data.nodeName}!`);
  
  // Trigger your own animation
  myConfettiOverlay.burst();
});

// Get current player state at any time
const state = await engine.getPlayerState('user_99');
console.log(state.activeMissions[0].progress);

Custom UI Override

Disable the default drawer and build your own HUD using our data stream.

const engine = new Gamifly({
  apiKey: '...',
  disableDefaultUI: true // Native UI mode
});

API Reference Index

Webhooks & Fulfillment

When a player earns a reward, Gamifly sends a cryptographically signed webhook to your fulfillment server.

// Example Webhook Payload (Fulfillment)
{
  "type": "reward_granted",
  "timestamp": "2026-04-14T18:30:00Z",
  "playerId": "user_99",
  "reward": {
    "id": "bonus_25_fs",
    "type": "free_spins",
    "amount": 25
  },
  "signature": "sha256=...."
}

Production Integration Guide

This document summarizes how to integrate the "Gamification Engine" infrastructure with your main betting/casino platform for technical teams. A more detailed and full version can be read from the docs/production-integration.md file within the source code.

1. Database (Supabase) Setup

After testing, create a new isolated project for the Production environment and apply the Migrations (supabase/migrations) via the CLI from your computer:

npx supabase login
npx supabase link --project-ref 
npx supabase db push

Also, ensure that seed (initial) data such as market_items and badges_config are migrated to the Production environment using the export/import method.

2. Iframe Integration and Security (JWT Auth)

To secure players, your main Casino system must generate a unique, one-time signed JWT token for the player before opening the Iframe (Gamifly).

// Casino Backend (Node.js Example)
const token = jwt.sign({
  sub: "DAVID", // player_id
  role: 'authenticated',
  exp: Math.floor(Date.now() / 1000) + (3600)
}, SUPABASE_JWT_SECRET);

// Iframe Source (src)
return `https://gamifly-domain.com/hub?token=${token}`;

RLS rules must be hardened in Production:

CREATE POLICY "Only owner can view" ON player_economy 
FOR SELECT USING (auth.uid() = player_id);

3. Reward Delivery (Fulfillment / Webhooks)

When a reward like "10 Free Spins" or a Cash Reward (Bonus Wallet) is earned in the Gamifly interface and the database processes the calculation, your system needs to assign the actual Spin (e.g., NetEnt) to the player. You can transmit this to your Casino server by triggering Database Webhooks via Supabase.