GSC Connect — Documentation

GSC Connect brings the full power of Google Search Console directly into the PrestaShop back office: one-click OAuth connection, sitemap submission, bulk URL inspection, clicks and position reports by product and category, automatic drop and deindexation alerts. This guide covers installation, Google OAuth setup, first sync, cron scheduling, report reading, common error handling and internal architecture.

Installation

The module deploys like any standard PrestaShop module: no Composer dependency, no persistent worker, no external service besides Google.

1. Download dfgscconnect.zip from your DataFirefly account (download link received after purchase).
2. Back office → Modules → Module Manager → Upload a module.
3. Drag and drop the ZIP. PrestaShop automatically installs the 8 dfgsc_* tables, menu tabs and associated hooks.
4. Click Configure on the module card.

Requirements

• PrestaShop 8.0.0 to 9.99.99
• PHP 7.4, 8.0, 8.1, 8.2 or 8.3
• MySQL 5.6+ or MariaDB 10.3+
• PHP curl extension enabled (default on all hosts)
• A Google account that already has owner or delegated owner access to your store’s Search Console property

Google OAuth setup

The module uses OAuth 2.0 to access Search Console on behalf of the store owner. This step is a one-time setup and takes about 5 minutes. No service account is required: authentication uses the Google account that already has access to your Search Console property.

Step 1 — Create a Google Cloud project

1. Go to console.cloud.google.com with the Google account that owns the Search Console access.
2. Click the project selector at the top, then New project.
3. Name it for example prestashop-gsc and create it.
4. Select this new project once created.

Step 2 — Enable the Search Console API

1. Menu → APIs & Services → Library.
2. Search for Google Search Console API.
3. Click on it then click Enable.

Step 3 — Configure the consent screen

1. Menu → APIs & Services → OAuth consent screen.
2. Choose External if your Google account is not part of a Google Workspace organization, otherwise Internal.
3. Fill in the application name (for example GSC Connect), your support email and your store domain.
4. On the Scopes screen, add the scope https://www.googleapis.com/auth/webmasters (Search Console read/write).
5. On the Test users screen, add your Google address. As long as the screen stays in test mode, this is enough for private use: you don’t need to submit the app for Google verification.

Step 4 — Create OAuth credentials

1. Menu → APIs & Services → Credentials.
2. Create Credentials → OAuth client ID.
3. Application type: Web application.
4. Name: GSC Connect (free).
5. In Authorized JavaScript origins, add your store domain with HTTPS: https://your-store.com.
6. In Authorized redirect URI, paste the exact URL displayed in the PrestaShop module configuration (the OAuth redirect URL box).
7. Click Create. Google displays a Client ID and a Client Secret.

Step 5 — Enter credentials in PrestaShop

1. Back office → module → Configure.
2. Paste the Client ID and Client Secret.
3. Save the form. A Connect to Google button appears.
4. Click it. You are redirected to the Google consent page.
5. Approve the permissions, you are redirected back to the PrestaShop back office.
6. The list of your Search Console properties is fetched automatically: the module selects the one matching your store domain by default.

First launch

Once OAuth is connected, run the first sync to pull in your data:

1. Dashboard tab. The default property is already selected.
2. Click Sync now. The module fetches the last 28 days of data (clicks, impressions, CTR, position) at page and query level. Expect 30 seconds to 2 minutes depending on your catalog size.
3. Sitemaps tab. Candidates are detected automatically (root /sitemap.xml + *_sitemap.xml pattern generated by the PrestaShop gsitemap module). Click Submit next to each relevant sitemap.
4. Inspection tab. Click Enqueue all active products. The queue fills instantly. Actual processing runs via cron while respecting Google’s quota of 2000 inspections per day.

Dashboard

The dashboard groups 8 KPIs over 28 days:

• Clicks — total organic clicks over the window
• Impressions — total SERP impressions
• Average CTR — clicks as a percentage of impressions
• Average position — weighted average position across all queries
• Unread alerts — number of open alerts to address
• Non-indexed pages — number of inspected pages with Google verdict FAIL or NEUTRAL
• Today’s quota — URL Inspection API calls consumed against the daily quota
• Last sync — date and time of the last sync cron pass

Below the KPIs, a 28-day trend chart displays clicks (solid line) and impressions (dashed line on secondary axis). Chart.js is bundled locally, no CDN dependency is loaded.

On the right, the Top 10 products and Top 10 categories rank your pages by clicks with their average position and CTR. URL → entity resolution uses PrestaShop’s native routing: id-slug pattern for products, link_rewrite for categories, cms_lang for CMS pages.

Clicks and position reports

The Reports tab offers three detailed views: Products, Categories, Queries. Each view accepts a configurable lookback: 7 / 14 / 28 / 90 days.

For each row, you get clicks, impressions, CTR and average position. Click any column header to sort (client-side, instant). CSV export produces a UTF-8 file with BOM and semicolon separator (natively Excel-compatible), up to 5000 rows per export.

Window comparison

For each listed product or category, the report also displays the variation against the previous window of the same duration. A significant position drop appears in red, an improvement in green.

Sitemaps

The Sitemaps tab automatically detects candidates on your store:

• https://your-store.com/sitemap.xml — root sitemap
• https://your-store.com/sitemap_index.xml — sitemap index
• *_sitemap.xml pattern at root — generated by the PrestaShop gsitemap module, one file per store and per language

Submit in one click. The module then tracks for you:

• The number of URLs submitted (declared by your sitemap)
• The number of URLs actually indexed (reported by Google)
• The number of errors detected by Google
• The last Googlebot download date

If Google reports errors on a sitemap, an automatic alert is raised: HIGH severity if ≥ 10 errors, otherwise MEDIUM.

Bulk URL inspection

Google’s URL Inspection API caps calls at 2000 per day per property. GSC Connect handles this limit via a queue with automatic retry.

Available actions

• Enqueue all active products — adds all products with visibility both, search or catalog
• Enqueue all categories — adds all active categories (root excluded)
• Re-inspect modified pages — adds only entities marked stale by the actionProductUpdate and actionCategoryUpdate hooks
• Process queue now — for testing, without waiting for cron
• Inspect ad-hoc URL — to validate an immediate fix on a specific page

Stored data

For each inspected URL, the module records:

• Google’s overall verdict: PASS, PARTIAL, FAIL or NEUTRAL
• Coverage state (Indexed, Discovered, Crawled but not indexed, etc.)
• robots.txt status and declared indexability
• Detected rich results (Product, Breadcrumb, Review, etc.)
• AMP status and mobile-friendliness
• Referring sitemap and referring URLs
• Last Googlebot crawl date

Alerts and drops

Three alert families are handled automatically by the module:

Position drops

Detects a significant position drop on an already well-ranked page. Default: drop of 5 positions or more on a page ranked ≤ 50. Adjustable threshold in settings (DFGSC_DROP_POS).

Click drops

Detects a significant drop in clicks on a page that was generating a minimum volume. Default: drop of 30 % with a minimum of 5 clicks on the previous window. Adjustable thresholds in settings (DFGSC_DROP_CLICKS, DFGSC_DROP_MIN_CLICKS).

Deindexations

Raised automatically when an inspected URL returns a FAIL or NEUTRAL verdict, or a DEINDEXED / INDEXING_NOT_ALLOWED coverage state.

Comparison mechanics

Drops comparison runs on a rolling window of 7 days against the previous 7 days, with a 2-day offset to respect Search Console latency. The module compares D-9..D-2 against D-16..D-9.

24h deduplication

The same alert (same page, same type) only fires once per 24h to avoid noise, even if cron runs hourly.

Email notifications

Alerts can be sent by email as an HTML digest grouped by severity, in French or English. Enable them from settings and set the recipient address.

Cron and scheduling

All background tasks go through a single token-protected endpoint, visible in the configuration page:

https://your-store.com/index.php?fc=module&module=dfgscconnect&controller=cron&token=XXXXXXXXXX

Schedule it every 1 to 6 hours from your host’s cron panel (cPanel, Plesk, o2switch, OVH). Example crontab:

0 */2 * * * curl -fsS "https://your-store.com/index.php?fc=module&module=dfgscconnect&controller=cron&token=XXXX" > /dev/null 2>&1

Executed tasks

By default, the endpoint runs every task. You can filter some out with the &tasks= parameter:

Task	Action
sync	Fetches new Search Analytics data (configurable lookback)
inspect	Processes the URL inspection queue while respecting quota
sitemaps	Refreshes submitted sitemap status
drops	Detects position and click drops
notify	Sends email alert digest
prune	Purges completed queue entries and old quota counters

Example to only sync metrics without touching inspection:

curl "https://your-store.com/index.php?fc=module&module=dfgscconnect&controller=cron&token=XXXX&tasks=sync,drops,notify"

Configuration reference

All options are in the module’s Configure page:

Option	Key	Default
Google Client ID	DFGSC_CLIENT_ID	(to fill in)
Google Client Secret	DFGSC_CLIENT_SECRET	(to fill in)
Sync lookback (days)	DFGSC_LOOKBACK_DAYS	28
Daily URL inspection quota	DFGSC_DAILY_QUOTA	2000
Position drop threshold	DFGSC_DROP_POS	5
Click drop threshold (%)	DFGSC_DROP_CLICKS	30
Minimum clicks to detect drop	DFGSC_DROP_MIN_CLICKS	5
Email notifications enabled	DFGSC_ALERT_ENABLED	yes
Alert recipient address	DFGSC_ALERT_EMAIL	admin email
Cron token	DFGSC_CRON_TOKEN	auto-generated

Google API quotas and limits

The Search Console API is free but subject to Google quotas:

• URL Inspection: 2000 calls per day per property, 600 per minute (Google hard limit, non-negotiable)
• Search Analytics: 25000 rows per call, ~1200 calls per minute, 30000 per day (soft cap)
• Sitemaps: 5000 calls per day

The module records all calls per endpoint and per day in the dfgsc_quota table. The inspection queue stops cleanly when the configured quota is reached, raising a MEDIUM severity alert. Counters are automatically purged after 30 days by the prune task.

Architecture and data

The module follows a classic PSR-4 architecture under the namespace DataFirefly/GscConnect/, with a custom autoloader shipped in vendor/autoload.php. No Composer dependency. No external dependency: Google API calls go through native cURL with SSL verification.

Layers

• Api/ — HTTP clients (GoogleOAuth, SearchConsoleClient)
• Model/ — database access repositories (Token, Site, Metric, Inspection, Sitemap, Alert, Queue, Quota)
• Services/ — orchestration (MetricsSync, Inspection, Sitemap, Alert)

Tables created

Table	Role
dfgsc_token	OAuth refresh token + expiration per store
dfgsc_site	Known Search Console properties (per store, with the default one)
dfgsc_metric	Search Analytics rows (by day, by page, optionally by query)
dfgsc_inspection	Local cache of URL inspections with full verdict
dfgsc_sitemap	Submitted sitemap state (URL, submitted, indexed, errors, last download)
dfgsc_alert	Generated alerts (type, severity, page, delta, status)
dfgsc_queue	Inspection queue with pending/processing/done/failed statuses
dfgsc_quota	API call counters per endpoint and per day

Hooks used

• actionAdminControllerSetMedia — back office asset loading
• displayBackOfficeHeader — reserved for future notifications
• actionProductUpdate / actionCategoryUpdate — inspection cache invalidation
• actionObjectProductDeleteAfter / actionObjectCategoryDeleteAfter — orphaned inspection purge

Security

• Cookie-based CSRF state token on the OAuth flow
• hash_equals validation on the cron token
• Refresh token stored in DB, never logged
• Access token never persisted: regenerated on demand from the refresh token and held in memory for the request lifetime
• Anti-listing index.php files in all subdirectories
• Systematic escaping via Tools::safeOutput on all template outputs

Troubleshooting

The “Connect to Google” button does not appear

Check that Client ID and Client Secret are actually saved. Save the form, then reload the configuration page.

Google screen displays redirect_uri_mismatch

The redirect URI in Google Cloud must be strictly identical to the one displayed in the module configuration: same protocol (https), same subdomain (www or not), same path, no trailing slash. Copy-paste without modification.

Sync does not return any data

Check three things: (1) the selected property is actually your store; (2) it has at least 72h of history in Search Console (Google delivers with ~48h latency); (3) the connected Google account has owner or delegated owner access to this property.

Inspections are not happening

Check that cron is scheduled and runs. Then check the day’s quota: if you consumed the 2000 Google calls, the queue is paused until the next day. You can force manually via the Process queue now button.

Email alerts do not arrive

Check that the address is valid, that PrestaShop’s SMTP configuration works (test with a welcome email for example), and that notifications are enabled in the module configuration.

401 or 403 error on Search Console calls

The refresh token was probably revoked on Google’s side (password change, account security, or consent expired). Disconnect and reconnect the store from the configuration.

Quota Exhausted (429) error

The Google quota for the property is reached. Google limits this to 2000 inspections per day, regardless of how many modules or tools query the property. The queue resumes automatically the next day.

Changelog

See the CHANGELOG.md file shipped in the module ZIP for the full list of changes per version.

---

For any question not covered here, contact DataFirefly support at support@datafirefly.com.