Introduction

GamifyHost is a gamification-as-a-service platform that lets you add points, games, and leaderboards to any application. Partners integrate via two complementary APIs:

Core Concepts

Partners

A partner is a company or developer who integrates GamifyHost. Each partner account has:

• One or more Apps (each with its own environment)
• API Keys (public + secret) scoped to each app
• Reward Rules that define how points are earned
• Game Mechanics that define how games behave

End Users

End users are your customers. They are identified by an externalId (the user ID in your system). GamifyHost creates and manages user records automatically when you award points.

Points

Points are the currency of the system. Users earn points through actions on your platform (signup, purchase, referral, etc.) and spend them to play games.

Games

Three game types are available:

Game	Type	Description
Neon Wheel	NEON_WHEEL	Spin-the-wheel with weighted segments
Cosmic Slots	COSMIC_SLOTS	Slot machine with symbol matching
Enigma Boxes	ENIGMA_BOXES	Pick-a-box mystery reward

Each game costs a configurable number of points to play. Outcomes are determined server-side using a weighted random number generator.

Rewards

Every game play produces a reward with a tier and type:

Tiers: epic (rarest), rare, common (most frequent)

Types: cashback, xp, points, item, special

Leaderboard

Players are ranked by a composite score:

score = totalPoints + totalRewardsWon + (gamesPlayed × 10)

Environments

All resources are scoped to an environment:

Environment	Key Prefix	Purpose
TEST	pk_test_ / sk_test_	Sandbox, no real rewards
LIVE	pk_live_ / sk_live_	Production

Architecture Overview

┌──────────────┐         ┌──────────────────┐         ┌──────────────┐
│  Your Backend │ ──────▶ │  GamifyHost API  │ ◀────── │  Your Client │
│              │  Secret  │                  │  Public  │  (Widget /   │
│  Award points│  Key     │  Points, Games,  │  Key     │   Flutter)   │
│  Query users │         │  Leaderboards    │         │  Play games  │
└──────────────┘         └──────────────────┘         └──────────────┘
                                  │
                                  ▼
                          ┌──────────────┐
                          │   Webhooks   │
                          │  (Rewards)   │
                          └──────────────┘