# Google Search Console Integration ## Complete Implementation Plan for IGNY8 **Version:** 1.0 | **January 2026** --- # 1. EXECUTIVE SUMMARY ## 1.1 What We're Building | Capability | Description | |------------|-------------| | Connect Once | Single Google account connection manages all sites | | Auto-Index | Every IGNY8 article automatically submitted to Google | | Monitor | See which pages are indexed, pending, or have issues | | Performance | View clicks, impressions, keywords in IGNY8 | | Manual Control | Inspect and request indexing for any URL | ## 1.2 Problem vs Solution **BEFORE:** Content published → Wait for Google → Maybe indexed in weeks/months → 43% NOT indexed after 1 year **AFTER:** Content published → Auto-inspect → Auto-request indexing → Status synced to WordPress → 90%+ indexed in 2-4 weeks ## 1.3 API Choice: URL Inspection API | Aspect | URL Inspection API (WE USE) | Indexing API (NOT USING) | |--------|----------------------------|--------------------------| | Restrictions | NONE - any URL | JobPosting/Events only | | Daily Quota | ~2,000/day | ~200/day | | Risk Level | Zero | High | ## 1.4 Integration Model ``` IGNY8 APP (Central Hub) ┌─────────────────────────────────────┐ │ Google OAuth Token (ONE time) │ └─────────────────┬───────────────────┘ │ ┌─────────────┼─────────────┐ ▼ ▼ ▼ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ Site A │ │ Site B │ │ Site C │ │(Plugin) │ │(Plugin) │ │(Plugin) │ └─────────┘ └─────────┘ └─────────┘ ``` --- # 2. ARCHITECTURE ## 2.1 System Components ``` ┌─────────────────────────────────────────────────────────┐ │ IGNY8 APP │ │ │ │ ┌────────────┐ ┌────────────┐ ┌────────────┐ │ │ │GSC Service │ │Queue Serv. │ │Metrics Srv │ │ │ │• OAuth │ │• URL queue │ │• Fetch data│ │ │ │• Tokens │ │• Rate limit│ │• Cache │ │ │ │• Mapping │ │• Status │ │• Filter │ │ │ └─────┬──────┘ └─────┬──────┘ └─────┬──────┘ │ │ └──────────────┼──────────────┘ │ │ ▼ │ │ ┌───────────────────────┐ │ │ │ Background Workers │ │ │ │ (Celery) │ │ │ │ • Process queue │ │ │ │ • Re-inspect URLs │ │ │ │ • Sync to plugins │ │ │ └───────────┬───────────┘ │ └───────────────────────┼──────────────────────────────────┘ │ ┌─────────────┴─────────────┐ ▼ ▼ ┌──────────────────────┐ ┌──────────────────────┐ │ GOOGLE APIS │ │ WORDPRESS SITES │ │ • URL Inspection API │ │ • IGNY8 Plugin │ │ • Search Analytics │ │ - Receive status │ │ • Sites API │ │ - Display in WP │ └──────────────────────┘ └──────────────────────┘ ``` ## 2.2 Data Flow ``` User connects Google → OAuth tokens stored → Fetch GSC sites → Map to IGNY8 sites │ ┌───────────────────────────────────────────┼───────────────────┐ ▼ ▼ ▼ AUTO-INDEXING MANUAL INDEXING METRICS IGNY8 publishes User selects URLs User views │ │ performance ▼ ▼ │ Add to queue (P:100) Add to queue (P:50) ▼ │ │ Fetch API └───────────────────┬───────────────────────┘ Cache ▼ Worker inspects │ NOT INDEXED? → Request indexing → Schedule re-inspect │ ▼ Sync to WordPress plugin ``` --- # 3. FEATURES ## 3.1 Feature List | # | Feature | Priority | |---|---------|----------| | 1 | GSC OAuth Connection | Critical | | 2 | Site Mapping | Critical | | 3 | URL Inspection | Critical | | 4 | Indexing Requests | Critical | | 5 | Auto-Indexing | Critical | | 6 | Queue Management | Critical | | 7 | Plugin Status Sync | High | | 8 | Search Metrics | High | | 9 | Manual URL Management | Medium | ## 3.2 OAuth Connection **Flow:** User clicks Connect → Google OAuth → User allows → Tokens stored → Sites fetched **Scopes:** `webmasters.readonly`, `webmasters` **Data Stored:** user_id, google_email, access_token (encrypted), refresh_token (encrypted), token_expiry, status, connected_at ## 3.3 Site Mapping **Logic:** For each IGNY8 site, check GSC for: 1. sc-domain:example.com (Domain property) ← Preferred 2. https://example.com (URL prefix) 3. http://example.com (URL prefix) **States:** matched ✓, manual 🔧, not_found ✗ ## 3.4 URL Inspection & Indexing **Decision Flow:** ``` Inspect URL → Parse Response │ ┌───────────┼───────────┐ ▼ ▼ ▼ INDEXED NOT INDEXED ERROR │ │ │ ▼ ▼ ▼ Done! Request indexing Show details │ ▼ Schedule re-inspect (24-48 hrs) ``` ## 3.5 Auto-Indexing Pipeline ``` IGNY8 publishes content │ ▼ Create URL tracking record │ ▼ Add to queue (Priority: 100) │ ▼ ┌─────────────────────────────────────┐ │ BACKGROUND WORKER │ │ │ │ Pick item → Check quota │ │ │ │ │ YES ─┴─ NO │ │ │ │ │ │ ▼ ▼ │ │ Process Skip (retry tomorrow) │ │ │ │ │ ▼ │ │ Call URL Inspection API │ │ │ │ │ ▼ │ │ NOT INDEXED? → Request indexing │ │ │ │ │ ▼ │ │ Sync to WordPress → Wait 3s → Next │ └─────────────────────────────────────┘ ``` ## 3.6 Queue Management **Rules:** 1. One at a time (3 sec between calls) 2. Priority order: 100 (IGNY8 auto) → 90 → 70 → 50 → 30 (re-inspect) 3. Quota: 2,000/day, reset midnight PT 4. Quota exhausted: items stay queued, resume after reset ## 3.7 Plugin Status Sync **Flow:** Status changes → Batch collector (5 min) → POST to plugin → Store in WP DB → Display in admin ## 3.8 Search Metrics **Metrics:** Clicks, Impressions, CTR, Position **Dimensions:** Pages, Keywords, Countries, Devices **Special:** Filter to show ONLY IGNY8 content performance --- # 4. USER EXPERIENCE ## 4.1 First-Time Setup 1. **Discovery:** New "Search Console" menu in IGNY8 2. **Welcome:** Benefits explained, "Connect" button 3. **OAuth:** User selects Google account, grants permission 4. **Mapping:** Shows matched/unmatched sites 5. **Complete:** Ready to use ## 4.2 Indexing Dashboard ``` ┌─────────────────────────────────────────────────────────┐ │ Site: [example.com ▼] │ │ │ │ ┌─────────┬─────────┬─────────┬─────────┐ │ │ │ TOTAL │ INDEXED │ PENDING │ ISSUES │ │ │ │ 53 │ 30 │ 18 │ 5 │ │ │ └─────────┴─────────┴─────────┴─────────┘ │ │ │ │ [IGNY8 Content] [All Site URLs] [Custom URL] │ │ │ │ ┌───────────────────────────────────────────────────┐ │ │ │ □ TITLE/URL PUBLISHED STATUS ACTION │ │ │ ├───────────────────────────────────────────────────┤ │ │ │ □ Best SEO Practices Jan 15 ✓ Indexed │ │ │ │ □ Blue Widget Pro Jan 14 ⏳ Pending │ │ │ │ □ Content Marketing Jan 12 ➡ Requested │ │ │ │ □ Red Widget Jan 10 ⚠ Noindex │ │ │ └───────────────────────────────────────────────────┘ │ │ │ │ Queue: 3 processing • Quota: 1,847/2,000 remaining │ └─────────────────────────────────────────────────────────┘ ``` ## 4.3 Performance Metrics ``` ┌─────────────────────────────────────────────────────────┐ │ Site: [example.com ▼] Date: [Last 28 days ▼] │ │ │ │ ┌───────────┬───────────┬───────────┬───────────┐ │ │ │ CLICKS │ IMPR │ CTR │ POSITION │ │ │ │ 1,234 │ 45,678 │ 2.7% │ 12.4 │ │ │ │ ▲ +15% │ ▲ +8% │ ▲ +0.3% │ ▼ -2.1 │ │ │ └───────────┴───────────┴───────────┴───────────┘ │ │ │ │ [Top Pages] [Top Keywords] [IGNY8 Content ★] │ │ │ │ □ Show only IGNY8 content │ │ │ │ ┌───────────────────────────────────────────────────┐ │ │ │ PAGE CLICKS IMPR CTR POSITION│ │ │ │ ★ /blog/best-seo 342 12,456 2.7% 8.2 │ │ │ │ ★ /product/widget 156 8,234 1.9% 15.4 │ │ │ │ /about-us 89 5,678 1.6% 22.1 │ │ │ └───────────────────────────────────────────────────┘ │ │ │ │ ★ = IGNY8 content [Export to CSV] │ └─────────────────────────────────────────────────────────┘ ``` ## 4.4 WordPress Plugin Display **Content List Column:** ``` □ TITLE DATE STATUS INDEX STATUS □ Best SEO Tips Jan 15 Published ✓ Indexed □ Widget Guide Jan 14 Published ⏳ Pending □ Marketing 101 Jan 12 Published ➡ Requested ``` **Edit Screen Metabox:** ``` ┌─────────────────────────────┐ │ Search Console Status │ │ Index Status: ✓ Indexed │ │ Last Checked: 2 hours ago │ │ ℹ Managed via IGNY8 │ └─────────────────────────────┘ ``` --- # 5. DATA ARCHITECTURE ## 5.1 Database Schema ``` USER (existing) │ └──► GSC_CONNECTION (1:1) │ • google_email │ • access_token (encrypted) │ • refresh_token (encrypted) │ • status │ └──► DAILY_QUOTA (1:N) • date • inspections_used • inspections_limit SITE (existing) │ └──► GSC_SITE_MAPPING (1:1) │ • gsc_property │ • mapping_type │ • status │ └──► URL_INDEXING_RECORD (1:N) │ • url │ • source │ • status │ • last_inspection_result │ └──► INDEXING_QUEUE (1:N) • queue_type • priority • status PUBLISHED_CONTENT (existing) │ └──► URL_INDEXING_RECORD (1:1) METRICS_CACHE (linked to GSC_SITE_MAPPING) • metric_type • date_range • data • expires_at ``` ## 5.2 Status Definitions | Status | Icon | Meaning | |--------|------|---------| | pending_inspection | ⏳ | In queue | | indexed | ✓ | In Google index | | not_indexed | ✗ | Not in index | | indexing_requested | ➡ | Request sent | | error_noindex | 🚫 | Has noindex tag | | error_blocked | 🚫 | Robots.txt blocks | | error_not_found | 🚫 | 404 error | --- # 6. PROCESSING LOGIC ## 6.1 Queue Priority | Priority | Type | |----------|------| | 100 | IGNY8 auto-inspection | | 90 | IGNY8 indexing request | | 70 | Manual indexing request | | 50 | Manual inspection | | 30 | Scheduled re-inspection | ## 6.2 Re-Inspection Schedule | Check # | Delay | Action if not indexed | |---------|-------|----------------------| | 1 | 24 hours | Continue | | 2 | Day 3 | Continue | | 3 | Day 6 | Continue | | 4 | Day 13 | Final check | | 5 | STOP | Mark for manual review | ## 6.3 Quota Management - Daily Limit: 2,000 inspections - Reset: Midnight PT - Exhausted: Items stay queued, resume after reset, user notified --- # 7. API INTEGRATION ## 7.1 Google OAuth - Redirect URI: `https://app.igny8.com/auth/google/callback` - Scopes: `webmasters.readonly`, `webmasters` ## 7.2 URL Inspection API ``` POST https://searchconsole.googleapis.com/v1/urlInspection/index:inspect Request: { "inspectionUrl": "https://example.com/page", "siteUrl": "sc-domain:example.com" } Response fields: verdict, coverageState, robotsTxtState, indexingState, lastCrawlTime ``` ## 7.3 Search Analytics API ``` POST https://searchconsole.googleapis.com/webmasters/v3/sites/{siteUrl}/searchAnalytics/query Request: { "startDate": "2025-01-01", "endDate": "2025-01-28", "dimensions": ["page", "query"], "rowLimit": 1000 } Response: clicks, impressions, ctr, position ``` ## 7.4 Sites API ``` GET https://searchconsole.googleapis.com/webmasters/v3/sites Response: List of sites with siteUrl and permissionLevel ``` --- # 8. WORDPRESS PLUGIN UPDATES ## 8.1 New Components - **Endpoint:** `POST /wp-json/igny8/v1/index-status-sync` - **Table:** url, post_id, status, last_checked, details - **UI:** Content list column, Edit screen metabox, Dashboard widget --- # 9. ERROR HANDLING | Category | Error | Action | |----------|-------|--------| | Connection | OAuth rejected | Retry | | Connection | Token expired | Reconnect | | Mapping | Site not in GSC | Link to GSC | | Indexing | Quota exhausted | Queue for tomorrow | | Indexing | noindex tag | Show warning | | Sync | Plugin unreachable | Retry later | --- # 10. IMPLEMENTATION PHASES | Phase | Weeks | Focus | |-------|-------|-------| | 1 | 1-2 | Core Connection (OAuth, site mapping) | | 2 | 3-4 | URL Inspection (queue, status tracking) | | 3 | 5-6 | Auto-Indexing (hooks, re-inspection) | | 4 | 7 | Plugin Status Sync | | 5 | 8-9 | Performance Metrics | | 6 | 10 | Polish & Optimization | --- # 11. SUCCESS METRICS | Metric | Target | |--------|--------| | GSC connection rate | 50% of active users | | Sites mapped | 80% of user sites | | Auto-indexing enabled | 70% of connected users | | Indexing success rate | >80% within 7 days | | Sync reliability | >99% | | API error rate | <1% | --- # 12. GLOSSARY | Term | Definition | |------|------------| | GSC | Google Search Console | | URL Inspection | Checking URL status in Google's index | | Indexing Request | Asking Google to index a URL | | Impressions | Times page appeared in search | | Clicks | Times users clicked from search | | CTR | Click-through rate | | Position | Average ranking in search | | sc-domain | Domain property type in GSC | | Quota | Daily API usage limits | --- **END OF DOCUMENT**