User

User API — Configuration & Logic

---

1. Overview

The User system provides core account-level operations for every player. It serves as the central hub for managing player data, inventory, virtual currencies, custom preferences, and account lifecycle.

The system supports the following features:

• Client State — single-call bootstrap that returns the full player state (profile, inventory, currencies, configuration, characters, quests, premium, etc.)

• Inventory — reading the player's items and virtual currency balances

• Custom User Data — storing and retrieving arbitrary key-value pairs per player (preferences, tutorial progress, UI state)

• Currency Transfer — converting one virtual currency into another based on configured allowed pairs

• Currency Subtraction — burning (spending) virtual currency from the player's balance

• Item Consumption — consuming/removing items from inventory by instance or by item type

• Usage Time Tracking — recording and retrieving player session time statistics

• Account Deletion — permanently removing a player's account and all associated data

https://platform.idosgames.com/TitleID/liveops/user

---

2. Configuration Structure

The User system relies on several sections within the title's TitlePublicConfiguration. Unlike the Character system, the User system has fewer dedicated configuration blocks — most of its behavior is determined by virtual currency definitions and inventory catalog settings configured elsewhere.

The key configurable element specific to the User API is:

Field	Type	Description
AllowedCurrencyTransferPairs	List<CurrencyTransferPair>	Whitelist of permitted currency-to-currency transfer directions

---

2.1. Allowed Currency Transfer Pairs

This section defines which virtual currency conversions are permitted via the TransferVirtualCurrency action. Each pair specifies a one-way direction — from one currency to another.

Field	Type	Description
FromCurrencyID	string	Source virtual currency ID
ToCurrencyID	string	Destination virtual currency ID

Key Rules:

• Transfer direction matters: configuring DICE → CO does not automatically allow CO → DICE. Each direction must be added separately if both are needed.

• System currencies (Coin, CoinLimit, Token, TokenLimit) are always forbidden regardless of configuration. The server enforces this hard block.

• The transfer is a 1:1 exchange by amount — the server subtracts N from the source and adds N to the destination.

• If AllowedCurrencyTransferPairs is empty or not configured, all transfer attempts will be rejected.

How to add: In the admin panel, enter the FromCurrencyID and ToCurrencyID for each allowed pair and click + Add.

💡 This is useful for games where players can exchange one earned resource for another, such as converting dice/energy tokens into soft currency.

💡 Or, for example, you can create a "LIMIT" currency that is restored, for example, 10,000 per day, and use it to control the rewards of the "COIN" currency.

---

2.2. Custom User Data

Custom User Data is a key-value store attached to each player. The client can read and write to it freely, with the following constraints:

• System keys are reserved. Any key that matches a value in the SystemCustomUserDataKey enum will be rejected. These keys are managed by the server internally.

• Values are stored as strings. Even if the client sends a number or object, the server serializes Value via .ToString().

Common Use Cases:

• Tutorial/onboarding progress (tutorial_step: "5")

• Player preferences (language: "en", music_volume: "0.8")

• UI state (last_tab: "inventory", seen_promo: "true")

• Feature flags or A/B test assignments (read-only from server, but client reads via GetCustomUserData)

⚠️ Do not store sensitive or game-critical data in Custom User Data, as it is client-writable. Use server-side systems (Leaderboards, Characters, Quests) for progression and economy.

---

2.3. Virtual Currencies

Virtual currencies are defined in the title's economy configuration (not in the User-specific config). The User API provides two operations for spending currencies:

SubtractVirtualCurrency — directly removes a specified amount from the player's balance. The server checks:

1. CurrencyID and SubtractAmount are provided

2. Amount meets the minimum threshold (IGSData.MIN_AMOUNT)

3. Player has sufficient balance (no negative balances allowed)

TransferVirtualCurrency — moves an amount from one currency to another (1:1 ratio). Additional checks:

1. Source and destination currencies are different

2. Neither currency is a system currency

3. The pair is in the AllowedCurrencyTransferPairs whitelist

4. Player has sufficient balance in the source currency

💡 For purchase-related currency deductions (shop, upgrades, level-ups), use the dedicated systems (Store, Character, etc.) which handle the full transaction atomically. SubtractVirtualCurrency is intended for standalone burns (e.g., skipping a timer, unlocking cosmetics via client logic).

---

2.4. Item Consumption

The ConsumeItem action allows the client to reduce item quantities in the player's inventory. Two modes are supported:

By ItemInstanceID: Targets a specific item instance. Useful when the player selects an exact item from their inventory.

By ItemID (+ CatalogVersion): Targets all instances of a given item type and consumes across them. Useful for fungible items like potions or resources where the specific instance doesn't matter.

Equipped item protection: An equipped item cannot be reduced to 0 quantity. The player must unequip it first (via the Character system) before fully consuming it.

⚠️ CatalogVersion defaults to "Item" if not provided. Ensure this matches your catalog setup to avoid consuming from the wrong catalog.

---

2.5. Usage Time Tracking

The Usage Time system allows the client to periodically report how long the player has been active, and to retrieve aggregated statistics.

AddUsageTime — records a time increment for the current session. Call this periodically (e.g., every 60 seconds) from the client.

GetUsageTime — returns aggregated stats broken down by:

Field	Type	Description
Today	int	Total usage time for today
Yesterday	int	Total usage time for yesterday
CurrentWeek	int	Total usage time for the current week
CurrentMonth	int	Total usage time for the current month
Total	long	All-time total usage time
History	Dict<DateTime, int>	Raw daily history (date → time value)

💡 This data can be used for retention analytics, rewarding active players, or displaying play time in the player's profile.

---

3. API Logic

3.1. GetClientState (Bootstrap)

GetClientState is the primary entry point when a player opens the game. It returns everything the client needs in a single call:

1. Loads the player's UserData

2. Refreshes authentication tokens if they are about to expire

3. Aggregates all player data (inventory, currencies, characters, quests, premium, social, leaderboard data, title configuration, etc.) into a ClientStateResponse

3.2. Inventory Access

GetUserInventory returns the latest snapshot of the player's inventory, including:

• All owned item instances (with ItemInstanceId, ItemId, CatalogVersion, RemainingUses, IsEquipped status)

• Virtual currency balances (key-value dictionary of currency IDs to amounts)

• Virtual currency recharge times (if auto-recharge is configured)

3.3. Rate Limiting & Locking

The User API enforces rate limiting and optimistic locking to prevent abuse:

• Rate limit: 1 request per 1 second per user

If a request arrives while the user is rate-limited or locked, it will be rejected. This applies to all User actions.

3.4. Account Deletion

DeleteUserAccount permanently removes all player data. This action:

• Is irreversible

• Removes the player's database document entirely

• Should be gated behind a client-side confirmation dialog

⚠️ Consider implementing a soft-delete or cooldown period in your client UI before calling this endpoint. The server performs immediate permanent deletion.

---

4. Step-by-Step Configuration Guide

Step 1: Configure Virtual Currencies

Before using the User API's currency operations, ensure your virtual currencies are defined in the title's economy configuration. Common currencies include soft currency (Gold/Coins), hard currency (Gems/Crystals), and special currencies (Energy, Dice, Shards).

Step 2: Configure Currency Transfer Pairs (Optional)

If your game needs currency-to-currency conversion:

1. Navigate to the AllowedCurrencyTransferPairs section in the admin panel

2. For each permitted conversion, enter the FromCurrencyID and ToCurrencyID

3. Click + Add for each pair

4. Remember: each pair is one-directional. Add both directions if bidirectional transfer is needed.

Example pairs:

FromCurrencyID	ToCurrencyID	Description
DICE	CO	Convert dice into coins
SH	CO	Convert shields into coins

Step 3: Configure Item Catalogs

Ensure your item catalog is set up with the correct CatalogVersion (typically "Item"). The ConsumeItem action will default to this catalog if the client doesn't specify one.

Step 4: Save

After completing all settings, click Save All (server). Changes are stored locally until saved to the server. The Refresh button allows you to discard local changes and reload current data from the server.

---

5. Player Data Structure

The UserData is the central storage model for each player. The User API reads from and writes to various fields within this document.

Key Fields Relevant to the User API

Field	Type	Description
UserID	string	Unique player identifier (database primary key)
TitleID	string	Title this player belongs to
Platform	string	Registration platform
Inventory	List<ItemInstance>	Player's item instances
VirtualCurrency	Dict<string, long>	Currency balances (CurrencyID → amount)
CustomUserData	GetCustomUserDataResult	Key-value custom data store
Characters	Dict<string, CharacterModel>	Player's characters (see Character API)
GameLoops	GameLoopsState	Board/game loop state
Premium	UserPremiumState	Active premium subscriptions
Quests	UserQuestState	Quest progress and cycle state
Social	UserSocialState	Friends lists (accepted, incoming, outgoing requests)
PublicData	UserPublicDataModel	Public profile data (username, country, avatar, level, power)
UsageTime	Dict<DateTime, int>	Daily usage time history
DailyRewards	Dict<string, DailyRewardState>	Daily reward claim progress per calendar
IsBanned	bool	Whether the player is banned
BanReason	string	Reason for the ban (if applicable)

UserPublicDataModel

Public profile data visible to other players.

Field	Type	Description
Username	string	Display name
Country	string	Player's country
AvatarUrl	string	URL to avatar image
Vip	bool	Whether the player has VIP status
Level	int	Player level
Power	long	Total power rating
NetWorth	long	Net worth value

---

6. API Actions

Action	Description
GetClientState	Returns the full client state (profile, inventory, config, characters, quests, premium, etc.)
GetUserInventory	Returns the player's items and virtual currency balances
GetCustomUserData	Returns the player's custom key-value data (excluding system keys)
UpdateCustomUserData	Sets a single key-value pair in custom data. Requires Key and Value
TransferVirtualCurrency	Transfers currency between two types. Requires FromCurrencyID, ToCurrencyID, TransferAmount
SubtractVirtualCurrency	Burns currency from the player's balance. Requires CurrencyID, SubtractAmount
ConsumeItem	Consumes item uses/quantity. Requires ItemInstanceID or ItemID (+CatalogVersion), SubtractAmount
DeleteUserAccount	Permanently deletes the player's account
GetUsageTime	Returns aggregated usage time statistics
AddUsageTime	Records additional usage time. Requires UsageTime

---

7. Usage Examples

Example 1: Casual Game with Soft Currency

• Currencies: CO (Coins)

• AllowedCurrencyTransferPairs: empty (no conversions needed)

• Custom User Data: tutorial progress, sound settings, last level played

• ConsumeItem: used for single-use power-ups

Example 2: Idle/Tycoon Game with Multiple Currencies

• Currencies: CO (Coins), DICE (Dice/Energy), SH (Shields), IG (Gems)

• AllowedCurrencyTransferPairs:

  • DICE → CO (convert unused dice to coins)

  • SH → CO (convert shields to coins)

• SubtractVirtualCurrency: used for cosmetic purchases managed by client logic

• Usage Time: tracked for daily login rewards and session-based bonuses

Example 3: RPG with Inventory Management

• Currencies: CO (Gold), IG (Crystals)

• ConsumeItem by ItemInstanceID: player uses a specific health potion from inventory

• ConsumeItem by ItemID: batch-consume crafting materials (e.g., 10 iron ore)

• Custom User Data: class selection, keybindings, chat preferences

---

8. FAQ

Q: What is the difference between GetClientState and GetUserInventory? A: GetClientState returns everything — the full player profile, all configuration, inventory, characters, quests, premium state, etc. It's designed to be called once at app launch. GetUserInventory returns only the inventory and currency balances, and is cheaper to call for refreshing after a purchase or action.

Q: Can the client write any key to Custom User Data? A: Almost any key. The only restriction is that keys matching the SystemCustomUserDataKey enum values are reserved by the server and will be rejected. Use descriptive, prefixed keys (e.g., ui_theme, pref_language) to avoid collisions.

Q: Is currency transfer a 1:1 exchange rate? A: Yes. The server subtracts TransferAmount from the source and adds the same TransferAmount to the destination. If you need exchange rates (e.g., 10 Dice = 1 Coin), implement the ratio on the client side by adjusting TransferAmount accordingly, or use a different mechanism (e.g., Store offers).

Q: Can I undo DeleteUserAccount? A: No. Account deletion is permanent and irreversible. Always gate this behind a client-side confirmation dialog (ideally with a typed confirmation like "DELETE" to prevent accidental taps).

Q: What happens if I call ConsumeItem on an equipped item? A: If consuming would reduce the item's quantity to 0, the operation will be rejected. The player must unequip the item first via the Character API's UnequipItems action.