=== Seotune Search Insights ===
Contributors: seotune
Tags: seo, google search console, analytics, keywords, queries
Requires at least: 6.2
Tested up to: 6.9
Requires PHP: 8.0
Stable tag: 1.0.1
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Search Console analytics and SEO insights in your WordPress admin. Connect with OAuth; data stored in your DB. Not affiliated with Google.

== Description ==

Seotune Search Insights connects to Google Search Console, stores search analytics in your WordPress database, and provides an admin dashboard with KPIs, reports, and actionable SEO insights.

For setup help, see the [Documentation](https://seotune.app/documentation/).

**Without external accounts:** The plugin installs and activates like any other plugin, but **reports and sync require** a Google Cloud OAuth client and a Google account with access to a Search Console property for your site. Until you complete connection in **Seotune Search Insights → Settings**, no Search Console data is fetched and dashboards stay empty.

**Features**

* **Connection**: OAuth connection to GSC; automatic detection of the property matching your site domain (no manual property picker).
* **Dashboard**: Overview with clicks, impressions, CTR, position; charts; top queries and pages; recent alerts.
* **Keywords**: Filterable, sortable report with export to CSV.
* **Pages**: Same for page URLs with export to CSV.
* **Opportunities**: Two reports — high impressions / low CTR, and keywords in positions 8–20 (quick wins); CSV export.
* **Cannibalization**: Queries with multiple pages competing; per-query URL list. Normalized by URL (fragment stripped).
* **Decay**: Pages with declining organic performance vs the previous period; filters, probable-cause hints, CSV export.
* **Content Refresh**: Pages prioritized for refresh (urgency levels) with reasons and metrics; CSV export.
* **Internal Links**: Internal linking opportunities from WordPress content and GSC signals; filters; CSV export.
* **Question Queries**: Question-style search queries with difficulty signals and metrics (from GSC data).
* **Alerts**: Automatic detection of position drop, CTR drop, traffic drop, impressions spike (runs after daily sync); list on the Dashboard and CSV export.
* **Export**: CSV export for queries, pages, opportunities, alerts, decay, content refresh, and internal linking (with filters where applicable; UTF-8 BOM for Excel).
* **Settings**: Google OAuth credentials, connect/disconnect, Sync & Import (auto-import last 28 days on first connection, sync now 3/7 days, import range in background), advanced import tuning, and import diagnostics.

Data is synced for the last 3 days on manual run or via a daily cron. After the **first successful connection** to Google Search Console, Seotune Search Insights automatically imports the last **28 days** so that the Dashboard and reports are not empty; you can then use Sync & Import to extend or restart the import for a larger range. After the first import, data is updated automatically every day via cron. Historical data can be imported in background batches (by default 7 days per batch and 1000 rows per DB write) that stay within sensible Google Search Console usage and are tuned for performance; you can adjust these values from Settings → Sync & Import if needed. The Sync & Import card also includes an **Import diagnostics** panel that shows recent import activity, cron status, and common issues (e.g. cron not running, API quota, PHP/DB limits) without exposing sensitive query data. Custom database tables use a **plugin-specific** prefix (in addition to your WordPress table prefix).

== Privacy ==

This plugin **does not** send your site’s front-end visitor traffic to Seotune Search Insights or to a proprietary Seotune API. It **does not** add visitor tracking, advertising pixels, or marketing analytics to the public site.

**Declared service data (administrators)**

* **Google OAuth 2.0 & Search Console API** (required for core features): After you add OAuth credentials and connect, the server communicates with Google to authorize and to read Search Console data you are allowed to access. Tokens and imported metrics are stored **in your WordPress database**. Google’s terms and privacy policies apply to Google accounts and APIs: [Google Privacy Policy](https://policies.google.com/privacy), [Google APIs Terms of Service](https://developers.google.com/terms).
* **Admin UI typography**: The dashboard uses the operating system’s UI fonts (system font stack in local CSS) in the **WordPress admin only**; it does not load third-party font stylesheets for Seotune Search Insights screens.

**Responsibility**: Site owners should inform end users where required by law (e.g. privacy policy, cookie/consent flows) that Search Console-related data is processed when administrators connect Google services.

Technical map (endpoints, when requests run): `documentation/network-and-privacy.txt`. Narrative guide: `documentation/index.html` (Privacy & third-party services).

== Frequently Asked Questions ==

= Do I need a Google account and OAuth credentials? =

Yes. Seotune Search Insights reads **your** Google Search Console data for the site you verify in Search Console. You create an **OAuth client** in Google Cloud Console, paste the Client ID and Client Secret into **Seotune Search Insights → Settings**, then click **Connect to Google** and approve access in your browser. Without this step, the plugin cannot fetch metrics and reports stay empty.

= Where is my Search Console data stored? =

Imported metrics, OAuth tokens, and plugin settings are stored **in your WordPress database** on your server (custom tables use a plugin-specific prefix). Data is not sent to Seotune Search Insights or to a third-party analytics service for Seotune Search Insights’s own use. Only administrators who can access your WordPress admin can see the dashboard.

= How often does data update? Why might numbers look old? =

After you connect, Seotune Search Insights **syncs recent days** on a schedule and can **import more history** from **Seotune Search Insights → Settings → Sync & Import**. Day-to-day updates rely on **WordPress cron** (and your server running scheduled tasks). If numbers do not refresh, cron may not be running—see **Troubleshooting** and **Hosting requirements** below.

= What happens when I uninstall the plugin? =

By default, uninstalling **does not** remove plugin tables or options. If you want a full cleanup, enable the option to **delete plugin data on uninstall** in **Seotune Search Insights → Settings** (wording may vary; see the bundled manual under *Uninstall & data removal*) **before** you delete the plugin from **Plugins**. When that option is on, the plugin’s `uninstall.php` removes the plugin tables and related stored settings (including OAuth tokens) as implemented in that release.

= Does Seotune Search Insights track my website visitors? =

No. Seotune Search Insights does **not** add visitor tracking, advertising pixels, or marketing scripts to your public pages. It works with **Search Console** data that Google already collects for your property, shown to **logged-in administrators** in the WordPress admin.

== Troubleshooting ==

=== Import diagnostics panel ===

In **Seotune Search Insights → Settings → Sync & Import** you will find an **Import diagnostics** box:

* A status badge (OK / WARNING / ERROR) with a short message and a hint.
* A table of the latest import jobs (manual sync, historical batches, internal links index), showing time, range, rows, duration, and result.
* A **Copy log for support** button that copies a plain-text summary (timestamps, job types, technical messages) which you can paste into a support ticket. No search queries, URLs, or user-identifiable data are included.

The panel is read-only and is meant to help you and support quickly understand what is happening on your server.

=== Common messages and what to do ===

* **“Cron may not be running regularly” / “No plugin cron jobs have run in the last few hours”**  
  This usually means WordPress cron is disabled or not being triggered. Check `wp-config.php` for `DISABLE_WP_CRON`. If it is set to `true`, configure a real server cron job that calls `wp-cron.php` every few minutes, or ask your hosting provider to set this up.

* **“Historical import is marked as running, but no backfill batches have completed yet”**  
  The backfill state is “running” but no historical batches are logged. This is typically another sign that cron is not firing. Verify the cron configuration as above, then wait a few minutes and refresh the page.

* **“Historical import seems stuck (no progress for a while)”**  
  If the progress bar stays at 0% or does not move for a long time, use **Stop / Reset import** in the Sync & Import card, then start a new import with smaller batches (lower “Days per batch”). Also make sure cron is running.

* **Search Console quota / rate limit errors in the log**  
  If recent log entries mention quota or rate-limit errors from the Google Search Console API, try lowering **Days per batch** for the historical import, and consider running imports at quieter times of day. If the issue persists, you may need to wait for quotas to reset or use a dedicated Google Cloud project.

* **PHP execution time, memory, or database errors in the log**  
  Messages mentioning maximum execution time, memory limits, or database connection issues indicate that the server limits are too strict for large imports. Try reducing **Days per batch** and, if needed, ask your hosting provider to increase PHP `memory_limit` and `max_execution_time`, or to relax database limits for background jobs.

== Hosting requirements (for smooth import) ==

Seotune Search Insights’ **historical import** runs in the background via WordPress cron: each cron run processes one batch (a few days of data), then schedules the next. For the import to complete without blocking or stalling, the hosting environment must meet the following.

**Default settings** (7 days per batch, 60 seconds delay between batches, 1000 rows per DB batch) are chosen to work on most hosting. On servers with more resources you can increase **Days per batch** and reduce **Delay between batches** in Seotune Search Insights → Settings → Sync & Import for a faster import.

**Minimum (plugin runs, import may be slow or need tuning)**

* **PHP**: 8.0 or higher (required by the plugin).
* **PHP memory_limit**: at least **128 MB**. Lower values can cause out-of-memory errors during import.
* **PHP max_execution_time**: at least **60 seconds** for each cron run (single batch). Many shared hosts use 30s; that can be enough for small batches but may cause timeouts on heavier batches.
* **WordPress cron**: Must run regularly (at least every 5–10 minutes). If `DISABLE_WP_CRON` is set to `true` in `wp-config.php`, a **system cron job** must call `wp-cron.php` (or trigger WordPress cron) every few minutes; otherwise the import never advances.
* **MySQL**: Standard WordPress requirements; no extra extensions needed. The plugin writes data in batches (configurable: 100–2000 rows per batch).

**Recommended (smooth, reliable import)**

* **PHP memory_limit**: **256 MB** or more.
* **PHP max_execution_time**: **120–300 seconds** for cron/CLI so each batch has enough time to fetch data from Google and write to the database.
* **Cron**: Triggered every **1–2 minutes** (e.g. system cron every 2 minutes) so batches run frequently and the import completes in a reasonable time.
* **Network**: Outbound HTTPS to Google APIs (Search Console) without long timeouts or blocks.

**Restrictive shared hosting (e.g. some Aruba, or low-resource plans)**

On hosting with strict limits (low memory, 30s execution time, or cron that rarely runs), the import can block, time out, or appear stuck. To improve reliability:

1. **Cron**: Ensure WordPress cron actually runs. If the host uses `DISABLE_WP_CRON`, set up a real cron job (e.g. `*/5 * * * *` to hit `https://yoursite.com/wp-cron.php?doing_wp_cron` or run `wp cron event run --due-now` via WP-CLI every few minutes). Ask the host (e.g. Aruba) how to add a cron job and what the URL/command should be.
2. **Days per batch**: In **Seotune Search Insights → Settings → Sync & Import**, set **Days per batch** to **3–5** (or even 1 for very slow hosts). Smaller batches reduce memory and execution time per run.
3. **Rows per DB batch**: In the same section, set **Rows per DB batch** to **500** (or 100 if you still see timeouts or DB errors). Lower values reduce load per request.
4. **PHP limits**: Ask the hosting provider to raise **memory_limit** to at least 256 MB and **max_execution_time** to at least 120 seconds for PHP (or for the cron/CLI context, if they differentiate).

If the import still fails or gets stuck, use **Import diagnostics** in Settings (and **Copy log for support**) to see whether the cause is cron not running, timeouts, memory, or API quota; then adjust the above or contact the host with the requested limits.

== Installation ==

**Video tutorial (installation & setup)**  
https://www.youtube.com/watch?v=QF8Wkk7Sg1I

1. Upload the `seotune-search-insights` folder to `/wp-content/plugins/`.
2. Activate Seotune Search Insights from the Plugins menu.
3. Go to Seotune Search Insights → Settings: enter your Google OAuth Client ID and Secret, then Connect to Google.

**Bundled documentation (HTML)** *(in the full source tree / developer checkout; omitted from the production `npm run release` zip to keep the download smaller)*

* Full guide (installation, OAuth, sync, troubleshooting, privacy): open `documentation/index.html` in a browser, or print to PDF from the browser.
* Maintainers: section “Plugin readme & listing compliance” in `documentation/index.html`; copy-ready notes in `documentation/listing-description-notes.txt` (third-party services, no overpromising, trademarks, privacy note for installers).
* Third-party licenses (Composer, JS bundle): `documentation/third-party-licenses.txt`.
* Admin UI source/build and WordPress.org expectations: `documentation/source-and-build.txt`.
* Network endpoints & privacy (Google): `documentation/network-and-privacy.txt`.
* Security, REST permissions, enqueue (guidelines 8 & 13): `documentation/security-rest-and-assets.txt`.
* Front-end vs admin UX (guidelines 10 & 11): `documentation/admin-ux-and-frontend.txt`.
* Trialware / complete plugin (guidelines 5 & 16): `documentation/trialware-and-complete-plugin.txt`.
* Trademarks & naming (guideline 17): `documentation/trademarks-and-naming.txt`.
* Registro audit WordPress.org (gap, priorità): `documentation/wordpress-org-audit-register.txt`.
* Contributors WordPress.org (slug readme): `documentation/CONTRIBUTORS-wordpress-org.txt`.

== Screenshots ==

1. Dashboard overview with KPIs, charts, top queries and pages, and recent alerts.
2. Keywords report: sortable, filterable table with Search Console metrics and CSV export.
3. Settings: Google OAuth (Client ID / Secret), connection status, and Sync & Import controls.
4. Opportunities: high-impression / low-CTR and positions 8–20 “quick win” reports.
5. Internal Links: opportunities from your WordPress content and Search Console signals, with filters.

== Development ==

**Backend (Composer)**

* From the plugin root: `composer install`.
* Keep the `vendor/` directory when deploying (plugin requires it for the Google API client).
* Autoload: `composer.json` uses a **classmap** for `includes/` (no PSR-4 path mismatch warnings).
* `monolog/monolog` is required by `google/apiclient`; it stays in `composer.json` as `^2.9` to pin Monolog 2.x and remain compatible with PHP 8.0 (Monolog 3 needs PHP 8.1+).

**Frontend (React)**

* From `admin/react-app`: `npm install` then `npm run build`.
* Build outputs a **single** `admin/assets/js/admin-app.js` (IIFE bundle for classic `wp_enqueue_script`, no `import.meta`) plus `admin/assets/js/admin-app.css` (extracted CSS). Deploy both files; without the built JS, a placeholder script is loaded.
* **WordPress.org / source access:** The default release zip **includes** `admin/react-app/` (Vite/React sources, `package-lock.json`; `node_modules` excluded — run `npm ci` inside `admin/react-app` to rebuild). Compiled `admin-app.js` + `admin-app.css` are also present. Optional: add a **public git mirror** URL below for convenience. Details: `documentation/source-and-build.txt`.
* **Public source code repository:** *(Optional — add GitHub/GitLab URL if you publish a mirror; not required for review because sources ship in the plugin package.)*

**Release zip(s) (from plugin root, after `composer` / `npm` as needed)**

* **Version bump & SVN:** see `scripts/README-release.txt` (Stable tag, version constant in `seotune-search-insights.php` aligned with the plugin header, changelog, Subversion tag folder).
* `npm run release` — creates a zip in `dist/` (includes `admin/react-app` sources; excludes `node_modules` and `documentation/`).
* `npm run release:src` — creates only the `*-with-sources.zip` variant with the **same contents** (alias for workflows that expect the filename).
* `npm run release:all` — writes both filenames; the archives are identical (duplicate name for compatibility).

**Translations (i18n)**

* Text domain: `seotune-search-insights`. PHP uses `load_plugin_textdomain` with `languages/`.
* Admin UI strings use `@wordpress/i18n` (`__()`, `sprintf`, `_n`) in JSX; `wp_set_script_translations()` loads Jed JSON for the built script.
* Regenerate templates (from plugin root, WP-CLI):  
  `wp i18n make-pot . languages/seotune-search-insights.pot --slug=seotune-search-insights --domain=seotune-search-insights --exclude=vendor,admin/react-app/node_modules,dist,admin/assets,documentation,scripts`  
  Update `languages/seotune-search-insights-en_US.po` with `wp i18n update-po languages/seotune-search-insights.pot languages/seotune-search-insights-en_US.po`.  
  Build JS JSON (maps all React sources to the single bundle):  
  `wp i18n make-json languages/seotune-search-insights-en_US.po --use-map=languages/wp-i18n-map.json --domain=seotune-search-insights --extensions=jsx,js`  
  Commit `languages/seotune-search-insights.pot`, `languages/seotune-search-insights-en_US.po`, `languages/wp-i18n-map.json`, and `languages/seotune-search-insights-*-*.json` with the plugin.

== Changelog ==

= 1.0.1 =
* Fix: ship SeoTune brand images (menu icon + header logo) inside the WordPress.org download so they display correctly in the sidebar, header, and About tab.

= 1.0.0 =
* Readme and translations: **Seotune Search Insights** branding only in user-facing text; database table prefix described generically (no marketing confusion with internal table names); developer notes reference the main plugin file version constant instead of naming it in the readme.
* **OpenAI / AI insights integration removed** from the base plugin (REST routes, PHP `Insights` class, Settings tab, feature flag, docs, and privacy readme section). The distributed build targets Google Search Console only.
* Readme: **Tags** reviewed for directory SEO — final set: `seo`, `google search console`, `analytics`, `keywords`, `queries` (replaced generic `insights` with GSC-aligned `queries`).
* Readme: **Tested up to** set to **6.9**.
* Readme: **Frequently Asked Questions** section (OAuth, data storage, cron/sync, uninstall, visitor privacy).
* Versioning, readme header, and LICENSE file aligned for distribution (plugin version 1.0.0 matches Stable tag).
* Admin app package.json version aligned with plugin release.
* Added `documentation/index.html`: user-facing manual (requirements, Google OAuth, GSC connection, sync/import, features, troubleshooting, uninstall, privacy & third-party services).
* Internationalization: Jed JSON for the admin bundle; React uses `@wordpress/i18n`; PHP REST/OAuth/sync error strings wrapped with `__()`; script translations loaded via `wp_set_script_translations`.
* Documentation: readme/listing compliance section in `documentation/index.html` and `documentation/listing-description-notes.txt` for listing transparency (Google API, OAuth, trademarks, privacy).
* Release: default `npm run release` includes `admin/react-app` in the zip (GPL source access); excludes `node_modules` and `documentation/`; root `composer.json` and `composer.lock` are included for Composer transparency.
* Composer autoload switched to classmap for `includes/` (clean `composer dump-autoload`); Monolog kept at `^2.9` as required by Google client + PHP 8.0 compatibility.
* Admin UI: React admin mounted with static imports (single Vite/Rollup IIFE bundle, `base: './'`); CSS extracted to `admin-app.css` for WordPress enqueue compatibility.

= 0.2.0 =
* Admin UI: new header with section name only and hamburger menu containing all sections (including Settings).
* Removed duplicate section titles from all report pages (Dashboard, Keywords, Pages, etc.).
* Header: property selector (domain name with icon and chevron) and last sync timestamp on the same row.
* Header: global date range dropdown (Last 7 days, Last 28 days, Last 90 days, Custom) on the same row; all reports use the same range; removed per-page date filters.
* Settings: added Save Settings button in the Google Search Console tab.
* Readme: new "Hosting requirements (for smooth import)" section (PHP limits, cron, tips for restrictive hosting e.g. Aruba).
* Header title styling: font-size 23px, font-weight 400.

= 0.1.0 =
* Initial release.
* Google Search Console OAuth; sync queries and pages; dashboard with KPIs and charts.
* Reports: Keywords, Pages, Opportunities (high-imp low-CTR, position 8–20), Cannibalization.
* Alerts (position/CTR/traffic drop, impressions spike); cron after sync.
* CSV export for all reports.
* Settings: GSC credentials, connect/disconnect, manual sync.
