Add SEO performance tracking features
- Add performance command to analyze page metrics from GA4/GSC - Add keywords command to find keyword opportunities - Add report command to generate SEO performance reports - Support CSV imports (no API setup required) - Optional Google API integration for automated data fetching - Analyze pageviews, clicks, impressions, CTR, rankings - Identify low CTR pages, low position pages, opportunities - Generate comprehensive SEO reports with recommendations - Add PERFORMANCE_TRACKING_GUIDE.md with complete documentation Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com>
This commit is contained in:
Kevin Bataille
355
PERFORMANCE_TRACKING_GUIDE.md
Normal file
355
PERFORMANCE_TRACKING_GUIDE.md
Normal file
@@ -0,0 +1,355 @@
|
||||
# SEO Performance Tracking Guide
|
||||
|
||||
Track and analyze your website's SEO performance using Google Analytics 4 and Google Search Console data.
|
||||
|
||||
## Overview
|
||||
|
||||
The SEO performance tracking features allow you to:
|
||||
|
||||
- **Analyze page performance** - Track pageviews, clicks, impressions, CTR, and rankings
|
||||
- **Find keyword opportunities** - Discover keywords you can rank higher for
|
||||
- **Generate SEO reports** - Create comprehensive performance reports
|
||||
- **Import data** - Support for both CSV imports and API integration
|
||||
|
||||
## Commands
|
||||
|
||||
### 1. `seo performance` - Analyze Page Performance
|
||||
|
||||
Analyze traffic and search performance data.
|
||||
|
||||
**Usage:**
|
||||
|
||||
```bash
|
||||
# Analyze with CSV exports
|
||||
./seo performance --ga4 analytics.csv --gsc search.csv
|
||||
|
||||
# Analyze GA4 data only
|
||||
./seo performance --ga4 analytics.csv
|
||||
|
||||
# Analyze GSC data only
|
||||
./seo performance --gsc search.csv
|
||||
|
||||
# With custom output
|
||||
./seo performance --ga4 analytics.csv --gsc search.csv --output custom_analysis.csv
|
||||
|
||||
# Preview
|
||||
./seo performance --ga4 analytics.csv --dry-run
|
||||
```
|
||||
|
||||
**Data Sources:**
|
||||
|
||||
- **Google Analytics 4**: Export from GA4 → Reports → Engagement → Pages and screens
|
||||
- **Google Search Console**: Export from GSC → Performance → Search results → Export
|
||||
|
||||
**Metrics Analyzed:**
|
||||
|
||||
| Metric | Source | Description |
|
||||
|--------|--------|-------------|
|
||||
| Pageviews | GA4 | Number of page views |
|
||||
| Sessions | GA4 | Number of sessions |
|
||||
| Bounce Rate | GA4 | Percentage of single-page sessions |
|
||||
| Engagement Rate | GA4 | Percentage of engaged sessions |
|
||||
| Clicks | GSC | Number of search clicks |
|
||||
| Impressions | GSC | Number of search impressions |
|
||||
| CTR | GSC | Click-through rate |
|
||||
| Position | GSC | Average search ranking |
|
||||
|
||||
### 2. `seo keywords` - Keyword Opportunities
|
||||
|
||||
Find keywords you can optimize for better rankings.
|
||||
|
||||
**Usage:**
|
||||
|
||||
```bash
|
||||
# Analyze keyword opportunities
|
||||
./seo keywords gsc_export.csv
|
||||
|
||||
# Limit results
|
||||
./seo keywords gsc_export.csv --limit 20
|
||||
|
||||
# Custom output
|
||||
./seo keywords gsc_export.csv --output keywords.csv
|
||||
```
|
||||
|
||||
**What It Finds:**
|
||||
|
||||
- Keywords ranking positions 5-20 (easy to improve)
|
||||
- High impression keywords with low CTR
|
||||
- Keywords with good traffic potential
|
||||
|
||||
**Example Output:**
|
||||
|
||||
```
|
||||
✅ Found 47 keyword opportunities!
|
||||
|
||||
Top opportunities:
|
||||
1. best vpn 2024 - Position: 8.5, Impressions: 1250
|
||||
2. torrent client - Position: 12.3, Impressions: 890
|
||||
3. vpn for gaming - Position: 9.1, Impressions: 650
|
||||
```
|
||||
|
||||
### 3. `seo report` - Generate SEO Report
|
||||
|
||||
Create comprehensive SEO performance reports.
|
||||
|
||||
**Usage:**
|
||||
|
||||
```bash
|
||||
# Generate report
|
||||
./seo report
|
||||
|
||||
# Custom output
|
||||
./seo report --output monthly_seo_report.md
|
||||
```
|
||||
|
||||
**Report Includes:**
|
||||
|
||||
- Performance summary
|
||||
- Traffic analysis
|
||||
- Keyword opportunities
|
||||
- SEO recommendations
|
||||
- Action items
|
||||
|
||||
## Data Export Guides
|
||||
|
||||
### Export from Google Analytics 4
|
||||
|
||||
1. Go to **Google Analytics** → Your Property
|
||||
2. Navigate to **Reports** → **Engagement** → **Pages and screens**
|
||||
3. Set date range (e.g., last 30 days)
|
||||
4. Click **Share** → **Download file** → **CSV**
|
||||
5. Save as `ga4_export.csv`
|
||||
|
||||
**Required Columns:**
|
||||
- Page path
|
||||
- Page title
|
||||
- Views (pageviews)
|
||||
- Sessions
|
||||
- Bounce rate
|
||||
- Engagement rate
|
||||
|
||||
### Export from Google Search Console
|
||||
|
||||
1. Go to **Google Search Console** → Your Property
|
||||
2. Click **Performance** → **Search results**
|
||||
3. Set date range (e.g., last 30 days)
|
||||
4. Check all metrics: Clicks, Impressions, CTR, Position
|
||||
5. Click **Export** → **CSV**
|
||||
6. Save as `gsc_export.csv`
|
||||
|
||||
**Required Columns:**
|
||||
- Page (URL)
|
||||
- Clicks
|
||||
- Impressions
|
||||
- CTR
|
||||
- Position
|
||||
|
||||
## API Integration (Advanced)
|
||||
|
||||
For automated data fetching, configure API credentials:
|
||||
|
||||
### 1. Google Analytics 4 API
|
||||
|
||||
**Setup:**
|
||||
|
||||
1. Go to [Google Cloud Console](https://console.cloud.google.com/)
|
||||
2. Create a new project or select existing
|
||||
3. Enable **Google Analytics Data API**
|
||||
4. Create service account credentials
|
||||
5. Download JSON key file
|
||||
6. Share GA4 property with service account email
|
||||
|
||||
**Configuration:**
|
||||
|
||||
Add to `.env`:
|
||||
```
|
||||
GA4_CREDENTIALS=/path/to/ga4-credentials.json
|
||||
GA4_PROPERTY_ID=properties/123456789
|
||||
```
|
||||
|
||||
### 2. Google Search Console API
|
||||
|
||||
**Setup:**
|
||||
|
||||
1. Go to [Google Cloud Console](https://console.cloud.google.com/)
|
||||
2. Enable **Search Console API**
|
||||
3. Create service account credentials
|
||||
4. Download JSON key file
|
||||
5. Share GSC property with service account email
|
||||
|
||||
**Configuration:**
|
||||
|
||||
Add to `.env`:
|
||||
```
|
||||
GSC_CREDENTIALS=/path/to/gsc-credentials.json
|
||||
GSC_SITE_URL=https://www.mistergeek.net
|
||||
```
|
||||
|
||||
### Using API Mode
|
||||
|
||||
Once configured, you can run without CSV files:
|
||||
|
||||
```bash
|
||||
# Fetch data directly from APIs
|
||||
./seo performance --start-date 2024-01-01 --end-date 2024-01-31
|
||||
```
|
||||
|
||||
## Performance Insights
|
||||
|
||||
### Low CTR Pages
|
||||
|
||||
Pages with high impressions but low CTR need better titles/descriptions:
|
||||
|
||||
```bash
|
||||
# Find pages with <2% CTR and 100+ impressions
|
||||
./seo performance --gsc search.csv
|
||||
# Check "low_ctr" section in output
|
||||
```
|
||||
|
||||
**Action:** Optimize meta titles and descriptions
|
||||
|
||||
### Low Position Pages
|
||||
|
||||
Pages ranking beyond position 20 need content optimization:
|
||||
|
||||
```bash
|
||||
# Find pages ranking >20 with 50+ impressions
|
||||
./seo performance --gsc search.csv
|
||||
# Check "low_position" section in output
|
||||
```
|
||||
|
||||
**Action:** Improve content quality, add internal links
|
||||
|
||||
### Keyword Opportunities
|
||||
|
||||
Keywords ranking 5-20 are easy to improve:
|
||||
|
||||
```bash
|
||||
./seo keywords gsc_export.csv --limit 50
|
||||
```
|
||||
|
||||
**Action:** Optimize content for these specific keywords
|
||||
|
||||
## Workflow Examples
|
||||
|
||||
### Weekly Performance Check
|
||||
|
||||
```bash
|
||||
# 1. Export fresh data from GA4 and GSC
|
||||
# 2. Analyze performance
|
||||
./seo performance --ga4 weekly_ga4.csv --gsc weekly_gsc.csv
|
||||
|
||||
# 3. Review keyword opportunities
|
||||
./seo keywords weekly_gsc.csv --limit 20
|
||||
|
||||
# 4. Generate report
|
||||
./seo report --output weekly_report.md
|
||||
```
|
||||
|
||||
### Monthly SEO Audit
|
||||
|
||||
```bash
|
||||
# 1. Export full month data
|
||||
# 2. Comprehensive analysis
|
||||
./seo performance --ga4 month_ga4.csv --gsc month_gsc.csv
|
||||
|
||||
# 3. Identify top issues
|
||||
# Review output for:
|
||||
# - Low CTR pages
|
||||
# - Low position pages
|
||||
# - High impression, low click pages
|
||||
|
||||
# 4. Generate action plan
|
||||
./seo report --output monthly_audit.md
|
||||
```
|
||||
|
||||
### Content Optimization Sprint
|
||||
|
||||
```bash
|
||||
# 1. Find keyword opportunities
|
||||
./seo keywords gsc.csv --limit 50 > opportunities.txt
|
||||
|
||||
# 2. For each opportunity:
|
||||
# - Review current content
|
||||
# - Optimize for target keyword
|
||||
# - Update meta description
|
||||
|
||||
# 3. Track improvements
|
||||
# Re-run analysis after 2 weeks
|
||||
./seo performance --gsc new_gsc.csv
|
||||
```
|
||||
|
||||
## Output Files
|
||||
|
||||
All analysis results are saved to `output/`:
|
||||
|
||||
| File | Description |
|
||||
|------|-------------|
|
||||
| `performance_data_*.csv` | Raw performance metrics |
|
||||
| `performance_analysis_*.csv` | Analysis with insights |
|
||||
| `seo_report_*.md` | Markdown report |
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### No Data Loaded
|
||||
|
||||
**Problem:** "No data loaded. Provide GA4 and/or GSC export files."
|
||||
|
||||
**Solution:**
|
||||
- Ensure CSV files are properly exported
|
||||
- Check file paths are correct
|
||||
- Verify CSV has required columns
|
||||
|
||||
### Column Name Errors
|
||||
|
||||
**Problem:** "KeyError: 'pageviews'"
|
||||
|
||||
**Solution:**
|
||||
- Ensure GA4 export includes pageviews column
|
||||
- Column names are normalized automatically
|
||||
- Check CSV encoding (UTF-8)
|
||||
|
||||
### API Authentication Errors
|
||||
|
||||
**Problem:** "Failed to initialize GA4 client"
|
||||
|
||||
**Solution:**
|
||||
- Verify service account JSON is valid
|
||||
- Check API is enabled in Google Cloud
|
||||
- Ensure service account has access to property
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Data Collection
|
||||
|
||||
1. **Export regularly** - Weekly or monthly exports
|
||||
2. **Consistent date ranges** - Use same range for comparisons
|
||||
3. **Keep historical data** - Archive old exports for trend analysis
|
||||
|
||||
### Analysis
|
||||
|
||||
1. **Focus on trends** - Look at changes over time
|
||||
2. **Prioritize impact** - Fix high-traffic pages first
|
||||
3. **Track improvements** - Re-analyze after optimizations
|
||||
|
||||
### Reporting
|
||||
|
||||
1. **Regular reports** - Weekly/monthly cadence
|
||||
2. **Share insights** - Distribute to team/stakeholders
|
||||
3. **Action-oriented** - Include specific recommendations
|
||||
|
||||
## Related Commands
|
||||
|
||||
- `seo export` - Export posts from WordPress
|
||||
- `seo meta_description` - Generate meta descriptions
|
||||
- `seo update_meta` - Update meta on WordPress
|
||||
|
||||
## See Also
|
||||
|
||||
- [README.md](README.md) - Main documentation
|
||||
- [META_DESCRIPTION_GUIDE.md](META_DESCRIPTION_GUIDE.md) - Meta description guide
|
||||
- [ANALYTICS_SETUP.md](ANALYTICS_SETUP.md) - API setup guide (if exists)
|
||||
|
||||
---
|
||||
|
||||
**Made with ❤️ for better SEO automation**
|
||||
Reference in New Issue
Block a user