> ## Documentation Index
> Fetch the complete documentation index at: https://docs.summerengine.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Game analytics on Summer Games: send events and read them in Grow

> What Summer counts for every game on Summer Games, how to send custom events with Summer.client.analytics, and how to read the numbers in Summer Grow.

Do this **before you export**: events your game sends are only in the builds that include them.

![Your game's own events, such as level\_completed, and the numbers Summer counts for you, page views, launches and play time, both show in Grow, Analytics: tiles for the totals and bars by day.](https://mintcdn.com/summer-18f03259/lAIp8hql2BjHQCvb/images/guide-art/publishing/analytics-light.svg?fit=max\&auto=format\&n=lAIp8hql2BjHQCvb\&q=85\&s=bf26f1c55dd0760adb9d1f943c0ad51f)

## What Summer counts for you

Every game on Summer Games gets four numbers with no code and no setting:

| Number | Counted when |
| - | - |
| **Store page views** | someone opens your game's page on summer.games |
| **Launches** | the game starts in the Summer Games desktop app or in the browser |
| **Play sessions** | a play session ends: the game quits, or the player leaves the browser game |
| **Play time** | the length of each finished session, added up |

These do not use your analytics storage, and their history does not expire. Days are in UTC. Launches and play time from the iPhone and Android apps come later.

## Send your own events

For things only your game knows: `level_completed`, `boss_defeated`, `tutorial_step_completed`. The full guide, with prompts for your agent, is [See what players do](https://docs.summerengine.com/build/analytics.md). The short version:

```gdscript theme={null}
var _analytics_warned := false

## Fire and forget: never await this, never retry it.
func _track(event: String, properties: Dictionary = {}) -> void:
	var capture := Summer.client.analytics.capture(event, properties)
	var result: SummerResult = await capture.get_result_or_completed_signal()
	if not result.ok and not _analytics_warned:
		_analytics_warned = true
		push_warning("analytics unavailable: %s" % result.code)

func _on_level_completed(level: int, seconds: float) -> void:
	_track("level_completed", {"level": level, "seconds": int(seconds)})
```

On a multiplayer server, use `Summer.authority.analytics.capture` for what the server decides: a match won, a coin collected, an item bought.

### Rules

* **Names** are fixed words in the past tense: 1-64 characters, matching `^[A-Za-z][A-Za-z0-9_.:-]{0,63}$`. Never start a name with `summer.`.
* **Values go in properties**, not in names: `{"level": 3}`, not `level_3_completed`.
* **Properties:** at most 64 values, nested at most 4 deep, one event at most 16 KiB.
* **No personal data:** no emails, ids, tokens or text the player typed. Summer adds the player, game and build itself.
* **Gameplay never waits.** Call `_track(...)` without `await`.
* **Never send again after a failure.** The first call may already be stored.

**Add analytics before I publish.** Your agent adds a few events that answer your questions.

Before I export my Summer game, add analytics events for \[WHAT, for example
"each level started and finished, and where players quit the tutorial"]. Use
the Summer `summer-analytics` skill; if you don't have it installed, find it
in the Summer library.

* Fixed event names in the past tense, with the details in properties.
* Server decisions on the server; menu and tutorial moments on the client.
* Never wait for an event, never send it again, no personal data.

Read my project first and list the events you'd add before you change anything.

### Where your events work

| Where the game runs | Your events |
| - | - |
| Summer Games desktop app (Mac, Windows) | Yes |
| Summer Games apps for iPhone and Android | Yes |
| Multiplayer server | Yes |
| Browser (summer.games web player) | Not yet: `capture` reports `unavailable` |
| Local Play and the editor | No: `capture` reports `unavailable`, nothing is stored |

### Summer Pro, allowance and cap

Your own events will need **Summer Pro**. The four numbers Summer counts for you stay free for every game.

**Enforcement starts later.** Until then Summer stores and counts custom events from every game, with or without Pro. Without Pro a game keeps up to 10,000 custom events at a time, each for 7 days; when that is full, new events are not stored until older ones expire. With Pro, events are kept 30 days. Grow → Analytics shows your usage. The rules below apply once enforcement starts.

* **Without Pro:** Summer does not store your game's custom events. The game keeps running: `capture` still succeeds, but nothing is stored. Studio shows **Events need Summer Pro** with a link to upgrade.
* **With Pro:** each month includes 1 million custom events across all your games. Unused events do not carry over to the next month. Only the live game counts; tests in Local Play and the editor do not. Months follow UTC.
* **Your monthly limit:** you choose how many custom events Summer stores each month. It starts at the amount Pro includes, so you never get a bill you did not choose. Need more? Raise it in Grow → Analytics, **Monthly limit**, or ask your agent: it sends you an approval link, because a limit change always needs your yes. Events above the included amount are extra: they are billed at the end of the month, and the more you send, the less each extra event costs. Once this applies to you, Studio shows an estimate of the month's extra cost.
* **When you reach your limit:** Summer stops storing events until the next month; `capture` still succeeds. Raise the limit to keep counting.
* **Monthly cap:** your limit can go up to a cap. Need more than the cap? Ask us on Discord to raise it.
* **Who it counts for:** the game's owner. Every game they own shares one allowance, one limit and one cap.

Send a few events that answer questions, not one per frame.

## Read your numbers

### In Studio

Open **Grow → Analytics**, pick your game and 7, 28 or 90 days ([Grow Analytics](https://docs.summerengine.com/grow/analytics.md) walks the page). You see:

* store page views, launches, play sessions and play time, as totals and by day;
* the average play session;
* **Custom events your game sent**, with counts;
* **Custom events usage** for this month: events sent, the allowance, the cap and the status (within the allowance, over it, cap reached, or needs Summer Pro).

### With your agent

The `analytics.overview` operation reads your Grow numbers: store page views, launches, play sessions and play time, per game and in total, compared with the days before. It also gives a short reading of what they mean. Your agent runs it with `summer_call`. For one game's days and custom events, use `summer_analytics_summary`.

```json theme={null}
{ "op": "analytics.overview", "input": { "days": 28 } }
```

| Input | Meaning |
| - | - |
| `days` | 7, 28 or 90 days (UTC, today included). Default 7. |
| `include` | Also read `prices`, `interest`, `readiness` or `earnings`. |

The numbers are always your real ones. When analytics are unavailable, the answer says so instead of showing zeros.

`summer_analytics_summary` (one game) also returns this month's custom events usage: events, allowance, limit, cap and status. `analytics.event_limit` reads your monthly limit. `analytics.set_event_limit` always asks you first: it answers with an approval link. In Studio, ask the assistant "how many analytics events have I used this month?" or "raise my events limit to 2 million".

**How is my game doing?** Your agent reads your Grow numbers and tells you what they mean. No changes.

Tell me how my game is doing on Summer Games over the last 28 days. Use the
Summer Engine MCP: analytics.overview for my game. Don't change anything.

Name each number with its window. Tell me what stands out, and which one or
two events I should add to my game to understand players better.

## Checklist before you export

* [ ] The game sends 3-10 events that answer your questions, such as where players stop and what they finish.
* [ ] No `await` on `_track` in gameplay code.
* [ ] No personal data in properties.
* [ ] Under Local Play the game plays normally while events report `unavailable`.
* [ ] You have Summer Pro, or you accept that only the four built-in numbers are counted.
* [ ] After the first published build, open Grow → Analytics and check that your events appear. A short delay is normal.

## Technical reference

Exact methods and inputs: [`Summer.client.analytics`](https://docs.summerengine.com/api-reference/gdscript/client/analytics), the [analytics operations](https://docs.summerengine.com/mcp/operations/analytics.md), and the [analytics HTTP API](https://docs.summerengine.com/api-reference/http/overview.md#analytics).

***

Does this not help you? [Reach out on Discord!](https://discord.gg/summerengine)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.