Google Analytics

# Google Analytics API Configuration
# Copy this file to .env and fill in your actual values

# Your Google Analytics 4 Property ID
# Find this in GA4: Admin > Property Settings > Property ID
# Format: 123456789 (numeric only, not the "G-" measurement ID)
GOOGLE_ANALYTICS_PROPERTY_ID=your-property-id-here

# Path to your Google Cloud service account JSON key file
# Create a service account in Google Cloud Console and download the JSON key
# Store this file OUTSIDE your git repository for security
# Example: /home/user/.config/google-analytics/service-account-key.json
GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account-key.json

# How to set up:
# 1. Go to Google Cloud Console (console.cloud.google.com)
# 2. Create or select a project
# 3. Enable the Google Analytics Data API
# 4. Create a service account (IAM & Admin > Service Accounts)
# 5. Download the JSON key file
# 6. Go to GA4 Admin > Property Access Management
# 7. Add the service account email with "Viewer" role
# 8. Update the values above with your property ID and key file path
# 9. Rename this file to .env
# 10. NEVER commit .env or the JSON key file to version control!


# Google Analytics Analysis Examples

Practical examples of common analytics tasks and analysis patterns.

## Example 1: Traffic Overview Analysis

**User Request**: "Review our Google Analytics performance for the last 30 days"

**Analysis Steps**:
1. Fetch core metrics for the period
2. Compare with previous 30 days
3. Identify trends and anomalies
4. Generate insights and recommendations

**Script Command**:
```bash
python scripts/analyze.py \
  --period last-30-days \
  --compare previous-period \
  --metrics sessions,activeUsers,newUsers,bounceRate,engagementRate
```

**Sample Output Analysis**:
```
Traffic Overview (Last 30 Days vs Previous 30 Days)

Sessions: 45,230 (+12.5%)
Active Users: 32,150 (+8.3%)
New Users: 18,920 (+15.2%)
Bounce Rate: 42.3% (-3.1pp)
Engagement Rate: 68.5% (+4.2pp)

Key Insights:
✓ Strong growth in new user acquisition (+15.2%)
✓ Improving engagement (bounce rate down, engagement rate up)
⚠ Sessions per user declining slightly (1.41 → 1.38)

Recommendations:
1. HIGH: Investigate new user source - identify which channels driving growth
2. MEDIUM: Implement retention campaign for existing users
3. LOW: A/B test homepage to improve session depth
```

## Example 2: Traffic Source Analysis

**User Request**: "What are our top traffic sources and which perform best?"

**Analysis Steps**:
1. Group traffic by source/medium
2. Calculate engagement metrics per source
3. Identify high-value vs high-volume sources
4. Recommend optimization strategies

**Script Command**:
```bash
python scripts/ga_client.py \
  --days 30 \
  --metrics sessions,engagementRate,conversions,bounceRate \
  --dimensions sessionSource,sessionMedium \
  --order-by sessions \
  --limit 20
```

**Sample Insights**:
```
Top Traffic Sources (Last 30 Days)

Source/Medium          Sessions    Eng.Rate    Conv.    Bounce
--------------------------------------------------------------
google/organic         18,240      72.3%       245      38.2%
direct/(none)          12,150      65.1%       189      45.6%
facebook/social         5,430      58.2%        67      52.3%
newsletter/email        3,210      81.5%       124      28.1%
google/cpc              2,890      68.9%        98      41.2%

Key Insights:
✓ Newsletter traffic has highest engagement (81.5%) and lowest bounce (28.1%)
✓ Organic search is largest volume but mid-tier engagement
⚠ Social traffic underperforming (high bounce, low conversion)

Recommendations:
1. HIGH: Invest in email list growth - highest quality traffic
2. HIGH: Optimize Facebook campaigns - high spend, poor performance
3. MEDIUM: Improve organic landing pages to boost engagement
4. LOW: Test paid search expansion - good ROI potential
```

## Example 3: Content Performance Analysis

**User Request**: "Which pages have the highest bounce rates and need improvement?"

**Analysis Steps**