WPCalibrate Ads Authorization Toolkit

A production-ready WordPress plugin for managing, validating, diagnosing, publishing, and safely repairing ads.txt and app-ads.txt implementations according to the IAB Tech Lab Ads.txt v1.1 specification.

Table of Contents

• About
  • Why WPCalibrate Ads Authorization Toolkit?
  • IAB Tech Lab v1.1 Compliance
• Features
• Documentation & User Guide
  • System Requirements
  • Installation
  • Automatic Updates via GitHub
  • Admin Tabs & Workflow
    • 1. Overview Tab
    • 2. Ads.txt Tab
    • 3. App-ads.txt Tab
    • 4. Diagnostics Tab
    • 5. Revisions Tab
    • 6. Tools Tab
    • 7. Settings Tab
    • 8. Support Tab
  • Ads.txt Line Structure Reference
  • Troubleshooting & FAQs
  • Developer Hooks & Filters
• Changelog
• License
• Credits & Author

About

Authorized Digital Sellers (ads.txt) and Authorized Mobile Application Sellers (app-ads.txt) are critical mechanisms introduced by the IAB Tech Lab to combat domain spoofing and arbitrage in programmatic advertising.

However, many publishers suffer massive ad revenue losses and crawling penalties due to:

• Subtle syntax errors (commas instead of semicolons, protocols in domain names, lowercase tags).
• Physical server files left over from legacy setups that silently override WordPress rewrite rules.
• Caching mismatches between staging databases, reverse proxies, and CDN edge servers.
• Unintentional duplication or contradictory relationship definitions (DIRECT vs. RESELLER).

WPCalibrate Ads Authorization Toolkit goes far beyond a basic textarea editor. It provides a full-featured diagnostics suite, live endpoint verification with SSRF protection, visual line-by-line diff comparisons, automated duplicate normalization, and safe revision snapshots with instant rollback.

Why WPCalibrate Ads Authorization Toolkit?

• Real-Time Validation: Instant, in-memory parsing against IAB Tech Lab rules with actionable line numbers and clear human explanations.
• Physical File Collision Safeguards: Detects physical ads.txt files on your server without touching or deleting your filesystem automatically.
• SSRF-Protected Live Verification: Confirms your public /ads.txt and /app-ads.txt endpoints return 200 OK and Content-Type: text/plain with identical content to your WordPress database.
• Zero Lock-In & Zero Telemetry: Your publisher data stays on your server. No external phone-home requests, trackers, or hidden analytics.

IAB Tech Lab v1.1 Compliance

Full native support for:

• Standard 3-field and 4-field records (domain, account_id, relationship, certification_authority_id).
• Directives: OWNERDOMAIN, MANAGERDOMAIN, SUBDOMAIN, CONTACT, and INVENTORYPARTNERDOMAIN.
• Forward-compatible unknown directive preservation.
• Full case-insensitive normalization with comment (#) retention.

Features

• Split-View Code Editor: Line numbers automatically stay synchronized with scrolling; includes an accessible fallback editor for screen readers and legacy browsers.
• Live Record Counters: Instant tally of DIRECT sellers, RESELLER records, Directives, Duplicate entries, and Syntax Errors.
• Built-in Demo Data Generator: 1-click IAB v1.1 compliant demo dataset for instant staging, onboarding, and sandbox testing.
• Live Endpoint Verification: Safely tests the public URL using WordPress HTTP API with strict SSRF controls (local loopback validation, blocks unauthorized ports and redirect spoofing).
• Visual Line Comparison (Diff): Compare what is saved in your WordPress database against what is actually served over HTTP on the public web.
• Safe Guided Repairs: One-click repairs for flushing WordPress rewrite rules, clearing verification caches, and deduplicating record sets.
• Revision History & Rollbacks: Every save is versioned with timestamps and author details. Reverting any revision automatically captures a pre-restore backup first.
• Multisite Aware: Distinguishes between subdomain/domain-mapped setups and path-based multisite installations where only the root domain can serve /ads.txt.
• White-Label / Native UI: Modern, high-contrast WordPress admin styling, responsive marketplace cards, unified branding, and SVG iconography.

Documentation & User Guide

System Requirements

• WordPress: 6.6 or higher
• PHP: 8.2 or higher
• Permalinks: Pretty permalinks enabled (e.g. /%postname%/) for dynamic virtual endpoint serving.

Installation

Option 1: WordPress Dashboard (Recommended)

1. Download wpcalibrate-ads-authorization-toolkit-1.0.0.zip.
2. In your WordPress admin, go to Plugins -> Add New -> Upload Plugin.
3. Choose the ZIP file and click Install Now.
4. Click Activate Plugin.

Option 2: Manual Installation via FTP

1. Unzip wpcalibrate-ads-authorization-toolkit-1.0.0.zip.
2. Upload the wpcalibrate-ads-authorization-toolkit folder to your /wp-content/plugins/ directory.
3. Activate the plugin in Plugins -> Installed Plugins.

Automatic Updates via GitHub

This repository contains the required headers (GitHub Plugin URI: https://github.com/zeeshanraza-official/wpcalibrate-ads-authorization-toolkit and Primary Branch: main).

You can easily manage automatic and one-click updates directly inside WordPress using standard GitHub update tools:

• Git Updater or GitHub Updater
• Plugin Update Checker

When a new release tag or commit is pushed to this GitHub repository, WordPress will detect the update and allow updating with a single click from Plugins -> Installed Plugins.

Admin Tabs & Workflow

Once activated, access the toolkit at WPCalibrate -> Ads Authorization in the WordPress admin menu.

1. Overview Tab

• Quick status indicators: public endpoint reachability, physical file status, and published record count.
• Step-by-step interactive guide covering:
  • Purpose: Why authorized seller declarations protect programmatic CPMs.
  • Syntax: How 3-field and 4-field records work.
  • Workflow: Edit -> Validate -> Publish -> Verify.
• One-click demo data insertion button.

2. Ads.txt Tab

• Full editing workspace for website publishers.
• Syntax validator highlighting warnings and errors line-by-line.
• Action buttons:
  • Save & Publish: Updates the live endpoint and creates a snapshot revision.
  • Validate Syntax: Checks records without saving.
  • Load Demo Data: Populates standard Google AdSense, Google Ad Manager, AppNexus/Xandr, and Rubicon/Magnite records.

3. App-ads.txt Tab

• Designed for mobile application and connected TV (CTV) publishers.
• Toggle enabled/disabled state (disabled by default so search engines do not crawl blank endpoints).
• Dedicated editor with independent revision tracking and validation.

4. Diagnostics Tab

• Endpoint Test: Live HTTP test verifying response status (200 OK) and header (Content-Type: text/plain).
• Physical File Check: Inspects the root filesystem for blocking ads.txt or app-ads.txt files.
• Environment Checks: Confirms pretty permalinks, SSL status, and multisite compatibility.
• Diff Tool: Highlights discrepancies between stored settings and live output.

5. Revisions Tab

• Browse previous versions of your authorized seller lists.
• View author, change notes, timestamp, and line count.
• Restore Revision: Reverts to any previous state with zero data loss (automatically snapshots current state prior to restore).

6. Tools Tab

• Normalize Records: Eliminates duplicate lines, standardizes uppercase relationships (DIRECT, RESELLER), and removes excessive whitespace.
• Flush Rewrite Rules: Re-registers WordPress virtual rewrite endpoints if you experience 404 errors.
• Physical File Importer: Imports an existing server file into the database safely.

7. Settings Tab

• Configure caching TTL for diagnostics checks.
• Set verification timeout limits.
• Manage license keys and optional feature toggles.

8. Support Tab

• Documentation links and FAQs.
• System environment info for troubleshooting.
• WPCalibrate Ecosystem showcase of companion plugins.

Ads.txt Line Structure Reference

Each data line in ads.txt follows this comma-separated structure:

<Domain of Exchange>, <Publisher Account ID>, <Relationship>, <Certification Authority ID>

Fields:

1. Domain: Canonical domain of the exchange or SSP (e.g. google.com). Do not include https:// or path slashes.
2. Publisher Account ID: Your seller or publisher ID assigned by that platform (e.g. pub-0000000000000000).
3. Relationship: Must be either DIRECT (publisher controls the account) or RESELLER (third party manages the inventory).
4. Certification ID (Optional): Security certification authority ID (e.g. f08c47fec0942fa0 for Google).

Example:

# Google AdSense / Ad Manager
google.com, pub-1234567890123456, DIRECT, f08c47fec0942fa0

# Authorized Reseller
rubiconproject.com, 10020, RESELLER, 0bfd66d529a55803

# Directives
OWNERDOMAIN=example.com
MANAGERDOMAIN=monetizationpartner.com

Troubleshooting & FAQs

Q: My public /ads.txt displays a 404 error.
Fix: Ensure pretty permalinks are enabled under Settings -> Permalinks. Then go to WPCalibrate -> Ads Authorization -> Tools and click Flush Rewrite Rules.

Q: Changes saved in WordPress do not appear on /ads.txt.
Fix: Check the Diagnostics tab. If a real physical ads.txt exists on your hosting server root, web servers (Nginx/Apache) will serve that file directly, bypassing WordPress. Use the Tools -> Import feature and then remove the physical file. Also clear your CDN or page cache.

Q: Can I use this on a WordPress Multisite network?
Fix: Yes. On subdomain networks (site.example.com), each site serves its own /ads.txt. On subdirectory networks (example.com/site/), IAB specifications mandate that crawlers only check the root domain (example.com/ads.txt), which the main network site controls.

Developer Hooks & Filters

Extend or customize toolkit behaviors using standard WordPress hooks:

// Filter published ads.txt content before it is served
add_filter( 'wpcalibrate_aat_ads_txt_content', function( string $content ): string {
    return $content . "\n# Appended via filter";
} );

// Customize rewrite endpoint name
add_filter( 'wpcalibrate_aat_endpoint_slug', function( string $slug ): string {
    return 'ads.txt';
} );

Changelog

1.0.0

• Initial Production Release.
• Full compliance with IAB Tech Lab Ads.txt v1.1 specification.
• Dedicated Ads.txt and App-ads.txt split editors with line synchronization.
• Real-time syntax validator covering DIRECT, RESELLER, and all standard directives (OWNERDOMAIN, MANAGERDOMAIN, SUBDOMAIN, CONTACT, INVENTORYPARTNERDOMAIN).
• Physical file collision detector with safe one-click import.
• Live public endpoint verification with SSRF safeguards.
• Visual line-by-line diff comparison between stored and live output.
• Revisions engine with automatic pre-restore backup snapshots.
• Safe guided repair tools (rewrite flush, cache reset, duplicate normalizer).
• Interactive "How to Use, Purpose & Method" visual guide on Overview tab.
• Integrated Demo Data generator with 1-click loading.
• Modern white-label UI with high-contrast SVG branding.
• Dual-slug submenu routing ensuring zero tab permission errors.
• GitHub dashboard update compatibility (GitHub Plugin URI).

License

This project is licensed under the GNU General Public License v2.0 or later (GPL-2.0-or-later).

Credits & Author

Developed by WPCalibrate.
Maintained by zeeshanraza-official.