# 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…

- Page: <https://www.datafirefly.com/en/documentation/dfgscconnect/>
- Language: en
- Last updated: 2026-06-29
- Other languages: [fr](https://www.datafirefly.com/documentation/dfgscconnect/index.md), [es](https://www.datafirefly.com/es/documentation/dfgscconnect/index.md), [de](https://www.datafirefly.com/de/documentation/dfgscconnect/index.md), [it](https://www.datafirefly.com/it/documentation/dfgscconnect/index.md), [pl](https://www.datafirefly.com/pl/documentation/dfgscconnect/index.md), [pt](https://www.datafirefly.com/pt/documentation/dfgscconnect/index.md), [nl](https://www.datafirefly.com/nl/documentation/dfgscconnect/index.md)
- Index: <https://www.datafirefly.com/en/documentation/llms.txt>

**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.

**Multistore native.** The module is multistore. Each store stores its own OAuth token, its own Search Console property and its own metrics history. You can connect one store without touching the others.

### 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](https://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**.

**The redirect URL must match exactly.** Including protocol (`https`), subdomain (`www` or not) and trailing-slash absence. One difference and Google blocks the connection with `redirect_uri_mismatch`.

### 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.

**Search Console latency.** Google delivers Search Analytics data with about 48h of lag. If you just connected, some metrics from yesterday or the day before won't be available yet. That's normal. The module accounts for this automatically in drop calculations (rolling window with 2-day offset).

## 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

**Deindexation detected → automatic alert.** If the verdict is FAIL or NEUTRAL, or the coverage state is DEINDEXED or INDEXING_NOT_ALLOWED, a HIGH alert is raised automatically with the reason returned by Google.

## 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"
```

**Shared hosting compatible.** No Redis, BullMQ, persistent worker or dedicated PHP-FPM dependency. The cron endpoint is a plain HTTPS URL protected by a token. Works natively on o2switch, OVH shared and any standard Linux hosting.

## 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._