our-claude-skills/ga-agent-skills/05-realtime-watcher/README.md

Component 5: Realtime Watcher

Type: Standalone Service Priority: P3 Status: Deferred

Goal

Real-time GA4 monitoring with periodic snapshots to Slack.

Status

Deferred — Complete components 1-4 first.

Original Concept

• Screenshot GA4 real-time dashboard every 5 minutes
• Send screenshots to Slack channel
• Trigger via Slack command or user request

Challenges

Challenge	Issue
Browser auth	GA4 requires Google login
Maintenance	Screenshots break when UI changes
Complexity	Headless browser + auth + scheduling
Value	Screenshots may not be best UX

Simplified Approach (Recommended)

Instead of screenshots, use the GA4 Real-time API:

1. Fetch real-time data via API
2. Generate chart image with Plotly
3. Send image to Slack

Benefits

• No browser automation
• More reliable
• Cleaner output
• Programmatic data access

Structure (Future)

05-realtime-watcher/
├── README.md
├── realtime_api.py          # GA4 Real-time API client
├── chart_generator.py       # Generate chart images
├── slack_sender.py          # Upload to Slack
├── watcher.py               # Main service
├── config.yaml
└── requirements.txt

GA4 Real-time API

from google.analytics.data_v1beta import BetaAnalyticsDataClient
from google.analytics.data_v1beta.types import RunRealtimeReportRequest

def get_realtime_users(property_id: str):
    client = BetaAnalyticsDataClient()

    request = RunRealtimeReportRequest(
        property=f"properties/{property_id}",
        dimensions=[{"name": "unifiedScreenName"}],
        metrics=[{"name": "activeUsers"}]
    )

    response = client.run_realtime_report(request)
    return response

Trigger Options

1. Slack Command: /ga-realtime start
2. Scheduled: During campaign launches
3. API Endpoint: Webhook trigger

Implementation (When Ready)

1. Build real-time API client
2. Create chart generator
3. Add Slack integration
4. Implement start/stop controls
5. Add session timeout (1 hour default)

Checklist (Future)

• Real-time API client
• Chart generation
• Slack integration
• Trigger mechanism
• Session management
• Deployment