Skip to main content

Google Search Console integration

Pulls real Search Console data into Magento so editors can see impressions / clicks / CTR / position per URL without leaving the admin — and so the dashboard widget shows actual SEO outcomes alongside the suite's audit counts.

Why integrate​

  • Close the loop on optimisation. You change a meta title; GSC tells you whether impressions and clicks moved. Without the integration that's a separate browser tab and context switch.
  • Cheap dashboard signal. A 7-day clicks + impressions card next to the audit counts is the single most-asked-about admin home metric.
  • Wider corpus for the auto-healer. Discovered URLs from GSC can feed the 404 Auto-Heal corpus (roadmapped — currently the corpus is url_rewrite-only).

Two auth modes​

How:

  1. In Google Cloud Console: create a service account, download its JSON key
  2. In Search Console (the property's Settings → Users): add the service account's email as a user (Restricted access is enough for read-only)
  3. In Magento: paste the JSON into Stores → Configuration → SEO Suite → Google Search Console → Service account JSON

No browser consent dance. The service account email gets the same access in Search Console that the human owner would have. Ideal when you manage many client stores — one SA can be added to every property.

OAuth refresh token (for end-user-owned setups)​

How:

  1. Create an OAuth 2.0 Client ID in Google Cloud Console
  2. Run through the consent flow once (one-off, manual) to get a refresh token
  3. Paste the client ID, client secret, and refresh token into Magento

Works when the GSC property is owned by an individual who doesn't want to grant a service account access. More setup steps but more familiar.

Either mode encrypts the credentials via Magento's standard core_config_data encryption.

Configuration​

Stores → Configuration → SEO Suite → Google Search Console

FieldDefault
Enable GSC syncNo
Authentication modeService account
Service account JSON(empty) — encrypted
OAuth client ID / secret / refresh token(empty) — secret + token encrypted
GSC property URL(empty) — e.g. https://store.example/ or sc-domain:store.example
Look-back window (days)7 (max 90)
Retention (days)90

Per-store overrides supported — multi-store installs can map each Magento store to its own GSC property.

What the sync pulls​

For each enabled store, daily cron byte8_seosuite_gsc_sync (04:30) calls:

POST https://searchconsole.googleapis.com/webmasters/v3/sites/{property}/searchAnalytics/query
{
  "startDate": "<look_back_days ago>",
  "endDate": "today",
  "dimensions": ["date", "page", "device"],
  "rowLimit": 25000
}

Paginates via startRow until exhausted. Each row is an unique combo of (date, page, device). Rows are upserted into byte8_seosuite_gsc_metrics keyed on (store_id, url_hash, metric_date, device) — re-running the sync over an overlapping date window is safe because GSC backfills today's data for ~48 hours.

CLI​

bin/magento seosuite:gsc:sync                  # all enabled stores, configured look-back
bin/magento seosuite:gsc:sync -s 1             # specific store
bin/magento seosuite:gsc:sync -l 28            # override look-back to 28 days

Output:

GSC sync complete — stores synced 2, rows persisted 18420, errors 0.
View at Marketing → SEO Suite → GSC Performance

Useful right after enabling the integration: do an initial 90-day backfill to populate the dashboard chart immediately.

Admin grid​

Marketing → SEO Suite → GSC Performance

Sortable columns: date, page, device, impressions, clicks, CTR, position. Date-range filter, store filter, full-text URL search.

Default sort: most recent date desc. Click any column header to re-sort (clicks desc to find your top performers, position asc to find what's nearly ranking page-1).

Toolbar: Sync Now triggers an inline run for admins without cron access.

Dashboard widget integration​

The SEO Suite Health widget gains a 5th card showing:

  • clicks (7-day total)
  • impressions (7-day total)
  • last synced timestamp

Card status:

  • Grey "Not synced yet" before the first sync
  • Green when clicks > 0
  • Links to the GSC Performance grid

Performance​

A typical store with ~5000 indexed URLs over a 7-day window produces ~30k–80k metric rows. The bulk-upsert is chunked at 1000 rows per query so even huge catalogs stay under MySQL's max_allowed_packet default.

Daily cron typically completes in 10–30 seconds end-to-end.

Token caching​

Access tokens are cached for 50 minutes (Google's tokens are 60-min lived) so subsequent API calls within the same cron run reuse the same token. The cache key is per-store so different stores can use different credentials cleanly.

What's NOT in this release​

  • URL Inspection API — programmatically requesting indexing for new product URLs. Roadmapped for v2.11.x as a follow-up; needs read-write OAuth scope and a per-product action button.
  • GSC corpus into the auto-healer — feeding GSC's "Discovered URLs" into the 404 auto-heal corpus to widen what it can match against. Roadmapped — currently the corpus is url_rewrite-only.
  • SERP ranking history charts — per-product 90-day position chart on the product edit form. Nice-to-have, not in scope for v2.11.

Limitations​

  • GSC has a ~48h delay on today's data, so today's metric row will be incomplete and revised over the next two days
  • GSC's per-day rowLimit is 25000 rows — for catalogs with more than ~100k URLs, you may not capture every long-tail URL on every sync. The default 7-day look-back keeps within limits for typical stores; reduce if you have a very large catalog
  • The integration is read-only — it doesn't write anything back to GSC