Introduction

Introduction

Welcome to the Phoenix Gamification Platform integration guide. This series of documents is written specifically for product and engineering teams who plan to embed Phoenix's leaderboard and rewards capabilities inside their own games or applications. The guide focuses exclusively on the pieces you interact with—public HTTP APIs, event formats, and WebSocket feeds—so you can design, build, and test client integrations without needing to understand any internal implementation details.

Phoenix provides three primary API surfaces you will work with:

1. Ingestion Gateway – a secure HTTP API that receives gameplay or engagement events and streams them into the scoring pipeline.
2. Admin Gateway – REST endpoints for defining and managing leaderboards, reward schedules, and tenant-scoped metadata.
3. Query Gateway – REST and WebSocket interfaces that power in-app experiences such as live leaderboards, user-centric views, and historical snapshots.

What This Guide Covers

Each document in this series maps to a critical step in the integration journey:

Getting Started

• Getting Started – provisioning credentials, environment variables, and test tenants.
• Events and Integration – how to structure ingestion events, authenticate with JWT, and send them reliably.

Leaderboards

• Leaderboard Overview – conceptual model of scopes, timeframes, scoring, ranking, and reward tiers.
• Creating Leaderboards – Admin API walkthroughs, example payloads, and validation tips.
• Realtime Updates – WebSocket subscriptions, pagination behaviors, and filter semantics.
• Querying Results – REST endpoints for pages, rank lookups, snapshots, and user-centric views.

Rewards Store

• Rewards Store – let users spend points on prizes, manage reward catalog, and handle orders.
• Rewards – core concepts for reward items and configurations.
• Reward Grants – tracking and querying reward history across all features.

Other Features

• Streak Overview – daily engagement tracking and milestone rewards.
• Coupon Overview – promotional codes and redemption flows.
• Spin the Wheel – chance-based reward mechanics.

Intended Audience & Prerequisites

• Backend engineers building gameplay services or engagement systems.
• Client engineers integrating mobile/desktop experiences with leaderboard widgets.
• DevOps or platform teams responsible for configuring environments, secrets, and observability.

You should be comfortable with HTTP APIs, JWT (Bearer) authentication for Ingestion and Query gateways, JSON payloads, and at least one server-side language (examples assume cURL, Node.js, and Rust).

Next Steps

Proceed to Getting Started to provision credentials, configure environment variables, and run smoke tests against the ingestion, admin, and query gateways. Each subsequent document builds on the previous one, so follow the order above for the smoothest onboarding experience.