> For the complete documentation index, see [llms.txt](https://lionstudios.gitbook.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://lionstudios.gitbook.io/readme/analytics/economy-event.md). # Economy Event ## Introduction Economy events are essential for understanding how players interact with the in-game economy. By tracking these events, you can gain insights into player spending behavior, item usage, and the overall balance of your game’s economic system. This information is crucial for optimizing in-game purchases, managing virtual currencies, and enhancing player satisfaction. ## Events #### [**`EconomyEvent`**](/readme/analytics/api/events/economy.md) The [`EconomyEvent`](/readme/analytics/api/events/economy.md) event is the most frequently used and versatile event in tracking economic activities. It allows developers to send information about received and spent products within the transaction parameter. This event helps in monitoring the flow of items, virtual currencies, and real currencies in the game. **Product Types:** * **Items**: Typically boosters / power-ups, and resources (common in idle games). * **Virtual Currencies**: Includes soft and hard currencies like coins, gems, etc. * **Real Currencies**: Represents real money transactions (USD, EUR, etc.). More details are available in the [Monetization - IAP section](/readme/analytics/monetization-event.md). On the server side, we parse the [`EconomyEvent`](/readme/analytics/api/events/economy.md) event to differentiate between sources (acquisitions) and sinks (expenditures) and calculate the balance across the entire user’s lifetime. This event is a key component of our backend economy pipeline. **Usage Guidelines:** * **Track Balance**: Fire the [`EconomyEvent`](/readme/analytics/api/events/economy.md) event whenever in-game items or currencies are used or received to track the balance accurately. * **Initial State**: At the beginning of the game, send an [`EconomyEvent`](/readme/analytics/api/events/economy.md) event to report the initial amounts of boosters, coins, and items to establish a baseline for each player. * **Event Aggregation**: To avoid spamming with too many [`EconomyEvent`](/readme/analytics/api/events/economy.md) events, aggregate items and virtual currencies into a single event and send it at strategic points, such as right before a [`MissionCompleted`](/readme/analytics/api/events/missioncompleted.md) event. Alternatively, you can batch the information and send it periodically. This reduces the number of events per user and makes querying economy data more efficient in the future. {% hint style="info" %} For IAPs, we have a dedicated [`InAppPurchase`](/readme/analytics/api/events/inapppurchase.md) event, which is covered later in the Monetization section. The [`InAppPurchase`](/readme/analytics/api/events/inapppurchase.md) event inherits logic from the [`EconomyEvent`](/readme/analytics/api/events/economy.md) event, making it essential to understand the logic behind the [`EconomyEvent`](/readme/analytics/api/events/economy.md) event. {% endhint %} {% hint style="info" %} Some events, such as [`MissionCompleted`](/readme/analytics/api/events/missioncompleted.md), [`MissionStep`](/readme/analytics/api/events/missionstep.md), [`RewardVideoCollect`](/readme/analytics/api/events/rewardvideocollect.md), etc., include a reward parameter. If the player gains something without spending real or virtual currency, use one of these events instead [`EconomyEvent`](/readme/analytics/api/events/economy.md) to avoid data duplication. These events also handled by our economy pipeline. Ensures that rewards are not logged twice. {% endhint %} #### [**`PowerUpUsed`**](/readme/analytics/api/events/powerupused.md) The [`PowerUpUsed`](/readme/analytics/api/events/powerupused.md) event is also part of the economy pipeline. Use this event to track when a player uses a power-up. **Usage Guidelines:** * Use the [`PowerUpUsed`](/readme/analytics/api/events/powerupused.md) event to track the usage of power-ups. * When giving boosters in [`MissionCompleted`](/readme/analytics/api/events/missioncompleted.md) or [`EconomyEvent`](/readme/analytics/api/events/economy.md) events, ensure the `ItemType` is set to `power_up`, to align with the pipeline logic * Developers **no need to fire an** [**`EconomyEvent`**](/readme/analytics/api/events/economy.md) event alongside the [`PowerUpUsed`](/readme/analytics/api/events/powerupused.md) event as it is integrated into the economy pipeline. #### [**`ItemCollected`**](/readme/analytics/api/events/itemcollected.md) Use this event to track when a player collects an item. This event is useful for understanding item distribution and collection patterns within your game. #### [**`ItemActioned`**](/readme/analytics/api/events/itemactioned.md) Use this event to track when a player takes an action involving an item, such as using, equipping, or selling it. This event helps you understand how players interact with the items they collect and the decisions they make regarding those items. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://lionstudios.gitbook.io/readme/analytics/economy-event.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.