# **Planning Prompt: Analytics Tracking Setup App** ## **Context for Claude** You are planning a web application that replaces a manual Google Docs-based workflow for setting up website analytics tracking. This prompt comes from a team that has manually set up GA4, GTM, Google Ads conversions, and Search Console for multiple client websites using a structured Google Doc as a tracking/status document. The experience revealed that \~80% of the work is automatable, and the remaining 20% consists of decision points and access-gating that requires human judgment or action. The app is called **TrackFlow** (working title). It manages the full lifecycle of setting up analytics tracking for a client website, from initial site crawl through to a fully configured GA4 \+ GTM \+ Google Ads \+ Search Console setup. --- ## **What This App Replaces** Currently, the workflow uses a Google Doc with this structure: ### Document Structure (the "tracking doc") **Summary tab:** - Quick status table (last updated, current setup status) - Narrative summary of implementation state - Known issues and future considerations **Goals, Events & Settings tab:** 1. **Status Legend** \- Emoji-based status indicators: - Done: checkmark-verified, green-square-unverified, gray-square-purposely-not-done, no-entry-removed, red-x-needs-troubleshooting - Proposed: lightbulb-new, blue-diamond-suggested-change, flame-approved, pear-disapproved, diamond-unsure 2. **Google Analytics section:** - **Events table** (columns: Status, Event Description, Event Label, Key Event flag, Count Per \[Event/Session\], Value \[1-100\], Setup Platform \[GTM/Analytics/Website\], Notes) - **Audiences table** (columns: Status, Audience Name/Description, Duration \[days\], Audience Event Label, Notes) - **Custom Channel Groups table** (columns: Status, Channel Name, Rules/Conditions) 3. **Google Ads section:** - **Conversions table** (columns: Status, Conversion Name, Type \[Primary/Secondary\], Category, Level \[Account/Campaign\], Value \[CAD\], Setup Platform, Enhanced Conversions flag, Notes) 4. **Meta section:** - Simple events table for Meta pixel tracking 5. **General Settings section:** - Main tracking tag review (tag detected, type, installed by, status) - GTM configuration (container ID, account ID) - GA4 settings (measurement ID, currency, timezone, included domains, referral exclusions, data retention, Google Signals) - Search Console verification status - Google Ads account settings and linking status 6. **Reference section:** - Common GA4 events library (reusable templates) - Common Google Ads goals - Typical channel groupings ### The Manual Workflow (what the app automates) Here is the exact sequence a human (or AI assistant) follows today: **Phase 1: Discovery** 1. Get the client website URL 2. Crawl/browse the website to identify: - All CTAs (buttons, links, forms) - Contact methods (phone, email, chat, directions, booking) - Form types and thank-you page patterns - Service/product page URL patterns - Navigation structure 3. Check if any tracking is already installed (view source for GTM/GA4/Meta snippets) 4. If tracking exists, determine what access the user has **Phase 2: Proposal** 5\. Based on the crawl, propose: - GA4 custom events (with labels, values, count-per, key-event flags) - GA4 audiences (with durations and trigger conditions) - Custom channel groups (with regex rules for each channel) - Google Ads conversions (with types, categories, values, setup platforms) 6. Document all proposals in the tracking doc with "proposed" status indicators 7. Get human approval (client or setup user) on the proposals **Phase 3: GTM Setup** 8\. Create or access the GTM container 9\. Import a starter container (if starting fresh) or audit existing tags 10\. Create all custom event tags: \- Each event needs: Tag (GA4 Event), Trigger, and sometimes Variables \- Common trigger types: Click URL contains, Click Text matches, Page Path matches, Form Submission, Element Visibility \- Events fire to the GA4 measurement ID via the GA4 Configuration tag 11\. Test all tags using GTM Preview mode 12\. Publish the GTM container 13\. Update tracking doc statuses **Phase 4: GA4 Configuration** 14\. Enable Google Signals 15\. Set data retention to 14 months 16\. Mark key events (conversions) in GA4 17\. Verify Google Search Console ownership (can be done via GTM) 18\. Link Search Console to GA4 19\. Link GA4 to Google Ads **Phase 5: Google Ads Setup** 20\. Import GA4 conversions into Google Ads (or create new ones) 21\. Configure each conversion: \- Primary vs Secondary \- Conversion value \- Count type (one per click vs every) \- Attribution model and window 22\. Update tracking doc with final statuses **Phase 6: Verification** 23\. Submit test conversions on the live site 24\. Verify events appear in GA4 Realtime 25\. Verify conversions appear in Google Ads 26\. Final status update in tracking doc --- ## **The Three Usage Modes** ### Mode 1: Fully Manual (No AI) The app serves as an interactive checklist/wizard. A human user: - Creates a tracking project - Enters the website URL - The app crawls the site and presents findings - The human manually configures everything in GA4/GTM/Ads - The human updates statuses in the app as they complete each step - The app provides clear instructions for each step - The client can log in and see progress ### Mode 2: AI-Assisted via UI (Claude Desktop \+ Plugin/Skill) A human user opens Claude Desktop (with a Max plan) and installs a TrackFlow plugin/skill. Claude: - Connects to the TrackFlow API to read/update project status - Uses browser automation (Chrome MCP or computer use) to perform the actual setup in GA4/GTM/Ads UIs - Updates TrackFlow via API as each step completes - Pauses at decision points for human approval - The client can see live progress in the TrackFlow app This is essentially what we did manually, except instead of updating a Google Doc, the AI updates the app via API. ### Mode 3: API-Connected (Most Automated) The user connects their Google account directly in the app. The app (or an AI agent behind it): - Uses Google Analytics Admin API to configure GA4 - Uses Google Tag Manager API to create/manage tags - Uses Google Ads API to import and configure conversions - Uses Search Console API for verification and linking - Falls back to guided manual steps only when API access is insufficient The user still approves proposals and key decisions, but the execution is fully automated. --- ## **Edge Cases and Branching Logic** The workflow must handle all of these situations: ### Access Scenarios 1. **Fresh start**: No tracking installed, user has full Google account access - Simplest path: create everything from scratch 2. **Tracking installed, user has access**: GTM and/or GA4 detected, user can log in - Audit existing setup, propose changes, implement approved changes 3. **Tracking installed, user has NO access**: GTM/GA4 detected but managed by someone else - App detects tracking, documents what it finds - User must obtain access (app provides specific instructions) - OR user decides to start fresh (remove old, install new) - App tracks this as a blocker and provides next steps 4. **Partial access**: User has GA4 but not GTM, or vice versa - App must handle mixed states 5. **GA4 without GTM**: Client uses GA4 directly (gtag.js) without GTM - Decision point: migrate to GTM or keep direct? - If keeping direct, some features are limited 6. **Legacy Universal Analytics**: Old UA code still present - Document it, recommend removal, track as a cleanup task ### Existing Setup Variations 7. **Nothing configured**: GA4 property exists but is default/empty - Proceed with full setup 8. **Partially configured**: Some events, some audiences, some settings - Must audit what exists, test what works, propose additions/changes - Cannot blindly overwrite — must present diff to user 9. **Fully configured but wrong**: Tracking exists but is broken or misconfigured - Most complex case: document current state, identify issues, propose fixes - User may need to consult with whoever set it up originally 10. **Multiple properties/containers**: More than one GA4 property or GTM container - User must choose which to work with - App should detect and surface all found ### Website Variations 11. **Single-page app (SPA)**: History-based navigation, no full page loads - GTM triggers differ (History Change vs Page View) - Must be detected during crawl 12. **E-commerce site**: Purchase tracking, product views, cart events - Entirely different event set (enhanced e-commerce) - May need data layer integration 13. **Multi-domain**: Multiple domains or subdomains - Cross-domain tracking configuration needed - Referral exclusions required 14. **WordPress/Shopify/etc.**: Platform-specific considerations - Some platforms have built-in GA4 integration - Plugin conflicts possible --- ## **Technical Architecture Considerations** ### API Integrations Required **Google Analytics Admin API (v1alpha)** - Create/manage properties - Configure data streams - Manage audiences - Set up custom dimensions/metrics - Configure data retention - Enable Google Signals - Manage key events **Google Tag Manager API (v2)** - Create/manage containers - Create tags, triggers, variables - Create container versions - Publish containers - Import/export containers **Google Ads API (v17+)** - Create conversion actions - Configure conversion settings - Link to GA4 **Google Search Console API** - Verify site ownership - Link to GA4 property **OAuth2 Scopes Needed:** - `https://www.googleapis.com/auth/analytics.edit` - `https://www.googleapis.com/auth/tagmanager.edit.containers` - `https://www.googleapis.com/auth/tagmanager.publish` - `https://www.googleapis.com/auth/adwords` - `https://www.googleapis.com/auth/webmasters` ### Site Crawling The app needs two crawl modes: **Basic crawl (bot-based):** - HTTP requests to discover pages - Parse HTML for: links, forms, buttons, phone numbers, email addresses, tracking snippets - Identify CTA patterns, URL structures, navigation hierarchy - Fast, works for most sites **Enhanced crawl (browser-based):** - Headless browser (Puppeteer/Playwright) - Renders JavaScript, captures dynamically loaded content - Can interact with elements (open menus, trigger modals) - Screenshots for visual review - Slower but catches SPAs, dynamic content, lazy-loaded elements ### MCP (Model Context Protocol) Integration For Mode 2 (AI-Assisted), the app should expose an MCP server that Claude Desktop can connect to. This gives Claude direct tool access to: - Read project state (current phase, pending tasks, blockers) - Update task statuses - Read crawl results - Read/write event proposals - Read/write audience proposals - Read/write channel group proposals - Read/write conversion proposals - Trigger crawls - Read GA4/GTM/Ads configuration (when API-connected) - Write GA4/GTM/Ads configuration (when API-connected) The MCP server essentially turns the app's API into Claude-native tools, making Mode 2 and Mode 3 seamless from the AI's perspective. ### Data Model (Core Entities) Project \- id, name, website\_url, client\_name \- status (discovery, proposal, setup, verification, complete) \- created\_at, updated\_at \- google\_account\_connection (optional OAuth) CrawlResult \- project\_id \- crawl\_type (basic, enhanced) \- pages\_discovered\[\] \- ctas\_found\[\] (type, text, url, selector, page) \- forms\_found\[\] (action, method, fields\[\], page) \- tracking\_detected\[\] (type \[gtm/ga4/meta/ua\], id, snippet) \- contact\_methods\[\] (type \[phone/email/chat/directions/booking\], value, pages\[\]) EventProposal \- project\_id \- status (proposed, approved, rejected, implemented, verified) \- event\_name, event\_description, event\_label \- is\_key\_event, count\_per (event/session), value \- setup\_platform (gtm, analytics, website) \- trigger\_type, trigger\_conditions{} \- notes AudienceProposal \- project\_id \- status \- audience\_name, description \- duration\_days \- membership\_rules{} \- notes ChannelGroupProposal \- project\_id \- status \- group\_name \- channels\[\] (name, rules\[\]) ConversionProposal \- project\_id \- status \- conversion\_name \- type (primary/secondary), category, level (account/campaign) \- value, currency \- setup\_platform \- enhanced\_conversions \- notes SetupTask \- project\_id \- phase (discovery, proposal, gtm\_setup, ga4\_config, ads\_setup, verification) \- task\_type (specific task identifier) \- status (pending, in\_progress, blocked, completed, skipped) \- blocker\_reason (if blocked) \- requires\_human (boolean) \- instructions (markdown \- what to do if manual) \- completed\_at, completed\_by (human/ai/api) \- notes PlatformConfig \- project\_id \- platform (ga4, gtm, ads, search\_console, meta) \- config\_key, config\_value \- status (detected, configured, verified) \- (stores things like: gtm\_container\_id, ga4\_measurement\_id, ga4\_property\_id, ads\_account\_id, etc.) ### Workflow Engine The app needs a state machine / workflow engine that: 1. Knows the full sequence of tasks for a tracking setup 2. Understands dependencies (can't configure GA4 events before GA4 property exists) 3. Handles branching (different paths for fresh-start vs existing-setup) 4. Tracks blockers and surfaces them clearly 5. Knows which tasks require human action vs can be automated 6. Provides clear next-step instructions at every point 7. Supports both linear wizard-style progression and dashboard-style overview ### Real-World Lessons from Manual Setup These are specific issues encountered during actual setup that the app must handle: 1. **GA4 key events can only be marked after they first fire.** The app must track events that are "configured but pending first data" and revisit them. 2. **GTM Preview mode is essential for testing.** The app should integrate or guide the user through GTM Preview testing for each tag. 3. **Google Ads conversion import from GA4 requires the GA4 property to be linked first.** Dependency ordering matters. 4. **Search Console verification via GTM is the cleanest method** when GTM is already installed. The app should prefer this path. 5. **Browser extensions can interfere with GA4 admin UI** (notably password managers like LastPass hijack form fields). The app should warn about this for Mode 2, and Mode 3 avoids it entirely by using APIs. 6. **Google Ads accounts may be shared across multiple properties.** The app must handle the case where one Ads account serves multiple websites. 7. **Conversion values should be in the client's local currency.** The app needs to ask/detect currency. 8. **Custom channel groups need careful regex ordering** — users are placed in the first matching group from top to bottom. 9. **Data retention defaults to 2 months in GA4** — this should always be changed to 14 months. The app should flag this. 10. **Google Signals enables cross-device tracking** but can affect data thresholds. The app should explain the tradeoff. 11. **Some events are better counted per-event (e.g., form submissions) while others per-session (e.g., page views).** The app's proposal engine should set sensible defaults. 12. **GTM container versioning matters.** The app should track which version contains which changes and support rollback awareness. 13. **Enhanced conversions require additional setup** (customer data matching). The app should note when this is available but not force it. --- ## **What to Plan** Create a comprehensive technical plan for building TrackFlow. The plan should cover: 1. **Technology stack** — frontend framework, backend, database, hosting, authentication 2. **Architecture** — monolith vs microservices, API design, real-time updates 3. **Data model** — refined from the sketch above, with proper relationships and migrations 4. **Workflow engine** — how the state machine works, how tasks are generated and sequenced 5. **Site crawler** — both basic and enhanced modes, how results are structured 6. **AI proposal engine** — how crawl results become event/audience/channel/conversion proposals 7. **Google API integrations** — OAuth flow, API client architecture, error handling, rate limits 8. **MCP server** — tool definitions for Claude Desktop integration 9. **User interface** — key screens, wizard flow, dashboard, client view 10. **Authentication & authorization** — user roles (setup user, client, admin), Google OAuth 11. **Deployment & infrastructure** — CI/CD, environments, monitoring 12. **MVP scope** — what to build first vs what can wait 13. **Risk assessment** — API limitations, OAuth complexities, rate limits, edge cases The plan should be detailed enough that a developer (or AI coding assistant) could begin implementation from it. Prioritize practical architecture over theoretical perfection — this is a tool that needs to work reliably for real client setups.