=== Advally Advertising ===
Contributors: advally
Tags: ads, advertising, adligature, monetization, prebid
Requires at least: 6.3
Tested up to: 6.4
Requires PHP: 7.4
Stable tag: 2.6.3
License: Proprietary

Purpose-built WordPress ad integration from Advally. Loads rules.js, targets ad experience per user type, manages ads.txt, and protects against optimization-plugin breakage.

== Description ==

The Advally WordPress plugin is the counterpart to the XenForo 2 plugin used on Audiokarma, Audizine, and other forum properties. It provides a full-parity integration of the Adligature ad stack for WordPress sites:

* Emits the correct `rules.js` and `rules.css` from `cdn.adligature.com/{alias}/prod/` with the contract script IDs (`AdvallyRules`, `AdvallyStyles`).
* Wires `advally.config()` and `advally.setTargeting('user', …)` / `setTargeting('experience', …)` so Adligature rules can target by user type.
* Supports three user tiers — Guest, Member, Premium — each mapped to one of four ad experiences: Ad-Free, Light, Normal, Heavy ("nascar").
* Optional per-role audience matrix with most-permissive-wins resolution for users in multiple roles.
* Per-experience behavior matrix (top / bottom / side adhesion, interstitial, frequency caps, z-index) — full parity with the XenForo `advally_adunits_matrix`.
* Page-level targeting: `wp-page`, `wp-type`, `wp-category`, `wp-tag`, `wp-author`, `wp-taxonomy`.
* SHA-256-hashed email as first-party data, gmail-dot-normalized, with a per-user opt-out checkbox on the WP profile screen.
* Rescans for AJAX-loaded content (FacetWP, WordPress post-load, jQuery `ajaxComplete`).
* Manages `ads.txt` with four modes — write to docroot, 302 redirect to the CDN, WP-rewrite proxy fallback, or off.
* Optimization-plugin compatibility layer: hooks WP Rocket, Autoptimize, LiteSpeed Cache, Breeze, and W3 Total Cache filter APIs so ad scripts are never deferred, lazy-loaded, or minified. Never edits stored plugin options.
* Malvertising protection (XenForo v2.4.2 parity): iframe sandbox enforcement, meta-refresh blocker, detection beacon to `reporting.advally.com`.
* Under Attack Mode: one click — from the admin bar or the Compat tab — sandboxes ad iframes for 72 hours to shut down a forced-redirect attack, then auto-reverts. Enforcement is on by default; the mode only ever raises protection above your baseline.
* Detects pre-existing theme-based Advally integration and suppresses its own script emission to prevent double-loading.
* Auto-updater backed by GitHub releases — updates show up in the standard WP admin Plugins screen.
* WP-CLI command suite for automated ops (`wp advally health`, `probe`, `sync-adstxt`, `validate-alias`, `log`, `update-check`).
* Structured rotating log under `wp-content/uploads/advally/advally.log`.
* Dev mode renders visible dashed-border placeholders for layout verification without revenue impact.

== Placement ==

Four ways to place ads on a page:

1. **Shortcode** — `[advally_ad slot="HeaderLeaderboard"]`
2. **Widget** — "Advally Ad" in Appearance → Widgets
3. **Gutenberg block** — "Advally Ad Slot" from the block inserter
4. **Automatic content injection** — enable in Settings → Advally Advertising → Placement; plugin inserts an ad every N top-level blocks on singular posts

Premium format placeholders (one per page each): `[advally_video]`, `[advally_recirculation]`, `[advally_quiz]`.

Guest conversion prompt (only renders for logged-out visitors): `[advally_guest_prompt context="first_ad"]` or `[advally_guest_prompt context="adhesion"]`.

To exclude a specific post from all ads, set the post's custom field `advally_ad_free` to `1`.

== Installation ==

1. Upload the plugin folder to `/wp-content/plugins/`.
2. Activate through the Plugins screen.
3. Go to **Settings → Advally Advertising**.
4. Enter your Site Alias (usually the bare domain, e.g. `example.com`) or click "Detect alias from advally.com".
5. Check **Enable Ads**.
6. Review experience mapping on the Experience tab and select premium roles if you have a paywall.
7. (Optional) Place ads via shortcode, widget, block, or enable automatic content injection on the Placement tab.

Verify with `wp advally health` — all rows should be green.

For a step-by-step ops runbook see `DEPLOYMENT_GUIDE.md` in the repo.

== Frequently Asked Questions ==

= How do I verify the plugin is working? =

Run `wp advally health`. Or view source on the front-end and confirm:

* `<link rel="preconnect" href="https://cdn.adligature.com" crossorigin>` in `<head>`
* `<script id="AdvallyRules" src="https://cdn.adligature.com/{alias}/prod/rules.js">`
* `<link id="AdvallyStyles" href="https://cdn.adligature.com/{alias}/prod/rules.css">`
* An inline `<script>` containing `advally.config({...})` and `advally.setTargeting(...)` calls

Visit `https://yoursite.com/ads.txt` and confirm Adligature content is served.

= I activated the plugin but no scripts appear in the page source. =

Most likely: the alias isn't set or the master Enable switch is off. The plugin silently refuses to enable ads without a validated alias — check Settings → Advally Advertising → General. If both look right, run `wp advally health` and read the output.

Less common: the auto-detector found existing Advally code in your active theme and stepped aside to avoid double-loading. The output of `wp advally health` will show `pre_existing_integration: detected (script emission suppressed)`. Either remove the theme code or override via Settings → Compatibility → Compatibility mode → Force on.

= My optimization plugin is deferring rules.js and ads aren't loading. =

Settings → Compatibility → confirm Optimization Guard is ON. Then purge the optimization plugin's own cache (WP Rocket: "Clear and Preload Cache"; Autoptimize: "Empty Cache"; LiteSpeed: "Purge All"). Already-cached HTML can keep the wrong attributes on the script tag until cache is cleared.

= Can users opt out of email-hash targeting? =

Yes. Every user has a checkbox at the bottom of their WordPress profile screen ("Ad targeting opt-out"). When checked, the plugin emits an empty string for that user's `emailSHA256` field — no hashed email is ever sent.

= Does the plugin work on multisite? =

Yes. Settings are per-site. The update-check transient is network-cached so subsites share the GitHub rate-limit budget. `ads.txt` mode needs careful selection on multisite — see the multisite section of `DEPLOYMENT_GUIDE.md`.

= How do I report a bug or ask for a feature? =

GitHub Issues: https://github.com/Advally/advally-wordpress-plugin/issues. Include the output of `wp advally health` and your active theme + optimization plugin name and version.

== Changelog ==

= 2.0.0 =
Complete rewrite. The November 2025 single-file V1 ("advally-advertising.php") shipped a settings page but emitted broken ad markup; this release is a full parity-with-XenForo integration plus optimization-plugin hardening, a malvertising guard, a per-role audience matrix, a Gutenberg block, a WP-CLI suite, structured logging, and a GitHub-backed auto-updater. See CHANGELOG.md in the repository for the full list of additions and the bugs removed from V1.

= 1.0.0 =
November 2025 skeleton. Superseded by 2.0.0 — do not run in production.
