Skip to main content
PlaySmart uses two levels of configuration: app-level settings that apply globally to every player and game, and per-game settings that control individual game behavior. Understanding both levels helps you know which knobs to turn when you want to change monetization, maintenance windows, or gameplay reward rules.

​
App-level settings

PlaySmart’s global app settings act as a control panel for the entire platform. These fields are returned by GET /v1/app-settings and affect all players and games:
FieldTypeDescription
is_liveBooleanGlobal kill-switch. When false, all games return a maintenance state and economic actions (coin awards, conversions, withdrawals) are blocked.
Setting is_live to false affects every player and every game simultaneously. Use this for platform-wide maintenance only.
Additional settings are managed by your deployment configuration and the active conversion setting, including:
  • minimum_withdrawal_amount — minimum USD balance required to request a withdrawal
  • withdraw_cooldown_hours — hours a player must wait between withdrawal requests
  • conversion_interval_hours — how often the coin-to-USD conversion job runs per user
  • ads_enabled — global flag to enable or disable ad serving across all games

​
Per-game configuration

Each game has its own configuration controlling reward behaviour and availability.

​
Game fields

FieldTypeDescription
nameStringDisplay name shown in the parent app’s game list.
package_nameStringAndroid package name (e.g. com.example.knifeking). Unique across all games; used for install detection.
play_store_urlStringFull Play Store URL shown when the game is not installed.
thumbnail_urlStringImage URL shown in the parent app game list.
game_modeStringOne of level_based, endless, or hybrid. See Game modes below.
coins_enabledBooleanWhen false, the game is playable but earns no coins. Useful for discovery or testing.
ads_enabledBooleanWhen false, no ads are served in this game, independent of the global flag.
is_activeBooleanWhen false, the game is hidden client-side and stops earning coins.

​
Reward configuration fields (games_configs)

Each game has exactly one linked config document:
FieldTypeDescription
reward_modeStringfixed (constant coin amount) or random_range (random draw between min and max).
reward_fixed_amountNumberCoins awarded per event when reward_mode is fixed.
reward_min_amountNumberLower bound of the random draw when reward_mode is random_range.
reward_max_amountNumberUpper bound of the random draw when reward_mode is random_range.
level_completion_enabledBooleanEnables coin rewards on level_complete trigger.
event_trigger_enabledBooleanEnables coin rewards on event_trigger trigger. Disabled by default.
event_trigger_thresholdNumberNumber of custom events required to fire an event_trigger reward. Minimum 1.
level_completion_multiplierNumberMultiplier on level_complete rewards. Default 1.0.
event_trigger_multiplierNumberMultiplier on event_trigger rewards. Default 0.5.

​
Game modes

The game_mode field accepts one of three values that describe the gameplay structure:

level_based

Players progress through discrete levels. Coin rewards are most naturally tied to LevelCompleted events.

endless

There are no distinct levels — play continues until the player fails. The event_trigger path suits this mode.

hybrid

The game has both level progression and endless/score-based elements. Both trigger paths can be enabled simultaneously.

​
Maintenance mode

A game can enter maintenance state from two independent sources:
  1. App-level: is_live is false on the app settings document — every game returns maintenance: true.
  2. Game-level: is_active is false on the game document — only that specific game returns maintenance: true.
When a game is in maintenance state, the client should display a maintenance screen and prevent the player from interacting with economy features for that game.

​
User game progress

PlaySmart automatically tracks per-player, per-game statistics server-side. You do not need to manage these fields yourself — they are updated as events are ingested.
FieldDescription
is_installedWhether the player has the game installed.
first_played_atTimestamp of the player’s first session.
last_played_atTimestamp of the player’s most recent session.
total_sessionsCumulative session count.
current_levelThe player’s current level (relevant for level_based and hybrid games).
total_games_playedTotal number of individual game rounds played.
total_games_completedTotal number of game rounds completed (not just started).
total_coins_earnedLifetime coins earned in this game.
daily_coins_earnedCoins earned today (resets daily).
high_scoreThe player’s best score.
last_scoreThe player’s score in their most recent round.
Each user_game_progress document is unique per (user_id, game_id) pair. PlaySmart creates it automatically on the player’s first interaction with a game.