Build a better game with the right AI prompts.

# Task: Implement production-only website and in-game analytics

You are a senior analytics engineer and game telemetry designer.

## Project context

- Website or game repository: [PATH OR LINK]
- Game engine or web framework: [DESCRIBE IT]
- Google Analytics measurement ID: [ID]
- Microsoft Clarity project ID: [ID]
- Glitch Analytics dashboard and setup: https://www.glitch.fun/publishers/analytics
- Glitch in-game analytics setup instructions or credentials: [PASTE OR LINK]
- Privacy and consent requirements: [REGIONS, AGE RANGE, OR POLICY]

## Instructions

1. Inspect the current analytics, environment configuration, routing, game loop, and privacy controls before making changes.
2. Ensure analytics are recorded only in production unless an explicit, isolated analytics test mode already exists.
3. Add Google Analytics for acquisition, landing-page behavior, traffic sources, and conversion events.
4. Add Microsoft Clarity for heat maps and session behavior, respecting consent and privacy requirements.
5. Implement Glitch in-game analytics using its current LLM setup instructions.
6. Create a documented event taxonomy covering onboarding, sessions, progression, deaths, combat, quests, economy, purchases, achievements, menus, errors, performance, and exits where applicable.
7. Include stable event names, required properties, player/session identifiers, version information, and platform context.
8. Never send passwords, authentication tokens, private chat, unnecessary personal information, or raw sensitive data.
9. Prevent duplicate events and verify that analytics cannot break gameplay when a provider is blocked or unavailable.
10. Add tests for production gating, event payloads, consent behavior, and failure handling.

## Verification and documentation

Provide a coverage matrix showing which player journey steps are tracked, evidence from each provider's debug or validation tools, known gaps, and instructions for adding future events without breaking the taxonomy.

## Establish tracking before gameplay implementation

Complete the analytics contract before the first playable implementation begins so every new system is measurable when it is added.

1. Read the approved mechanics, core loop, onboarding plan, UI flows, progression, economy, multiplayer, accessibility, localization, performance, failure, and release requirements.
2. Create a coverage matrix that maps every important player journey and game system to stable events, required properties, success/failure outcomes, timing, version, platform, input method, and privacy-safe locale context.
3. Define one centralized, failure-safe analytics interface that gameplay, UI, backend, and platform code can call without depending directly on a provider. A blocked, offline, slow, or failed analytics provider must never block input, saves, networking, scene changes, or gameplay.
4. Keep event names and property keys language-independent. Never use translated display text as an event identifier, and never send raw dialogue, player-entered text, secrets, unnecessary personal data, or developer diagnostics.
5. Document exactly where implementation prompts must emit events for session start/end, onboarding, core-loop entry and repetition, mechanics, movement, combat or challenges, menus, progression, rewards, economy, purchases, saves, errors, performance, accessibility, localization changes, success, failure, retry, abandonment, and exits where applicable.
6. Add schema validation, duplicate prevention, consent and production gating, offline/queue behavior, provider-failure tests, and a development validation view that proves event order and payloads without exposing it to players.

Do not mark analytics setup complete until the taxonomy, integration interface, privacy rules, test strategy, and implementation coverage matrix are documented and ready for every later game-development step to follow.

## Internationalization and localization architecture

Build internationalization into the existing architecture before gameplay and UI content multiply. Do not create a separate localization application or bolt translation onto finished screens.

- Centralize player-facing text behind stable translation keys and locale resources. Do not hard-code display strings in gameplay, menus, tutorials, errors, notifications, subtitles, or content data.
- Define a fallback locale, missing-key behavior, resource ownership, extraction and validation commands, translator notes, and a safe process for adding or updating a language.
- Support Unicode, plural/select rules through an ICU-style message system or the engine's equivalent, locale-aware number/date/time/currency/unit formatting, and invariant internal IDs for saves, networking, analytics, achievements, and game rules.
- Plan for right-to-left layout and bidirectional text, CJK and other line-breaking rules, diacritics, input methods and IME where players type, font fallback and glyph coverage, translated text expansion, subtitles/captions, localized audio or asset variants where required, and runtime language selection with a persisted preference.
- Keep localization data separate from trusted game rules. Servers, SDKs, automation, and analytics should exchange stable language-independent identifiers while clients turn them into localized player-readable text.
- Add pseudolocalization, missing/unused-key validation, fallback-locale tests, long-string and text-expansion tests, right-to-left tests, font/glyph checks, and representative locale screenshots to the normal test and CI strategy.

Document the supported launch locales, later-locale workflow, ownership, file locations, naming rules, formatting rules, font and audio strategy, platform limitations, and exact commands another developer or translator uses.

## Player-readable output requirement

Everything shown to a player must be written and presented for a human player, not for a developer or debugger. This includes menus, HUD labels, buttons, prompts, tutorials, objectives, dialogue, tooltips, loading and save states, empty states, confirmations, warnings, errors, rewards, notifications, accessibility messages, and connection or recovery states.

Use concise plain language, the game's established terminology and tone, recognizable icons with text where meaning could be ambiguous, and a clear next action. A player-facing error should explain what happened in useful terms, whether progress is safe, and what the player can do next.

Never expose raw exceptions, stack traces, JSON, database IDs, internal event names, enum or variable names, file paths, debug coordinates, HTTP status codes without explanation, server implementation details, developer TODOs, placeholder text, or raw telemetry on a player-facing surface. Send technical details to development-only logs, diagnostics, telemetry, or an authenticated support view. A short support reference code may be shown to the player only when it helps support locate the private diagnostic record.

Verify representative success, failure, offline, loading, empty, permission, validation, timeout, save, reconnect, and recovery states from the player's perspective. Developer documentation and final engineering reports may remain technical; this requirement applies to anything the game presents to players.

## Required game documentation

Documentation is part of the definition of done for this task.

Before finishing:

1. Read the existing README, docs directory, architecture notes, decision records, and AI instructions that apply to this system.
2. Update the existing relevant documentation instead of creating a competing document or a second source of truth.
3. If no relevant document exists, create a clearly named Markdown document in the game's established documentation directory. Use docs/ when the project has no existing convention.
4. Document the current system, the decisions made, ownership and lifecycle rules, configuration, files or assets changed, commands and tests run, known limitations, and how another developer should extend or troubleshoot the work.
5. Update AI_INSTRUCTIONS.md or the project's equivalent when this task changes architectural boundaries, required workflows, naming rules, or validation commands.
6. Keep documentation accurate to the implementation. Do not claim support, measurements, or test coverage that was not verified.
7. In the final report, list every documentation file created or updated.