SerpIQ — User documentation

Introduction

SerpIQ connects your WordPress site to Google Search Console (GSC), stores search analytics in your database, and provides reports in the WordPress admin: dashboard KPIs, keywords, pages, opportunities, cannibalization, alerts, and more.

You need a Google account with access to a Search Console property for your site, and you must create OAuth credentials in Google Cloud (see below).

Requirements

Server & WordPress

• WordPress 6.0 or higher (tested up to 6.7+).
• PHP 8.0 or higher.
• HTTPS strongly recommended for production. OAuth and Google APIs expect a secure site; use a valid TLS certificate.
• MySQL/MariaDB as in standard WordPress hosting.
• Outbound HTTPS to Google APIs (Search Console, OAuth) must be allowed (no long firewall blocks).

PHP limits (imports)

• memory_limit: at least 128 MB; 256 MB+ recommended for large historical imports.
• max_execution_time: at least 60 s per request; 120–300 s helps heavy cron batches.

WordPress cron

Background sync and historical imports rely on WordPress cron. If DISABLE_WP_CRON is true in wp-config.php, configure a real server cron that hits wp-cron.php every few minutes, or imports may stall.

Installation

1. Unzip the plugin package if needed. Upload the serpiq folder to wp-content/plugins/ (or install via ZIP in Plugins → Add New → Upload Plugin).
2. Activate SerpIQ under Plugins.
3. Ensure vendor/ is present (Composer dependencies). The distributed package includes it; do not delete it.
4. Go to SerpIQ → Settings and follow the Google OAuth steps below before expecting data.

Video tutorial

If you prefer, you can follow the setup steps in this video guide.

Open the video on YouTube.

Google Cloud & OAuth setup

You must create an OAuth Client ID (type: Web application) in Google Cloud Console and paste the Client ID and Client Secret into SerpIQ → Settings.

1. Google Cloud project

1. Open Google Cloud Console and select a project (1) or create a new one (2). To create a new project, click the currently selected project to open the project selector dialog, then click the New project button.

   

   

2. Enable the Google Search Console API for that project (APIs & Services → Library → search “Search Console API” → Enable). To proceed, type Google Search Console API in the search field (3), then select the Google Search Console API result and click Enable (4).

   

   

3. After enabling the Google Search Console API, you should see the screen shown below.

   

2. OAuth client (Web application)

1. Now click on Credentials → Create Credentials → OAuth client ID (6).

   

2. Come Application Type seleziona Web application (7).

   

3. Now you should see the screen shown below. In the Name field you can enter any value, but it is essential to fill in the Authorised redirect URIs field (8) with https://YOUR-DOMAIN.com/wp-admin/admin.php?page=serpiq-settings, which you can find in the SerpIQ Settings section. Important: replace YOUR-DOMAIN.com with your own domain name.

   

4. Now click the Create button. You will see a pop-up window showing the Client ID and Client Secret, which you must copy and save. You can also download the JSON file containing these values.

   

   Important: if you close this window without saving the Client ID and Client Secret, you won’t be able to retrieve them later and you will need to create new credentials.

   Once you’ve copied the credentials, click OK.

5. Now proceed with the final step: in the OAuth 2.0 Client IDs section, click the name of the Web application client you just created (9) (in the example shown in the image, Web client 2).

   

   Now click Audience and then Publish app. In the pop-up window that appears, click Confirm to complete the process.

   

First connection to Search Console

1. Go to SerpIQ → Settings and paste the Client ID and Client Secret into their respective fields. First click Save Settings, then click Connect to Google.

   

2. Sign in with the Google account that has access to Search Console for this site.
3. Accept the requested permissions. SerpIQ will try to detect the Search Console property that matches your site’s domain.
4. After success, you should see connection status and property information in Settings.

If no property is found, verify that a GSC property exists for your URL (same protocol and host as your live site) and that the signed-in user has access.

Sync & import

• Manual sync: pulls recent data (typically a short window such as the last few days) depending on settings.
• Automatic daily sync: after setup, a scheduled task can refresh data periodically.
• First-time / historical import: SerpIQ may offer importing a longer range (e.g. last weeks or months) in background batches to avoid timeouts. Adjust “days per batch”, delay between batches, and rows per DB batch in Settings if your host is slow or hits limits.
• Import diagnostics: in Settings, use the diagnostics panel to see job status, cron health, and errors (without exposing raw search queries in support copies).

Main plugin sections

Dashboard

Overview: clicks, impressions, CTR, position, charts, top queries/pages, alerts summary.

Keywords

Search queries report with filters, sorting, CSV export.

Pages

Landing page URLs performance; export to CSV.

Opportunities

Reports such as high impressions / low CTR and “quick win” positions; CSV export.

Cannibalization

Queries where multiple URLs compete; helps prioritize consolidation.

Decay / Content refresh / Internal links / Question queries

Additional reports depending on your plugin version—use the in-app labels and date range selector.

Settings

Google OAuth, sync/import options, diagnostics, uninstall data option.

Use the global date range in the header where available so all reports stay consistent.

Troubleshooting

Cron not running

Symptoms: historical import never progresses, diagnostics warn that no SerpIQ cron ran recently. Fix: ensure WordPress cron runs (system cron calling wp-cron.php if disabled, or fix host blocking).

Google API quota / rate limits

Reduce batch size or spread imports over time; wait for quota reset; use a dedicated Cloud project if you hit project limits.

PHP memory / timeout

Lower “days per batch” and rows per DB batch; ask the host to raise memory_limit and max_execution_time.

OAuth / redirect errors

Re-check redirect URI in Google Cloud, site URL and admin URL (HTTP vs HTTPS), and that clocks are correct.

Uninstall & data removal

SerpIQ stores data in custom database tables (prefixed, e.g. serpiq_) and in WordPress options (tokens, keys, settings).

1. In SerpIQ → Settings, find the option to delete plugin data on uninstall (wording may vary) and enable it if you want a full cleanup when removing the plugin.
2. Deactivate SerpIQ under Plugins, then Delete the plugin.

If “delete data on uninstall” is enabled, uninstall removes SerpIQ tables and related options (including encrypted OAuth tokens and plugin settings) according to the plugin’s uninstall.php logic.

If it is disabled, uninstall may leave tables and options in the database; you may need manual cleanup or re-installation with the same data.

Privacy & third-party services

Site administrators are responsible for compliance with applicable laws (including GDPR where relevant), for providing any required privacy notices to site visitors, and for obtaining consents where needed.

SerpIQ does not send front-end visitor traffic to SerpIQ or to a SerpIQ-operated tracking API. It does not inject marketing or analytics trackers into public pages for SerpIQ’s purposes.

Google (Search Console & OAuth)

• SerpIQ uses Google’s APIs and OAuth to read Search Console data you are authorized to access.
• Data is fetched from Google and stored locally in your WordPress database for reporting.
• Users who connect must have a Google account and accept Google’s terms and policies for Search Console and Google Cloud/OAuth.
• Network traffic to Google is sent over HTTPS; content depends on what Google returns for your property.
• Read-only OAuth scope used: https://www.googleapis.com/auth/webmasters.readonly.
• Official references: Google Privacy Policy, Google APIs Terms of Service.

Admin UI typography

SerpIQ screens in the WordPress admin use a system font stack defined in bundled CSS. No third-party font stylesheets are loaded for the plugin UI.

Outbound network summary

For a technical list of endpoints (Google OAuth, Search Console API, same-site REST), see documentation/network-and-privacy.txt in the plugin package.

What stays on your server

• Imported GSC metrics and related plugin data in the database (until deleted or uninstalled per settings).
• OAuth tokens and plugin settings in WordPress options (until removed).

This section is a high-level summary only and does not replace legal advice or your own privacy policy for end users of your website.

Installer / site owner obligations

If you use SerpIQ on a public website, you are typically responsible for:

• Telling end users (where the law requires it) that you use Google services—at least at the level of transparency required in your jurisdiction.
• Maintaining a privacy policy or legal notices appropriate to your site, and linking them where required (footer, cookie banner flow, etc.). SerpIQ does not provide that legal text for you.
• Ensuring that only authorized staff connect Google accounts and manage API keys.

Plugin readme & listing compliance

This subsection is for maintainers and contributors preparing the WordPress.org plugin readme or similar public listing. End users normally read the readme on the plugin page, not this HTML file.

Third-party dependencies (disclose clearly)

SerpIQ depends on the following when used as designed:

• Google Search Console API (via Google API Client for PHP): read-only access to search analytics for a property the user is allowed to access.
• Google OAuth 2.0: the site administrator signs in with a Google account and authorizes the app; tokens are stored in the WordPress database.

What to avoid promising

• Do not claim guaranteed rankings, traffic, or revenue.
• Do not suggest the plugin replaces Google Search Console, Google Analytics, or professional SEO advice.
• Describe features as they work in the product: reports, exports, sync—nothing more.

Trademarks & branding (Google, etc.)

• Primary listing name should remain SerpIQ (or your distinct brand), not “Google …” as the product title. Describe integration as “for Search Console” or “uses Google Search Console data” where needed.
• Use plain text such as “Google Search Console” or “Google OAuth” where you need to explain functionality—descriptive use is normal for software documentation.
• Avoid official Google logos, product icons, or trade dress in screenshots or promotional graphics unless you have permission that satisfies Google’s brand guidelines.
• Do not name the plugin in a way that suggests it is an official Google product; state independence (“not affiliated with Google”) in readme/header when appropriate.

Privacy wording for users (summary)

Make clear that the person who installs the plugin must respect privacy and data-protection rules applicable to their site: they connect Google services, store analytics-related data locally, and may need to update their privacy policy and internal processes accordingly. Point them to the Privacy & third-party services section of this documentation.

Ready-to-adapt copy

See the plain-text file documentation/listing-description-notes.txt in the plugin package for short and long description blocks you can adapt for the readme or listing.