game-analytics-kit

English · Русский

game-analytics-kit

Live example report · Site · Quick start

A kit that turns a coding agent — Claude Code or OpenAI Codex — into a game analyst. Installed into a game project, it lets the agent pull the game's raw analytics into a local database, learn what this particular game's events mean, answer product questions and publish versioned reports: one HTML file per version that opens from disk and can be forwarded to anyone.

The kit is the same for every project. Everything game-specific — event meaning, filters, cohorts, queries, notes about the data — the agent writes inside the project, guided by the kit's skills.

• What you get
• Quick start
• Working with Claude Code and Codex
• What to ask
• Reports
• Big games
• Updating and removing
• The token and security
• Troubleshooting
• Developing the kit

What you get

Seven skills — instructions the agent loads when a request matches them. Installed for both agents (.claude/skills/ and .agents/skills/).

An engine (kit/gak, Python standard library only — nothing to pip install): AppMetrica Logs API sync by date ranges into SQLite, device sampling for big games, an event catalog, a model scaffold, queries, CSV import from ad and store consoles, the standard tables of every report (key metrics by build version, drop-off, core actions by their number in the session, leaving after events), SVG charts and the report builder.

Sources today: AppMetrica events, sessions, installs, ad revenue, purchases, crashes and errors; ad-network and store numbers come as CSV exports or screenshots. The engine has a source interface for adding Firebase, GameAnalytics, devtodev and others.

Quick start

You need:

• a game that already sends events to AppMetrica (the SDK is in the game and the app exists in the AppMetrica console) — it is the source the kit reads today;
• Python 3.11+ — on Windows the py launcher from python.org; on macOS/Linux use python3 wherever this page says py;
• git, and Claude Code or Codex installed and signed in.

Below, <kit> is the folder where you clone this repository and <project> is the root of the game's git repository. For Unity that is the folder with Assets/ and ProjectSettings/, or the repository root above it if the Unity project sits in a subfolder. The kit puts its analytics/ folder there, next to Assets/, never inside it (--analytics-dir picks another place).

1. Clone the kit once

git clone https://github.com/Trafalgardi/game-analytics-kit.git <kit>

2. Install it into the game project

py <kit>/install.py <project>

This adds the skills, analytics/ga.py (the command launcher) and analytics/analytics.toml (project settings). --dry-run shows the plan without changing anything.

3. Get an AppMetrica token — a read-only OAuth token of the Yandex account that sees the app:

1. Open https://oauth.yandex.ru/client/new, create an app: platform Web services, Redirect URI https://oauth.yandex.ru/verification_code, permission AppMetrica → appmetrica:read.

2. Copy its ClientID, open https://oauth.yandex.ru/authorize?response_type=token&client_id=<ClientID>, confirm, and copy access_token from the address bar.

3. Save it in a file, not in the chat. One file serves every project of that account:

   mkdir -p ~/.config/game-analytics-kit        # Windows (cmd): mkdir %USERPROFILE%\.config\game-analytics-kit
   

   and create .env in that folder with one line:

   APPMETRICA_TOKEN=<your token>
   

   Only for this project instead: the same line in <project>/analytics/.env (git-ignored).

4. Check that the kit sees the token

cd <project>
py analytics/ga.py status

Expect token APPMETRICA_TOKEN: found in .... py analytics/ga.py selftest checks the engine offline. Run every analytics/ga.py command from the project root.

5. Start the agent in the project and ask in plain words, one request at a time

cd <project>
claude          # or: codex

1. Connect AppMetrica and pull the last two weeks. — the agent finds the SDK key in the code, fills analytics/analytics.toml, measures the data volume and starts the pull in the background (10–60 minutes for two weeks, depending on the game). It waits for the pull itself and says when it is done; py analytics/ga.py status shows the loaded days too.
2. Build the data model. — the agent learns the game's events and writes the project model.
3. Audit our analytics. — optional but recommended the first time: what the game tracks, what is broken, what to fix before trusting the numbers.
4. Make a full review of the game for the last two weeks. — the full report.

The agent names each report (its slug) after the request: the report is analytics/reports/<slug>/v001/report.html, and analytics/reports/index.html lists them all. Requests work in any language; reports are written in report_language from analytics/analytics.toml — Russian by default, report_language = "en" for English. The agent asks before running commands unless you allow them; allow py analytics/ga.py ... for the session to avoid a prompt per command.

Working with Claude Code and Codex

Both agents discover the skills by themselves; you do not name them.

• Install for one agent only with --agents claude or --agents codex.
• Headless runs need permission to run commands (claude -p --dangerously-skip-permissions, codex exec --dangerously-bypass-approvals-and-sandbox) — use them in a project you trust.
• Long data pulls run as detached background jobs, so they survive the end of an agent's session; the agent follows them with py analytics/ga.py sync --wait.

What to ask

What the agent learns about the project stays in the project: analytics/notes/project.md (durable facts: event meaning, filters, time zone) and analytics/notes/findings.md (dated conclusions). Every next session starts by reading them.

Reports

Every report has the same structure, so you — and the next agent — find things in the same place:

A full review has all blocks; a question report keeps 1, 6, 7 and only the blocks it needs. The title is your request ("MyGame 0.2.0, 08–21.09: full review"); the thesis is the line under it. Facts are separated from interpretation, and every number in the answers, hypotheses and recommendations appears in a table or chart of the report. The builder refuses a report whose structure or links are broken.

• A version is final once built. A correction or new data is a new version (v002) that starts with "what changed".
• report.html is one self-contained file (only fonts load from the web); light and dark themes; readable on a phone.
• Live examples on made-up numbers: on the site and in docs/examples/sample-report/en/analytics/reports/ (the same in Russian: ru/) (sample — a full review in three versions, sample-question — a question report). Open index.html from a clone to browse them.

Big games

Event volume differs between games by two orders of magnitude. Before the first large pull the agent downloads one day into a scratch database and picks a mode by volume:

• sample = 0.1 in analytics.toml keeps 10% of devices — the same devices in every table, so rates, medians and funnels are not biased. Absolute numbers (players, impressions, revenue) are shown both as the sample and as an estimate (×10), marked "≈ estimate".
• flatten_params = false skips the parameters table, the biggest part of the database (~6 KB per event).

The engine also refuses to load a chunk that would not fit on the disk and says which lever to use. A real case: ~600k events a day — with a 5% sample and no flattening, two weeks load in about 15 minutes into a ~200 MB database.

Updating and removing

git -C <kit> pull                            # get the kit's current version
py <kit>/install.py <project>              # update the project (same command as install)
py <kit>/install.py <project> --dry-run    # what would change
py <kit>/install.py <project> --uninstall  # remove the kit and its skills; data, notes and reports stay

An update replaces only what the kit owns — the skill folders it installed (they carry a .gak-managed marker), analytics/kit/ and analytics/ga.py. Your analytics.toml, .env, data, model, queries, notes and reports are never touched; your own skills in .claude/skills/ are left alone. After an update: py analytics/ga.py status, py analytics/ga.py selftest, py analytics/ga.py model apply. The installed version is recorded in analytics/kit.install.json; the changes are in CHANGELOG.md.

What to commit in the game repository: analytics/analytics.toml, model/, queries/, notes/, reports/, ga.py, kit/, kit.install.json and the skill folders, so that everyone on the team gets the same kit with the project. analytics/.gitignore already excludes the database, console exports, report scratch folders and .env.

The token and security

• The AppMetrica token is read-only (appmetrica:read). It is looked up in this order: the APPMETRICA_TOKEN environment variable, <project>/analytics/.env, ~/.config/game-analytics-kit/.env.
• The kit never prints, logs or stores the token: not in the database, reports, notes, analytics.toml or git. status only says where it was found.
• Do not paste the token into the chat. If you do, the agent will not repeat it and will ask you to save it to a file; revoke it at https://oauth.yandex.ru if it leaked anywhere.
• The SDK key from the game code (a UUID) is not a secret; it goes into analytics.toml.
• Advertising ids, IP addresses and operators are not downloaded unless you ask for them explicitly (sync --with-device-ids).
• The database stays on your machine. Reports contain aggregates, not device-level data.

Troubleshooting

Developing the kit

Read CONTRIBUTING.md first. The contract is docs/DESIGN.md (change it first, then the code, then the skills); the field experience the skills are written from is docs/KNOWLEDGE.md; end-to-end tests with real agents are in docs/TESTING.md and docs/TEST_LOG.md. Rules for agents that work on the kit itself: AGENTS.md.

py kit/selftest.py                               # engine, offline, synthetic data
py tests/test_install.py                         # installer
py docs/examples/sample-report/make_sample.py    # report builder and the examples
py install.py <scratch project folder> --dry-run # the install plan

py install.py <project> --link links the skills and the engine to your clone instead of copying them, so a change in the kit is visible in the project at once.

License

MIT.