claude-plugin-wordpress-manager 2.4.0 → 2.9.0

package/skills/wp-alerting/scripts/alerting_inspect.mjs

@@ -0,0 +1,150 @@
+/**
+ * alerting_inspect.mjs — Detect alerting configuration readiness.
+ *
+ * Checks WP_SITES_CONFIG for Slack and SendGrid credentials.
+ * Scans for monitoring plugins and alerting infrastructure.
+ *
+ * Usage:
+ *   node alerting_inspect.mjs [--cwd=/path/to/project]
+ *
+ * Exit codes:
+ *   0 — alerting configuration found
+ *   1 — no alerting configuration found
+ */
+
+import { readFileSync, existsSync, readdirSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { argv, stdout, exit } from 'node:process';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function readFileSafe(filePath) {
+  try { return readFileSync(filePath, 'utf-8'); } catch { return null; }
+}
+
+function existsSafe(filePath) {
+  try { return existsSync(filePath); } catch { return false; }
+}
+
+function globDir(dirPath) {
+  try { return readdirSync(dirPath); } catch { return []; }
+}
+
+// ---------------------------------------------------------------------------
+// Detectors
+// ---------------------------------------------------------------------------
+
+function detectSlackConfig() {
+  const slack = { configured: false, indicators: [] };
+  const raw = process.env.WP_SITES_CONFIG;
+  if (!raw) return slack;
+
+  let sites;
+  try { sites = JSON.parse(raw); } catch { return slack; }
+  if (!Array.isArray(sites)) return slack;
+
+  for (const site of sites) {
+    const label = site.id || site.url || 'unknown';
+    if (site.slack_webhook_url) {
+      slack.configured = true;
+      slack.indicators.push(`slack_webhook_url configured for ${label}`);
+    }
+    if (site.slack_bot_token) {
+      slack.configured = true;
+      slack.indicators.push(`slack_bot_token configured for ${label}`);
+    }
+    if (site.slack_channel) {
+      slack.indicators.push(`slack_channel: ${site.slack_channel} for ${label}`);
+    }
+  }
+  return slack;
+}
+
+function detectSendGridConfig() {
+  const sg = { configured: false, indicators: [] };
+  const raw = process.env.WP_SITES_CONFIG;
+  if (!raw) return sg;
+
+  let sites;
+  try { sites = JSON.parse(raw); } catch { return sg; }
+  if (!Array.isArray(sites)) return sg;
+
+  for (const site of sites) {
+    const label = site.id || site.url || 'unknown';
+    if (site.sg_api_key) {
+      sg.configured = true;
+      sg.indicators.push(`sg_api_key configured for ${label}`);
+    }
+    if (site.sg_from_email) {
+      sg.indicators.push(`sg_from_email: ${site.sg_from_email} for ${label}`);
+    }
+    if (site.sg_from_name) {
+      sg.indicators.push(`sg_from_name: ${site.sg_from_name} for ${label}`);
+    }
+  }
+  return sg;
+}
+
+function detectMonitoringSetup(cwd) {
+  const monitoring = { plugins_found: false, cron_available: false, indicators: [] };
+
+  // Check for monitoring-related plugins
+  const pluginsDir = join(cwd, 'wp-content', 'plugins');
+  const plugins = globDir(pluginsDir);
+
+  const monitoringPlugins = [
+    'query-monitor',
+    'new-relic-reporting-for-wordpress',
+    'jetpack',
+    'developer',
+    'wp-crontrol',
+    'debug-bar',
+    'health-check',
+  ];
+
+  for (const plugin of monitoringPlugins) {
+    if (plugins.includes(plugin)) {
+      monitoring.plugins_found = true;
+      monitoring.indicators.push(`plugin: ${plugin}`);
+    }
+  }
+
+  // Check for wp-cron.php availability
+  const cronPath = join(cwd, 'wp-cron.php');
+  if (existsSafe(cronPath)) {
+    monitoring.cron_available = true;
+    monitoring.indicators.push('wp-cron.php found');
+  }
+
+  return monitoring;
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+function main() {
+  const cwdArg = argv.find(a => a.startsWith('--cwd='));
+  const cwd = cwdArg ? resolve(cwdArg.split('=')[1]) : process.cwd();
+
+  const slack = detectSlackConfig();
+  const sendgrid = detectSendGridConfig();
+  const monitoring = detectMonitoringSetup(cwd);
+
+  const anyConfigured = slack.configured || sendgrid.configured || monitoring.plugins_found || monitoring.cron_available;
+
+  const report = {
+    alerting_configured: anyConfigured,
+    slack,
+    sendgrid,
+    monitoring,
+    cwd,
+  };
+
+  stdout.write(JSON.stringify(report, null, 2) + '\n');
+  exit(anyConfigured ? 0 : 1);
+}
+
+main();

package/skills/wp-analytics/SKILL.md

@@ -0,0 +1,158 @@
+---
+name: wp-analytics
+description: This skill should be used when the user asks about "analytics",
+  "GA4", "Google Analytics", "Plausible", "Core Web Vitals", "CWV",
+  "PageSpeed", "page speed", "LCP", "CLS", "INP", "TTFB", "FCP",
+  "traffic report", "traffic analysis", "site performance metrics",
+  "web vitals", "real user metrics", or mentions monitoring
+  WordPress site analytics and performance data.
+version: 1.0.0
+tags: [analytics, ga4, plausible, cwv, pagespeed, core-web-vitals]
+---
+
+# WordPress Analytics Skill
+
+## Overview
+
+Unified analytics covering 3 platforms (GA4, Plausible, Core Web Vitals) with 14 MCP tools. These tools enable traffic analysis, audience insights, performance monitoring, and cross-platform reporting directly from the WordPress management environment. By combining data from multiple analytics sources, you can build comprehensive performance dashboards, identify optimization opportunities, and track real user experience metrics.
+
+## When to Use
+
+- User wants to check GA4 traffic data (sessions, pageviews, conversions)
+- User needs Plausible analytics (privacy-friendly, lightweight metrics)
+- User asks about Core Web Vitals scores (LCP, CLS, INP, FCP, TTFB)
+- User wants PageSpeed Insights analysis for specific URLs
+- User needs a combined traffic report across analytics platforms
+- User asks about performance trends, audience segments, or traffic sources
+- User wants to compare metrics between GA4 and Plausible
+- User needs to monitor real user experience metrics from CrUX data
+
+## Decision Tree
+
+1. **What analytics platform?**
+   - "GA4" / "Google Analytics" / "sessions" / "conversions" → GA4 workflows (Section 1)
+   - "Plausible" / "privacy analytics" / "simple analytics" → Plausible workflows (Section 2)
+   - "Core Web Vitals" / "LCP" / "CLS" / "INP" / "PageSpeed" → CWV analysis (Section 3)
+   - "traffic report" / "dashboard" / "compare" → Cross-platform reporting (Sections 4-6)
+
+2. **Run detection first:**
+   ```bash
+   node skills/wp-analytics/scripts/analytics_inspect.mjs [--cwd=/path/to/project]
+   ```
+   This identifies configured analytics credentials and installed plugins.
+
+## Service Overview
+
+| Service | Tools | Auth Type | Use Case |
+|---------|-------|-----------|----------|
+| Google Analytics 4 | 6 tools (`ga4_*`) | Service Account JSON | Traffic, audience, conversions |
+| Plausible Analytics | 4 tools (`pl_*`) | API Key | Privacy-friendly traffic metrics |
+| Core Web Vitals | 4 tools (`cwv_*`) | Google API Key | Performance and user experience |
+
+## Sections
+
+### Section 1: GA4 Setup & Configuration
+See `references/ga4-integration.md`
+- Service Account creation in Google Cloud Console
+- GA4 Data API v1beta enablement
+- WP_SITES_CONFIG setup with ga4_property_id and ga4_service_account_key
+- Property ID format and account structure
+- Common dimensions and metrics reference
+- Quota limits and sampling considerations
+
+### Section 2: Plausible Setup & Configuration
+See `references/plausible-setup.md`
+- API key generation (cloud or self-hosted)
+- WP_SITES_CONFIG setup with plausible_api_key and plausible_base_url
+- Available metrics and properties
+- Period and date range formats
+- Filtering and breakdown options
+
+### Section 3: Core Web Vitals Analysis
+See `references/cwv-monitoring.md`
+- Metric definitions (LCP, FCP, CLS, INP, TTFB)
+- Good / needs-improvement / poor thresholds
+- PageSpeed Insights API usage
+- CrUX API for real user data
+- WP_SITES_CONFIG setup with google_api_key
+
+### Section 4: Traffic Report Generation
+See `references/analytics-dashboards.md`
+- Weekly and monthly report templates
+- Key KPIs: sessions, pageviews, bounce rate, conversion rate
+- Date range selection and comparison periods
+- Combining data from multiple sources
+
+### Section 5: Performance Dashboard
+See `references/analytics-dashboards.md`
+- Building composite dashboards from GA4 + Plausible + CWV
+- Trend analysis and alerting thresholds
+- Top pages by traffic and performance score
+- Audience segmentation patterns
+
+### Section 6: Cross-Platform Comparison
+See `references/traffic-attribution.md`
+- Comparing GA4 and Plausible traffic numbers
+- UTM parameter tracking and source/medium mapping
+- Combining analytics with WooCommerce conversion data
+- Discrepancy analysis between platforms
+
+## Reference Files
+
+| File | Content |
+|------|---------|
+| `references/ga4-integration.md` | GA4 Data API setup, service account, dimensions/metrics, quotas |
+| `references/plausible-setup.md` | Plausible API key, self-hosted vs cloud, metrics, periods |
+| `references/cwv-monitoring.md` | CWV metric definitions, thresholds, PageSpeed/CrUX APIs |
+| `references/analytics-dashboards.md` | Dashboard patterns, report templates, KPIs, combined data |
+| `references/traffic-attribution.md` | UTM params, source/medium, GA4 + WooCommerce conversions |
+
+## MCP Tools
+
+| Tool | Description |
+|------|-------------|
+| `ga4_report` | Run a GA4 Data API report with custom dimensions and metrics |
+| `ga4_realtime` | Get GA4 real-time active users and events |
+| `ga4_top_pages` | Get top pages by pageviews, sessions, or engagement |
+| `ga4_traffic_sources` | Get traffic source breakdown (source, medium, campaign) |
+| `ga4_conversions` | Get conversion event data and goal completions |
+| `ga4_audience` | Get audience demographics and technology breakdown |
+| `pl_aggregate` | Get aggregate Plausible metrics for a time period |
+| `pl_timeseries` | Get Plausible time-series data with configurable intervals |
+| `pl_breakdown` | Get Plausible breakdown by property (page, source, country) |
+| `pl_realtime` | Get Plausible real-time visitor count |
+| `cwv_pagespeed` | Run PageSpeed Insights analysis on a URL |
+| `cwv_crux_url` | Get CrUX real user metrics for a specific URL |
+| `cwv_crux_origin` | Get CrUX real user metrics for an entire origin |
+| `cwv_history` | Get CrUX historical Core Web Vitals data |
+
+## Recommended Agent
+
+Use the **`wp-monitoring-agent`** for automated analytics reporting, performance alerting, and scheduled dashboard generation that combines data across all three platforms.
+
+## Related Skills
+
+- **`wp-search-console`** — combine search analytics with traffic data for full SEO visibility
+- **`wp-content-optimization`** — use analytics data to prioritize content optimization efforts
+- **`wp-content-attribution`** — track content sources and attribute traffic to specific campaigns
+- **`wp-monitoring`** — monitor site uptime and health alongside analytics performance
+
+## Cross-references
+
+- GA4 setup pairs with `wp-search-console` for combined Google data workflows
+- CWV monitoring feeds into `wp-performance` for technical optimization
+- Traffic attribution connects to `wp-social-email` for campaign tracking
+- Dashboard patterns support `wp-monitoring` alerting workflows
+
+## Troubleshooting
+
+| Issue | Cause | Resolution |
+|-------|-------|------------|
+| GA4 returns empty data | Service account lacks Viewer role | Grant "Viewer" role on the GA4 property |
+| GA4 quota exceeded | Too many API requests | Reduce request frequency; use date ranges instead of daily calls |
+| Plausible 401 error | Invalid or expired API key | Regenerate API key in Plausible dashboard |
+| Plausible returns no data | Site domain mismatch | Ensure site_id matches the domain registered in Plausible |
+| CWV "API key not valid" | Google API key missing or restricted | Enable PageSpeed Insights API in Google Cloud Console |
+| CWV no CrUX data | Low-traffic page | CrUX requires sufficient real user traffic; use lab data instead |
+| Detection script exit 1 | No analytics config found | Add ga4_property_id, plausible_api_key, or google_api_key to WP_SITES_CONFIG |
+| Plugin detected but no API data | Plugin handles tracking only | Plugins embed tracking code; API access requires separate credentials |

package/skills/wp-analytics/references/analytics-dashboards.md

@@ -0,0 +1,83 @@
+# Analytics Dashboard Patterns
+
+## Weekly Report Template
+
+A weekly report should cover the most recent 7-day period compared to the previous 7 days.
+
+### Key Metrics Section
+| KPI | This Week | Last Week | Change |
+|-----|-----------|-----------|--------|
+| Sessions (GA4) | — | — | +/-% |
+| Unique Visitors (Plausible) | — | — | +/-% |
+| Pageviews | — | — | +/-% |
+| Bounce Rate | — | — | +/-pp |
+| Avg. Session Duration | — | — | +/-s |
+| Conversions | — | — | +/-% |
+| LCP (p75) | — | — | +/-ms |
+| CLS (p75) | — | — | +/- |
+| INP (p75) | — | — | +/-ms |
+
+### Top Pages Section
+List the top 10 pages by pageviews with:
+- Page path and title
+- Pageviews (GA4) and Visitors (Plausible)
+- CWV scores if available
+- Week-over-week change
+
+### Traffic Sources Section
+Breakdown by source/medium with session counts and conversion rates.
+
+## Monthly Report Template
+
+Extends the weekly report with:
+- Month-over-month and year-over-year comparisons
+- Audience trends (new vs returning, device split, geo distribution)
+- Content performance (top 20 pages, worst performers, new content impact)
+- CWV trend charts (4-week rolling averages)
+- Conversion funnel analysis
+
+## Combining GA4 + Plausible Data
+
+### Why Use Both
+- **GA4** provides deep behavioral data, conversion tracking, and audience segmentation
+- **Plausible** provides privacy-compliant counts that may be more accurate (no adblocker filtering)
+- Comparing both reveals tracking discrepancies and adblocker impact
+
+### Alignment Strategy
+1. Use the **same date range** for both platforms
+2. Map GA4 `sessions` to Plausible `visits` (closest equivalent)
+3. Map GA4 `activeUsers` to Plausible `visitors`
+4. Note: numbers will differ — Plausible typically shows fewer visits due to no cookie tracking
+5. Calculate the **tracking gap**: `(GA4 sessions - Plausible visits) / GA4 sessions * 100`
+
+### Recommended Dashboard Sections
+1. **Overview** — side-by-side GA4 and Plausible totals
+2. **Traffic Sources** — GA4 source/medium enriched with Plausible referrer data
+3. **Content Performance** — page-level metrics from both platforms
+4. **Core Web Vitals** — PageSpeed scores and CrUX field data
+5. **Conversions** — GA4 conversion events and goal completions
+6. **Trends** — time-series charts with 7-day and 30-day windows
+
+## Key KPIs Reference
+
+| KPI | Source | Formula / Notes |
+|-----|--------|-----------------|
+| Sessions | GA4 | Total sessions in period |
+| Unique Visitors | Plausible | Deduplicated visitor count |
+| Pageviews | Both | Total page loads |
+| Bounce Rate | GA4 | `1 - engagementRate` |
+| Pages per Visit | Plausible | `pageviews / visits` |
+| Avg. Duration | GA4 | `averageSessionDuration` in seconds |
+| Conversion Rate | GA4 | `conversions / sessions * 100` |
+| LCP (p75) | CWV | 75th percentile Largest Contentful Paint |
+| CLS (p75) | CWV | 75th percentile Cumulative Layout Shift |
+| INP (p75) | CWV | 75th percentile Interaction to Next Paint |
+| Performance Score | PageSpeed | Lighthouse 0-100 score |
+
+## Report Format Guidelines
+
+- Use **Markdown tables** for structured data
+- Include **percentage changes** with directional indicators
+- Flag metrics that cross CWV thresholds (good/needs-improvement/poor)
+- Provide **actionable recommendations** for declining metrics
+- Keep reports under 200 lines for readability

package/skills/wp-analytics/references/cwv-monitoring.md

@@ -0,0 +1,101 @@
+# Core Web Vitals Monitoring
+
+## Metric Definitions
+
+### LCP — Largest Contentful Paint
+Measures **loading performance**. Time until the largest visible content element is rendered.
+- Applies to: images, videos, block-level text elements
+- Target: measures perceived load speed
+
+### FCP — First Contentful Paint
+Measures **initial render**. Time until the first text or image is painted on screen.
+- Applies to: any visible DOM content
+- Target: measures time to first visual feedback
+
+### CLS — Cumulative Layout Shift
+Measures **visual stability**. Sum of unexpected layout shift scores during the page lifecycle.
+- Applies to: visible elements that move without user interaction
+- Target: measures how much content jumps around
+
+### INP — Interaction to Next Paint
+Measures **responsiveness**. Latency of user interactions (clicks, taps, key presses) throughout the page lifecycle.
+- Replaced FID (First Input Delay) as a Core Web Vital in March 2024
+- Target: measures overall page responsiveness
+
+### TTFB — Time to First Byte
+Measures **server responsiveness**. Time from the request start until the first byte of the response is received.
+- Includes DNS, connection, TLS, and server processing time
+- Target: measures backend and network performance
+
+## Thresholds
+
+| Metric | Good | Needs Improvement | Poor |
+|--------|------|-------------------|------|
+| LCP | <= 2.5s | 2.5s - 4.0s | > 4.0s |
+| FCP | <= 1.8s | 1.8s - 3.0s | > 3.0s |
+| CLS | <= 0.1 | 0.1 - 0.25 | > 0.25 |
+| INP | <= 200ms | 200ms - 500ms | > 500ms |
+| TTFB | <= 800ms | 800ms - 1800ms | > 1800ms |
+
+The 75th percentile (p75) is used for assessment — meaning 75% of page loads must meet the threshold.
+
+## PageSpeed Insights API
+
+### Setup
+1. Enable **PageSpeed Insights API** in Google Cloud Console
+2. Create or use an existing API key
+3. Add `google_api_key` to WP_SITES_CONFIG
+
+### Request Format
+```
+GET https://www.googleapis.com/pagespeedonline/v5/runPagespeed
+  ?url=https://example.com
+  &key=YOUR_API_KEY
+  &strategy=mobile        # or "desktop"
+  &category=performance   # also: accessibility, best-practices, seo
+```
+
+### Response Fields
+- `lighthouseResult.categories.performance.score` — 0-100 score
+- `lighthouseResult.audits['largest-contentful-paint']` — LCP details
+- `lighthouseResult.audits['cumulative-layout-shift']` — CLS details
+- `lighthouseResult.audits['interaction-to-next-paint']` — INP details
+- `loadingExperience.metrics` — CrUX field data (if available)
+
+### Quota
+- 25,000 queries per day (free tier)
+- 400 queries per 100 seconds
+
+## CrUX API (Chrome UX Report)
+
+### Overview
+CrUX provides **real user metrics** collected from Chrome users who opted into usage statistics. Unlike PageSpeed Insights (lab data), CrUX reflects actual user experience.
+
+### Request Format
+```
+POST https://chromeuxreport.googleapis.com/v1/records:queryRecord
+  ?key=YOUR_API_KEY
+
+Body:
+{
+  "url": "https://example.com/page",
+  "formFactor": "PHONE",        // optional: PHONE, DESKTOP, TABLET
+  "metrics": ["largest_contentful_paint", "cumulative_layout_shift"]
+}
+```
+
+For origin-level data, use `"origin"` instead of `"url"`.
+
+### Data Availability
+- CrUX data requires **sufficient traffic** — low-traffic pages may have no data
+- Data is aggregated over a 28-day rolling window
+- Updated weekly (typically Monday)
+- Historical data available via BigQuery dataset `chrome-ux-report`
+
+## WordPress-Specific Considerations
+
+- **Caching plugins** (WP Super Cache, W3 Total Cache, LiteSpeed) significantly affect TTFB and LCP
+- **Image optimization** plugins impact LCP for image-heavy pages
+- **Theme and plugin JavaScript** is the primary cause of poor INP scores
+- **Web fonts** can cause CLS if not using `font-display: swap`
+- Test both **logged-in** and **logged-out** states — admin bar affects CLS

package/skills/wp-analytics/references/ga4-integration.md

@@ -0,0 +1,76 @@
+# GA4 Data API v1beta Integration
+
+## Service Account Setup
+
+1. Go to [Google Cloud Console](https://console.cloud.google.com/)
+2. Create or select a project
+3. Enable the **Google Analytics Data API** (v1beta)
+4. Navigate to **IAM & Admin > Service Accounts**
+5. Create a service account with a descriptive name (e.g., `wp-analytics-reader`)
+6. Download the JSON key file
+7. In GA4 Admin, grant the service account email **Viewer** role on the property
+
+## WP_SITES_CONFIG Configuration
+
+```json
+{
+  "id": "my-site",
+  "url": "https://example.com",
+  "ga4_property_id": "properties/123456789",
+  "ga4_service_account_key": "/path/to/service-account-key.json"
+}
+```
+
+- `ga4_property_id` — format is `properties/NUMERIC_ID` (find in GA4 Admin > Property Settings)
+- `ga4_service_account_key` — absolute path to the downloaded JSON key file
+
+## Property ID Format
+
+- GA4 uses numeric property IDs prefixed with `properties/`
+- Example: `properties/350123456`
+- Find it in GA4 Admin > Property Settings > Property ID
+- Do NOT use the Measurement ID (G-XXXXXXX) — that is for the tracking tag only
+
+## Common Dimensions
+
+| Dimension | API Name | Description |
+|-----------|----------|-------------|
+| Date | `date` | Date in YYYYMMDD format |
+| Page path | `pagePath` | URL path of the page |
+| Page title | `pageTitle` | HTML title of the page |
+| Source | `sessionSource` | Traffic source (google, facebook, etc.) |
+| Medium | `sessionMedium` | Traffic medium (organic, cpc, referral) |
+| Campaign | `sessionCampaignName` | UTM campaign name |
+| Country | `country` | User country |
+| Device category | `deviceCategory` | desktop, mobile, tablet |
+| Landing page | `landingPage` | First page of the session |
+
+## Common Metrics
+
+| Metric | API Name | Description |
+|--------|----------|-------------|
+| Sessions | `sessions` | Total sessions |
+| Active users | `activeUsers` | Users with engaged sessions |
+| Pageviews | `screenPageViews` | Total page views |
+| Engagement rate | `engagementRate` | Percentage of engaged sessions |
+| Avg. session duration | `averageSessionDuration` | Mean session length in seconds |
+| Bounce rate | `bounceRate` | Percentage of non-engaged sessions |
+| Conversions | `conversions` | Total conversion events |
+| Event count | `eventCount` | Total events fired |
+
+## Quota Limits
+
+| Quota | Limit | Notes |
+|-------|-------|-------|
+| Requests per day | 25,000 | Per project |
+| Requests per minute | 1,200 | Per project |
+| Concurrent requests | 10 | Per project |
+| Tokens per query | 17,500 | Complexity-based; dimensions and metrics consume tokens |
+| Response rows | 100,000 | Max rows per response; use pagination for larger datasets |
+
+## Sampling and Data Freshness
+
+- GA4 Data API may return **sampled data** for large date ranges or complex queries
+- Check `metadata.dataLossFromOtherRow` in responses for row aggregation
+- Real-time data has a 24–48 hour processing delay for standard reports
+- Use `keepEmptyRows: true` to include zero-value rows in reports

package/skills/wp-analytics/references/plausible-setup.md

@@ -0,0 +1,92 @@
+# Plausible Analytics Setup
+
+## Overview
+
+Plausible is a privacy-friendly, lightweight analytics platform. It does not use cookies, fully complies with GDPR/CCPA, and provides a simple API for data retrieval.
+
+## Cloud vs Self-Hosted
+
+| Aspect | Plausible Cloud | Self-Hosted |
+|--------|----------------|-------------|
+| URL | `https://plausible.io` | Your own domain (e.g., `https://analytics.example.com`) |
+| API base | `https://plausible.io/api` | `https://analytics.example.com/api` |
+| Hosting | Managed | You manage the server |
+| Cost | Subscription-based | Free (server costs apply) |
+| Data ownership | Plausible servers (EU) | Your infrastructure |
+
+## API Key Generation
+
+1. Log into your Plausible dashboard
+2. Go to **Settings > API Keys**
+3. Click **+ New API Key**
+4. Name it (e.g., `wp-analytics-read`) and copy the key
+5. Store the key securely — it is shown only once
+
+## WP_SITES_CONFIG Configuration
+
+```json
+{
+  "id": "my-site",
+  "url": "https://example.com",
+  "plausible_api_key": "plausible-api-key-here",
+  "plausible_base_url": "https://plausible.io"
+}
+```
+
+- `plausible_api_key` — the API key generated above
+- `plausible_base_url` — omit for cloud (defaults to `https://plausible.io`), set for self-hosted
+
+## Available Metrics
+
+| Metric | Description |
+|--------|-------------|
+| `visitors` | Unique visitors |
+| `visits` | Total visits (sessions) |
+| `pageviews` | Total page views |
+| `views_per_visit` | Average pages per visit |
+| `bounce_rate` | Percentage of single-page visits |
+| `visit_duration` | Average visit duration in seconds |
+| `events` | Total custom events |
+
+## Available Properties (Breakdown Dimensions)
+
+| Property | Description |
+|----------|-------------|
+| `event:page` | Page path |
+| `visit:source` | Traffic source |
+| `visit:referrer` | Full referrer URL |
+| `visit:utm_source` | UTM source parameter |
+| `visit:utm_medium` | UTM medium parameter |
+| `visit:utm_campaign` | UTM campaign parameter |
+| `visit:country` | Visitor country (ISO 3166-1 alpha-2) |
+| `visit:device` | Device type (Desktop, Mobile, Tablet) |
+| `visit:browser` | Browser name |
+| `visit:os` | Operating system |
+
+## Period Formats
+
+| Period | Format | Example |
+|--------|--------|---------|
+| Day | `day` | Current day |
+| 7 days | `7d` | Last 7 days |
+| 30 days | `30d` | Last 30 days |
+| Month | `month` | Current month |
+| 6 months | `6mo` | Last 6 months |
+| 12 months | `12mo` | Last 12 months |
+| Custom | `custom` | Requires `date` param: `2024-01-01,2024-01-31` |
+
+## Filtering
+
+Filters use the format `property operator value`:
+- `visit:source==Google` — exact match
+- `event:page==/blog**` — wildcard match
+- `visit:country!=US` — not equal
+- Multiple filters: separate with `;` (AND logic)
+
+Example: `visit:source==Google;visit:country==IT`
+
+## Rate Limits
+
+- **600 requests per hour** per API key
+- **10 requests per second** burst limit
+- Responses include `X-RateLimit-Remaining` header