=== Foreground CAPI Health Check ===
Contributors: foregroundagency, khmerlee
Tags: meta pixel, conversions api, capi, audit, attribution
Requires at least: 6.0
Tested up to: 7.0
Requires PHP: 7.4
Stable tag: 2.1.8
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Audit your site's Meta Pixel + Conversions API setup. 12 checks against the 2026 iOS 17/18 stack. Free, no signup, no phone-home.

== Description ==

The browser Meta Pixel is broken for ~30% of your visitors after iOS 17 and iOS 18 changed how Apple devices handle tracking. Most marketing managers running WordPress have no easy way to tell if their Pixel + CAPI setup actually works.

This plugin runs a 12-check audit against your site's front page and gives you a score from 0 to 100, plus plain-English explanations of what each failure means and how to fix it.

**Free forever.** No signup, no upsell harassment, no phone-home. Every audit runs locally on your server.

**Need it fixed for you?** If your score is below 85 and you'd rather not learn server-side CAPI from scratch, we offer a flat-fee Pixel Fix service: **$497, delivered in 4 business days.** One link to that service appears inside the plugin admin only when your score is below 85. The audit works completely whether or not you use the paid option.

**What it checks**

* Meta Pixel installed and parseable
* Domain verification (iOS 14+ critical)
* Pixel events firing (PageView, Purchase, Lead, etc.)
* Advanced Matching (the single biggest EMQ lever)
* CAPI deduplication via eventID
* Consent Mode v2 / cookie banner presence
* Google Tag Manager container
* fbclid first-party capture (iOS 17 / iOS 18 Link Tracking Protection)
* external_id in Advanced Matching (iOS 18 Hide My Email answer)
* Server-side CAPI plugin presence
* Apple Privacy Manifest readiness (if you link to an iOS app)
* HTTPS enforced

**What it does NOT do**

* No phone-home. Every audit runs on your server against your URL. Nothing is sent to Foreground.
* No email capture. No signup wall.
* No subscription, no paid tier, no upsell harassment.
* No automatic re-runs or cron jobs.

**Made by Foreground Digital**

Foreground is a Dubai-based digital agency. We build Meta Ads campaigns and the server-side infrastructure that catches them — Pixel + CAPI, CRM integrations, WordPress + headless. Founded 2024.

== Installation ==

1. Upload the plugin folder to `/wp-content/plugins/` or install via the Plugins screen.
2. Activate the plugin.
3. Go to **Tools → Meta CAPI Health** and click "Run audit on this site."

== Frequently Asked Questions ==

= Does this plugin send any data to Foreground or anyone else? =

No. Every audit runs locally on your server against your own front page. The plugin does not contact any external service. The only outbound link is the optional "Fix it for me" CTA that opens foreground.agency in a new tab — and only you, the WordPress admin, ever sees it.

= Does this work with PixelYourSite, Meta for WordPress, etc.? =

Yes. The plugin audits whatever Pixel is currently rendering on your front page, regardless of which plugin installed it. It will also detect known CAPI plugins (PixelYourSite Pro, Meta for WordPress, CAPI Suite) when checking for server-side CAPI.

= My score is 60. Now what? =

Read each failed check. The easy fixes (Pixel install, Advanced Matching toggle, HTTPS, domain verification) you can do yourself in Meta Business Manager + WP Settings. The hard fixes (server-side CAPI endpoint, eventID dedupe, fbclid capture) require PHP development. The plugin gives you both paths on every failure row.

= How often should I re-run the audit? =

After any of these: new theme, new plugin that touches tracking, Meta Events Manager warnings, big WordPress core update, or every 90 days as a routine check.

= Why is there a CTA to a paid service? =

Because someone has to pay for the audit logic to exist. The plugin is free forever and the audit always runs in full. The CTA only appears when your score is below 85 and links to a flat-fee fix service — no dark patterns, no email capture inside the plugin.

= Will this plugin slow down my site? =

No. The audit only runs when you click the button in wp-admin. It does not run on every page load, does not enqueue scripts on the front end, and does not register any cron jobs.

= Can I delete the plugin without leaving data behind? =

Yes. On uninstall, the plugin removes all of its options from `wp_options`. No tables are created. No files are left behind.

== Screenshots ==

1. Main dashboard: branded header, circular score gauge with delta vs last run, status panel, and 5 stat cards (Passed / Warnings / Failed / Est. attribution loss / Total checks).
2. Categorized audit findings: 12 checks grouped into Foundation, Match Quality, Reliability, Compliance, and Optional. Each failing row expands to show DIY fix steps with a difficulty badge (Easy / Medium / Hard).
3. Score history: 480px sparkline graph + run-by-run table showing score deltas across iterative fixes. Keeps the last 20 runs.

== Changelog ==

= 2.1.8 =
* WordPress.org review compliance pass #2.
* Removed reference to a Foreground terms URL that did not resolve. The plugin's readme now lists only the Foreground privacy policy URL (which exists and is current). No code change.

= 2.1.7 =
* WordPress.org review compliance pass.
* Added == External services == section to the readme disclosing the single self-audit HTTP request and clarifying that all third-party mentions (Meta endpoints, third-party WP plugins, foreground.agency) are documentation references — the plugin does not connect to any of them.
* Wrapped the two internal SVG renderers (score gauge, score history sparkline) in `wp_kses()` with an explicit SVG element/attribute allowlist instead of `phpcs:ignore` suppression. No visible UI change.

= 2.1.6 =
* Detect Pixel installations behind cookie-consent gates (Cookiebot, CookieYes, Iubenda, etc.). The Pixel-installed and events-firing checks now also recognize: noscript fallback img tags (facebook.com/tr?id=X), and known plugin signatures (PixelYourSite, Meta for WordPress, CAPI Suite). Previously the audit returned a false "no Pixel found" for any consent-deferred install — common on EU/UK sites.
* Pixel ID extraction now reads from noscript fallback when inline init is unavailable.

= 2.1.5 =
* Cache-bust on audit fetch. Appends ?fcapi_audit={timestamp} to the home URL so Cloudflare / Varnish / WP-Rocket / other reverse-proxies serve fresh origin HTML rather than a stale cached page. Prevents the "no Pixel found" false-negative when a user installs a Pixel but forgets to purge their CDN cache.

= 2.1.4 =
* Plugin Check compliance pass for WordPress.org submission.
* Added /* translators: */ comments to every sprintf/__() with placeholders (10 spots across audit-runner and admin-page).
* Fixed unordered placeholders in the "events detected" string (now uses %1$d %2$s positional).
* Swapped parse_url() for wp_parse_url() per WordPress coding standards.
* Removed Domain Path: /languages header (no translation folder shipped yet).
* Suppressed false-positive escape-output flag on internal SVG renderers (render_score_gauge, render_sparkline) with phpcs:ignore + audit comments.
* Trimmed plugin tags from 9 to 5 (WP.org max) and short description under 150 chars.

= 2.1.2 =
* Brand: replaced the CSS-rendered "F" placeholder in the dashboard header and About card with the official Foreground icon PNG. Visual identity now matches the rest of foreground.agency exactly.

= 2.1.1 =
* Security hardening pass before WP.org submission.
* Replaced double-escape pattern (inner esc_html before sprintf into translation) with sanitize_text_field() for remote-derived strings — prevents render-time over-escaping.
* SVG attributes in score gauge wrapped in esc_attr() (defense-in-depth, values were already integers).
* SSRF surface locked: audit-runner now ALWAYS fetches home_url(), ignores any passed target_url. Prevents future contributors accidentally creating a generic URL-fetcher.

= 2.1.0 =
* Added "About this plugin" sidebar card to fill the empty space in the score hero. Single contextual CTA: "Get the Pixel Fix" when score < 85, "Visit foreground.agency" when score 85+.
* 3-column hero layout (score gauge / status panel / about card). Responsive: collapses to 2-col then 1-col on smaller screens.

= 2.0.0 =
* Complete UI redesign with branded dashboard header, circular score gauge, and 5 stat cards (Pass / Warn / Fail / Est. loss / Total).
* Checks are now grouped into 5 categories: Foundation, Match Quality, Reliability, Compliance, Optional.
* Removed all per-row "Fix it for me" buttons. Each failing check now expands inline to show DIY fix steps with difficulty rating (Easy / Medium / Hard).
* Removed the prominent CTA banner. Foreground branding moved to a single discrete footer line.
* Improved empty state with helpful onboarding text.
* Sparkline graph in score history now uses the brand orange and has an area fill gradient.

= 1.0.3 =
* UX: Score history panel now auto-expands at 2+ runs (was 3+). Iteration feedback is visible immediately on the second audit.

= 1.0.2 =
* NEW: Score history with delta indicator. Each re-run shows +/- vs the previous score plus a 20-run sparkline graph so you can visually track improvements as you fix issues.
* NEW: "Best ever" badge so you can see your historical peak.
* Detailed run history table with timestamps, pass/warn/fail breakdown, and estimated attribution loss per run.

= 1.0.1 =
* FIX: Audit now surfaces fetch errors (SSL, firewall, loopback issues) instead of silently failing.
* Added SSL fallback chain — retries with sslverify=false then falls back to HTTP if needed.
* Increased timeout 15s → 20s, redirect hops 3 → 5.

= 1.0.0 =
* Initial release.
* 12 Tier-1 checks covering iOS 14/17/18, Advanced Matching, eventID dedupe, fbclid capture, Consent Mode v2, server-side CAPI detection.
* Tools → Meta CAPI Health admin page.
* Zero external calls. No phone-home. No email capture.

== External services ==

This plugin makes ONE outbound HTTP request, and it goes only to your own WordPress site. No data is ever sent to Foreground, Meta, or any other third party.

**1. Your own site's home URL (self-audit request)**

* What it is: A standard HTTP GET request to your site's own front page (`home_url()`), used to fetch and parse the public HTML so the plugin can detect Pixel installs, fired events, Advanced Matching, eventID dedupe, etc.
* What data is sent: Only the HTTP GET itself. The User-Agent header is set to `ForegroundCAPIHealth/1.0 (+https://foreground.agency)` to identify the audit traffic in your access logs. No personal data, no admin identifiers, no cookies, no user IDs.
* When: Only when a WordPress administrator manually clicks "Run audit on this site" inside Tools → Meta CAPI Health. There is no cron, no front-end trigger, and no automatic re-run.
* Where: The request loops back to your own server (the same WordPress installation that has the plugin installed). It does not go to any external service.
* Fallback chain: If HTTPS fails due to a local certificate issue, the request is retried once with `sslverify=false`, and as a last resort over `http://` to the same hostname. This is purely a local recovery path; no external host is ever contacted.

**2. References to third-party services in the plugin's UI (documentation only — no external call)**

The plugin's "How to fix" instructions name several third-party services so administrators know where to go in their existing accounts. The plugin does **not** connect to any of these. They are mentioned for instructional purposes only:

* **Meta / Facebook** — `connect.facebook.net`, `graph.facebook.com`, Meta Events Manager, Meta Business Manager. Used as documentation references when explaining how to install a Meta Pixel, set up domain verification, or wire Conversions API. The plugin does not call any Meta endpoint. Meta's terms: https://www.facebook.com/legal/terms — Meta's privacy policy: https://www.facebook.com/privacy/policy
* **Third-party WordPress plugins** mentioned by name in the fix steps (PixelYourSite, Meta for WordPress, CAPI Suite, Cookiebot, CookieYes, Complianz, Termly, Iubenda, OneTrust, GTM for WordPress). These are recommendations only. The plugin does not call, depend on, or communicate with any of them.
* **Foreground.agency** — appears in the audit traffic User-Agent string for self-identification, and as the destination of an optional "Get the Pixel Fix" link shown in the admin UI only when an administrator clicks it. The plugin itself does not phone home to foreground.agency. Foreground privacy policy: https://foreground.agency/privacy

The "Fix it for me" CTA shown when an administrator's score is below 85 is a plain HTML link that opens `https://foreground.agency/pixel-fix/?ref=wp-plugin` in a new tab. Nothing is transmitted unless the administrator chooses to click it.

== Upgrade Notice ==

= 1.0.0 =
First public release.
