Advally WordPress Plugin

What it is

The Advally Advertising plugin is the official Adligature ad integration for
WordPress sites. It is the WordPress counterpart to the XenForo 2 plugin that
runs on Audiokarma, Audizine, and the other forum properties — same ad stack,
same targeting model, same revenue protections, expressed in WordPress terms.

In one sentence: it loads the correct rules.js / rules.css for your site from
the Adligature CDN, targets the ad experience to each visitor (Guest / Member /
Premium), manages your ads.txt, and stops optimization/caching plugins from
silently breaking ad revenue.

What it does (feature overview)

• Loads the Adligature ad stack. Emits rules.js and rules.css from
  cdn.adligature.com/{alias}/prod/ using the contract script IDs AdvallyRules
  and AdvallyStyles, plus the advally.config() / advally.setTargeting(...)
  wiring rules need.
• Targets ads by visitor type. Three user tiers — Guest, Member, Premium —
  each mapped to one of four ad experiences: Ad-Free, Light, Normal, Heavy
  (“nascar”). An optional per-role audience matrix resolves users who hold
  multiple roles using most-permissive-wins.
• 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.
• First-party data, with consent. SHA-256-hashed email (gmail-dot-normalized)
  as first-party data, with a per-user opt-out checkbox on the WordPress
  profile screen. Opt-out emits an empty hash — nothing is sent.
• ads.txt management in four modes: write to docroot, 302 redirect to the
  CDN, WP-rewrite proxy fallback, or off.
• Optimization-plugin protection. Hooks the filter APIs of WP Rocket,
  Autoptimize, LiteSpeed Cache, Breeze, and W3 Total Cache so ad scripts are never
  deferred, lazy-loaded, or minified. It never edits stored plugin options —
  it only adds runtime exclusions.
• Malvertising protection (XenForo v2.4.2 parity): iframe sandbox enforcement,
  meta-refresh blocker, and a detection beacon to reporting.advally.com.
• No double-loading. Detects pre-existing theme-based Advally integration and
  suppresses its own script emission.
• Auto-updater backed by GitHub releases — updates appear in the standard WP
  Plugins screen.
• WP-CLI suite for ops: wp advally health | probe | sync-adstxt | validate-alias | log | update-check.
• Structured logging at wp-content/uploads/advally/advally.log.
• Dev mode renders dashed-border placeholders for layout verification with no
  revenue impact.

Installing & enabling (publisher quick start)

1. Upload the plugin folder to /wp-content/plugins/ and Activate it.
2. Go to Settings → Advally Ads.
3. Enter your Site Alias (usually the bare domain, e.g. example.com) or click
   Detect alias from advally.com.
4. Check Enable Ads.
5. On the Experience tab, review the experience mapping and select premium
   role(s) if the site has a paywall.
6. (Optional) Place ads via shortcode, widget, block, or enable automatic content
   injection on the Placement tab.
7. Verify with wp advally health — all rows should be green.

The plugin silently refuses to enable ads without a validated alias — a safety
default. If nothing emits, the alias or the master Enable switch is the first
thing to check.

A full step-by-step engineer runbook lives in docs/CLIENT_INSTALL.md (clean
installs) and docs/BEACHGRIT_INSTALL.md (sites with existing theme-hardcoded
integration). Ops runbook: DEPLOYMENT_GUIDE.md.

Placing ads

Four ways to place an ad unit:

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

Premium-format placeholders (one per page each): [advally_video],
[advally_recirculation], [advally_quiz]. Logged-out guest conversion prompt:
[advally_guest_prompt context="first_ad"] or context="adhesion".

To exclude a single post from all ads, set its custom field advally_ad_free to 1.

Injection on posts with embeds (2.6.5 and later)

Block counting skips a post that holds a script, svg or picture, so that post gets no in-content ad. To count paragraphs instead, set this option with WP-CLI. It has no settings field.

wp option update advally_content_inject_mode paragraphs

The ad goes after every Nth paragraph, using the same N and minimum as the Placement tab. A paragraph that holds an embed or comes just before one is not used, and the ad moves to the next clear paragraph. Paragraphs inside quotes, lists, figures and tables are not counted, and no ad goes after the last paragraph. To go back, set the option to blocks, the default.

Theme positions (2.6.4 and later)

A custom theme can name each place an ad may go, and the plugin decides which slot prints there. Moving a slot then takes a settings change instead of a theme deploy.

1. In the theme, call the hook where the ad may go: do_action( 'advally_position', 'single_sidebar' );
2. Map the position name to a slot with WP-CLI. It has no settings field.

wp option update advally_positions '{"single_sidebar":"HeaderLeaderboard"}' --format=json

A position with no mapping prints nothing. The usual checks still apply, so an ad-free post or experience stays ad-free. To add a CSS class, map the name to an object: {"single_sidebar":{"slot":"HeaderLeaderboard","class":"my-class"}}.

Verifying it works

Run wp advally health (every row green), or view page source 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(...)
• https://yoursite.com/ads.txt serves Adligature content

Common issues

• Activated but no scripts in source — alias not set or master Enable off (the
  plugin refuses to emit without a validated alias). Less commonly, the detector
  found existing Advally code in the active theme and stepped aside; wp advally
health shows pre_existing_integration: detected. Remove the theme code or force
  via Settings → Compatibility → Compatibility mode → Force on.
• Optimization plugin is deferring rules.js — confirm Settings → Compatibility
  → Optimization Guard is ON, then purge the optimization plugin’s own cache
  (already-cached HTML keeps the wrong script-tag attributes until purged).
• Email-hash targeting opt-out — each user has an “Ad targeting opt-out”
  checkbox at the bottom of their WordPress profile.
• Multisite — settings are per-site; the update-check transient is
  network-cached so subsites share the GitHub rate-limit budget. Choose the
  ads.txt mode carefully (see DEPLOYMENT_GUIDE.md).

How it relates to the rest of Advally

• Same ad stack as the XenForo plugin — the WordPress plugin exists so non-forum
  (WordPress) publishers get the identical Adligature integration. BeachGrit is the
  flagship WordPress property migrating onto it.
• Rules come from the CDN, not the plugin — the plugin only emits the loader +
  targeting; the actual ad behavior is governed by the site’s rules.js published
  from Adligature. Changing ad behavior is a rules/wrapper change, not a plugin
  change.
• ads.txt is centrally CDN-managed — the redirect/proxy modes point at the
  Adligature-managed ads.txt, the same source of truth used everywhere else.

Reporting bugs

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