Offline documentation note: images are bundled with this package and work offline. Installation videos are streamed online because including them would add 300MB+ to the download.

## Server requirements

- PHP: 8.0+ (recommended 8.1/8.2)
- Extensions: PDO MySQL, cURL, JSON, mbstring, OpenSSL, and zip (ZipArchive) if you use the in-app updater
- Database: MySQL / MariaDB
- HTTPS: recommended for production
- Writable paths: `storage/` (see below)

## Installation

Choose your hosting panel and follow the step-by-step guide.

## Installation on Plesk (step-by-step)

Follow the video and then the checklist below (Plesk-specific steps plus common SeoScope steps).

1. Domain / subdomain + document root = `public` (Plesk)

   Video: Plesk installation walkthrough (streamed from seoscope.cloud).

   Your browser cannot play this video inline. Open 00_plesk.mp4 in a new tab and stream it (not bundled to keep the package size reasonable).

   - Create/select the domain or subdomain in Plesk.
   - Open Hosting Settings (or Apache & nginx Settings) and set Document root to the SeoScope `public` folder (the one that contains `index.php`).

2. Upload the ZIP + extract (Plesk)
   - Open Files for the subscription and upload the SeoScope ZIP into the site folder.
   - Use Extract so the application folders (including `public/`) exist on disk.
3. Create the database (Plesk)
   - Databases → Add Database → create a MySQL/MariaDB database.
4. Create the DB user + privileges (Plesk)
   - Create (or select) a database user and grant privileges to the database.
   - Note host (often `localhost`), port (often `3306`), database, username, password.

5. Run the installer + first login
   - Open your site in the browser and start the installer (or visit `/install/index.php`).
   - Enter DB host/port/name/user/password, then create the admin account.
   - After install, activate the license at `/license` using your Envato purchase code.
   Security after install: once setup is complete and you can log in, delete the uploaded ZIP archive and remove the `install/` directory from the server.
6. Create OAuth JSON (Google Cloud)
   - Create a new project (or use an existing one) in Google Cloud Console.
   - Enable Google Search Console API.
   - Configure the OAuth consent screen and publish the app if required.
   - Create credentials: OAuth client ID → Web application.
   - In SeoScope, copy the exact Redirect URI shown in `Settings → Google` and paste it into Authorized redirect URIs.

   - Download the client JSON.
7. Upload JSON + connect Google (SeoScope)
   - Open `Settings → Google` in SeoScope.
   - Upload the OAuth JSON (or paste Client ID/Secret) and click Connect Google.

8. Create the cron (Plesk)
   - In SeoScope open `Settings → Automation` and copy the Cron URL shown there.
   - In Plesk: Tools & Settings (or Domains → subscription) → Scheduled Tasks → Add Task.
   - Choose Fetch a URL (HTTP GET) and paste the Cron URL.
   - Schedule every 5–10 minutes (for example `*/5 * * * *`). Use only one scheduler for that URL (HTTP 409 means a run is already in progress).

9. Fetch properties + enable what you need (SeoScope)
   - Go to Websites (or `Projects`) and click Fetch properties.
   - Enable the properties you want to analyze and let the cron run the first sync.

## Installation on cPanel (step-by-step)

Follow the video and then the checklist below (cPanel-specific steps plus common SeoScope steps).

1. Domain / subdomain + document root = `public` (cPanel)

   Video: cPanel installation walkthrough (streamed from seoscope.cloud).

   Your browser cannot play this video inline. Open 00_cpanel.mp4 in a new tab and stream it (not bundled to keep the package size reasonable).

   - Create the domain/subdomain in cPanel (labels vary: Domains, Subdomains, Create A New Domain).
   - Set the domain’s document root to the SeoScope `public` folder (must contain `index.php`).
2. Upload the ZIP + extract (cPanel)
   - Open File Manager and upload the ZIP to the target site folder.
   - Extract it so `public/`, `app/`, `config/`, `install/` exist on disk.
3. Create the database (cPanel)
   - Use MySQL® Databases (or MySQL Database Wizard) to create a database.
4. Create the DB user + privileges (cPanel)
   - Create a DB user and Add User To Database with ALL PRIVILEGES.
   - Note host (often `localhost`), port (often `3306`), database, username, password.
5. Run the installer + first login
   - Open your site and run the installer (or visit `/install/index.php`).
   - Enter DB host/port/name/user/password, then create the admin account.
   - After install, activate the license at `/license` using your Envato purchase code.
   Security after install: once setup is complete and you can log in, delete the uploaded ZIP archive and remove the `install/` directory from the server.
6. Create OAuth JSON (Google Cloud)
   - Create a new project (or use an existing one) in Google Cloud Console.
   - Enable Google Search Console API.
   - Configure the OAuth consent screen and publish the app if required.
   - Create credentials: OAuth client ID → Web application.
   - In SeoScope, copy the exact Redirect URI shown in `Settings → Google` and paste it into Authorized redirect URIs.

   - Download the client JSON.
7. Upload JSON + connect Google (SeoScope)
   - Open `Settings → Google`, upload OAuth JSON (or paste Client ID/Secret), then click Connect Google.

8. Create the cron (cPanel)
   - In SeoScope open `Settings → Automation` and copy the `curl` command shown there.
   - In cPanel: Cron Jobs → Add New Cron Job.
   - Schedule every 5 minutes (e.g. `*/5 * * * *`) and paste the command in the Command field.

   - If quoting fails, use single quotes around the URL inside `curl`.
9. Fetch properties + enable what you need (SeoScope)
   - Go to Websites (or `Projects`) and click Fetch properties.
   - Enable the properties you want to analyze and let the cron run the first sync.

## App features (overview)

SeoScope turns Google Search Console performance data into structured SEO reports: headline KPIs, sortable tables, drill-downs between queries and landing pages, and rule-based opportunity lists. You work inside a single property (Search Console site or URL-prefix) at a time, with shared filters so KPIs and detail tables stay consistent as you move between screens.

Global filters (property, date preset, device, country, and compare where supported) apply across reports. Optional SEO AI Assistant cards (see below) summarise the current view of each screen when you click Generate insight.

- Dashboard — KPIs, performance chart, tracked keyword/page widgets, optional SEO AI card with deterministic SEO health badge.
- Quick Win — IQQI, CTR Opportunity, Low CTR Pages, Topical Gaps (each tab may show an SEO AI card).
- Keywords — Query report with All/Tracked, search, compare, drill-down to pages.
- Pages — Landing URL report with All/Tracked and query drill-down.
- Cannibalization — Competing URLs per query.
- Long tail — Multi-word queries.
- Question queries — Question-style queries (configurable terms).
- Decay — Queries losing clicks, impressions, or position vs. the prior period.

## SEO AI Assistant (optional)

The SEO AI Assistant is an optional module. It appears as a card on the Dashboard and on the report screens listed above. It does not run when you open a page: nothing is sent to an AI provider until you click Generate insight or Regenerate. If AI is disabled or not configured, the card explains how to open `Settings → AI`.

### Turning it on

- Open `Settings → AI`, turn on Enable AI insights (saved immediately when you flip the switch).
- Choose OpenAI or Anthropic, paste your own API key (BYOK), pick a model, and click Save AI settings for keys, models, and optional monthly token caps.
- Keys are stored encrypted on your server in your database—SeoScope does not operate a shared proxy that holds your secret.
- Your server needs the PHP cURL extension to call the provider you selected.

### Privacy & what is sent

Each run sends a compact JSON payload from your server to the provider you chose: Search Console metrics for the active report view (top table rows and report-specific context such as filters, compare periods, or decay thresholds), plus minimal workspace context (property, dates, filters). The exact shape depends on the screen; read the short note under What is sent to your AI provider on the AI settings tab. API keys stay on your server; nothing is sent while AI insights are off.

Traffic goes from your installation directly to the provider’s HTTPS API—an additional outbound connection alongside Google and any license/update endpoints (see Security & outbound connections).

### SEO health badge (Dashboard only)

On the Dashboard, the SEO health badge (Good / Warning / Critical) is calculated only on the server from aggregate KPIs and a compact digest of the daily series. The model produces the narrative paragraphs; it does not decide the badge. Report screens return narrative insight only (no health badge).

### Limitations & costs

- API billing is between you and the AI provider (OpenAI or Anthropic). SeoScope does not resell tokens. Token usage per provider is shown on `Settings → AI`.
- Results are cached for a configurable window so the same property + filters + report view do not re-call the provider unnecessarily.
- Built-in rate limits reduce accidental bursts; if you hit them, wait and try again.
- The assistant summarises the current filtered view (typically the top rows shown in the table), not your entire Search Console export.

### Quality checklist (CodeCanyon-oriented)

Short bar for reviewers and authors. The full runbook with checkboxes lives in the repository file `documentation/CODECANYON-CHECKLIST.md` (section SEO AI Assistant — CodeCanyon-oriented checklist (M5)); it is not bundled in the retail ZIP because the whole `documentation/` tree is author-only.

- No secret leaks: API keys stay server-side (encrypted); browser JSON must never echo keys or raw provider payloads.
- Plain language: user-facing errors suggest what to do next (configure AI, retry, reload) without stack traces.
- Fallbacks: no paid AI call on first dashboard load; every empty / misconfigured / offline state has a defined UI path.

### Manual smoke test (authors)

Full runbook: `documentation/CODECANYON-CHECKLIST.md` → SEO AI Assistant — Manual smoke test. Spot-check at least Dashboard, one Quick Win tab, and one other report (e.g. Keywords or Decay) after changes to AI payloads or routes.

- Settings → AI — Toggle Enable AI insights off/on without clicking Save AI settings; confirm the switch state persists after reload.
- Generate twice (same screen, same filters) → second response `cached: true` when cache TTL applies.
- Regenerate → `cached: false` and fresh narrative when the provider succeeds.
- Change filters that affect the payload (date range, compare, report thresholds) and confirm cache keys diverge (no stale insight from another view).

## Interface language & translations

The product ships with English as the only built-in interface language. In `Settings → Interface` you can add more languages and select the active one (see below).

## Updates

The full Updates section is maintained online. If you are reading this page offline, you can always open the live docs at https://seoscope.cloud/documentation/.

## Troubleshooting

For expanded troubleshooting, please refer to the live docs at https://seoscope.cloud/documentation/.

## Security & outbound connections

Security notes and outbound connection details are maintained online at https://seoscope.cloud/documentation/.

## Support

For support, please use the official CodeCanyon support channel associated with your purchase.