Zeal Ad Manager Documentation
Welcome to Zeal Ad Manager! Thank you for purchasing our commercial-grade advertising network plugin for WordPress. This comprehensive guide will walk you through the installation, configuration, and management of your ad network.
Zeal Ad Manager transforms your WordPress site into a complete, self-service advertising network. Go beyond simple, fixed-rate ad systems with an intelligent, performance-based dynamic pricing engine that creates a fair and competitive ecosystem for both advertisers and publishers.
Important: Please read this documentation carefully before setting up the plugin. It covers everything from installation to advanced configuration, including the dynamic pricing engine, ad formats, and fraud detection system.
What's Included
- Zeal Ad Manager Plugin — The core WordPress plugin with all features
- Animated Ad Builder — 18+ professional animation templates with live preview
- ZealUp Premium Ad Formats — Anchor, Sticky Bar, and Vignette overlay ads
- GeoIP Database — Bundled MaxMind GeoLite2 Country database for geographic targeting
- AI Integration — Google Gemini-powered keyword generation and ad copy creation
- This Documentation — Complete setup and configuration guide
Key Features at a Glance
- Intelligent dynamic pricing engine with geographic and performance multipliers
- 7 standard ad formats + 3 premium ZealUp overlay formats
- Full-featured Animated Ad Builder with 18+ templates
- Self-service Advertiser and Publisher dashboards
- WooCommerce integration for campaign funding
- Automated fraud detection system
- AI-powered keyword generation and ad copy creation (Google Gemini)
- GeoIP-based country targeting (bundled, no external calls)
- Shadow DOM ad isolation for CSS conflict prevention
- 7 customizable email notification templates
- Publisher site verification system
- Cross-origin ad serving with CORS security
Server Requirements
Before installing Zeal Ad Manager, ensure your server meets the following minimum requirements:
| Requirement | Minimum | Recommended |
|---|---|---|
| WordPress Version | 6.0+ | 6.5+ |
| PHP Version | 7.3+ | 8.0+ |
| MySQL Version | 5.7+ | 8.0+ |
| WooCommerce | 7.0+ (required for payments) | 8.0+ |
| PHP Memory Limit | 128MB | 256MB |
Required PHP Extensions
json— For API communication and data processingcurl— For external API calls (Gemini AI, RapidAPI)mbstring— For multi-byte string handlinggdorimagick— For image processing
Required Plugins
- WooCommerce — Required for advertiser campaign funding via the checkout system
Tip: Most modern WordPress hosting providers meet all of these requirements out of the box. If you're unsure, check the Tools → Site Health page in your WordPress dashboard.
Optional External Services
| Service | Purpose | Required? |
|---|---|---|
| Google Gemini AI | Auto-generate keywords for ads and publisher sites; generate AI ad copy | Optional |
| RapidAPI (App Store API) | Fetch app metadata for the App Install ad format | Optional (only for App Install ads) |
Installation & Setup
Follow these steps carefully to install and configure Zeal Ad Manager on your WordPress site.
1. Upload & Activate the Plugin
- Download the
zeal-ad-manager.zipfile from your purchase - In your WordPress dashboard, go to Plugins → Add New → Upload Plugin
- Click Choose File and select the zip file
- Click Install Now, then click Activate Plugin
Alternative: You can also upload the unzipped zeal-ad-manager folder directly to /wp-content/plugins/ via FTP/SFTP, then activate it from the Plugins page.
2. Auto-Created Pages
Upon activation, the plugin automatically creates three essential pages with pre-configured shortcodes:
| Page | Shortcode | Purpose |
|---|---|---|
| Advertiser Dashboard | [zam_advertiser_dashboard] |
Self-service campaign management for advertisers |
| Publisher Dashboard | [zam_publisher_dashboard] |
Site management and earnings tracking for publishers |
| Register | [zam_register_form] |
Registration form with role selection (Advertiser or Publisher) |
Note: You can find these pages in Pages → All Pages and add them to your navigation menu. The pages are only created on the first activation — re-activating the plugin will not duplicate them.
3. WooCommerce Integration Setup
Zeal Ad Manager uses WooCommerce to process advertiser payments. Follow these steps to set it up:
- Make sure WooCommerce is installed and activated
- Go to Products → Add New and create a new Simple product
- Name it something like "Ad Campaign Credit" or "Advertising Funds"
- Set the price to any value (the plugin will override the price dynamically based on the advertiser's chosen budget)
- Publish the product
- Note the Product ID (visible in the URL when editing:
post=123) - Go to Zeal Ad Manager → Settings → General and enter this Product ID in the Ad Credit Product ID field
- Save your settings
Important: The WooCommerce product must be published and the correct Product ID entered in settings. Without this, advertisers will not be able to fund their campaigns.
Done! Your Zeal Ad Manager is now installed. The next step is to configure the admin settings to customize pricing, ad formats, and email notifications.
Admin Panel Configuration
Access the Zeal Ad Manager admin panel from the WordPress sidebar: Zeal Ad Manager. The admin area includes a dashboard overview, ad/site management, reports, and a comprehensive settings page with four tabs.
Dashboard Overview
The admin dashboard provides an at-a-glance view of your ad network's performance:
- Total Revenue — All-time earnings from ad impressions and clicks
- Total Payouts — Total amount paid out to publishers
- Total Impressions — Cumulative ad impressions across the network
- Total Clicks — Cumulative ad clicks across the network
- Pending Ads — Number of ads awaiting approval
- Pending Sites — Number of publisher sites awaiting verification
- Pending Withdrawals — Publisher withdrawal requests awaiting processing
The dashboard also includes quick links to review queues and access reports.
Admin Reports
Navigate to Zeal Ad Manager → Reports for detailed analytics:
- Date-range filtering for custom reporting periods
- Top-performing ads by impressions, clicks, and revenue
- Top-performing publisher sites
- Geographic performance breakdown by country
- Revenue and payout trends
General Settings
Navigate to Zeal Ad Manager → Settings → General
Publisher & General Settings
| Setting | Description |
|---|---|
| Currency Symbol | The currency symbol displayed throughout the plugin (e.g., $, €, £). Default: $ |
| Publisher Revenue Share (%) | Percentage of ad revenue paid to publishers. (e.g., 70 means the publisher gets 70%, you keep 30%) |
| Minimum Withdrawal Amount | The minimum balance a publisher must have before they can request a withdrawal |
| Available Withdrawal Methods | One method per line. Shown as options to publishers (e.g., PayPal, Bank Transfer, Payoneer) |
| Sponsored Ad Tooltip Content | Rich text content that appears when users click the sponsored icon (⊕) on ads |
| Hide Dashboard Page Titles | Hides the main page titles on frontend dashboards for a cleaner appearance |
WooCommerce Integration
| Setting | Description |
|---|---|
| Ad Credit Product ID | The WooCommerce Product ID for the ad credit product (see Installation Step 3) |
Ad Network Settings
Navigate to Zeal Ad Manager → Settings → Ad Network
Ad Serving & Automation
| Setting | Description |
|---|---|
| Minimum Advertiser Budget | Minimum amount an advertiser can spend on a campaign. Default: 10 |
| Available HTML Ad Slots | Maximum number of HTML template ads active on the network. Set to 0 to disable. Default: 5 |
| Enabled Ad Templates | Select which ad formats are available to advertisers (Spotlight, Story, Banner, App Install, HTML, AI Dynamic, Animated) |
| Base CPC Rate | Base cost per click before multipliers are applied (e.g., 0.25) |
| Base CPM Rate | Base cost per 1,000 impressions before multipliers (e.g., 5.00) |
| Country Tier Multipliers | Define geographic pricing tiers. Format: US,CA,UK:1.5 (one tier per line). Unlisted countries default to 1.0 |
| Exclude Countries from Targeting | Comma-separated country codes to remove from advertiser targeting options (e.g., KP,IR,SY) |
| Enable Cross-Origin Ad Serving | Required for ads to work on external publisher sites. Enables CORS headers on the API |
| Enable Domain Referer Check | Recommended. Verifies ad requests come from approved publisher domains only |
| Serve Ads on Unapproved Sites | Not Recommended. Bypasses the approval system — ads serve on pending sites too |
| Auto-Approve New Ads | Skip manual admin review — ads go live immediately after payment |
| Auto-Verify New Sites | Automatically verify and approve publisher sites when the verification meta tag is detected |
AI Integration (Google Gemini)
Navigate to Zeal Ad Manager → Settings → Ad Network (AI Integration section)
The plugin uses Google's Gemini AI to automatically generate relevant keywords for ads and publisher sites, and to create AI-powered dynamic ad copy.
Setup
- Go to Google AI Studio and create an API key
- Enter the API key in the Gemini API Key field
- Save settings
What AI Does
- Keyword Generation — Analyzes ad landing pages and publisher site content to extract relevant keywords for intelligent ad matching
- AI Dynamic Ads — Generates 5 headlines, 3 descriptions, and relevant keywords from an advertiser's URL — automatically rotated for A/B testing
- Weekly Refresh — AI ad content and publisher keywords are automatically regenerated weekly via scheduled cron jobs
Privacy: Only advertiser landing page URLs and publisher site URLs are sent to Google's Gemini API. No visitor data is ever shared. This feature is entirely opt-in and requires manual API key configuration.
App Data Integration (RapidAPI)
For the App Install ad format, the plugin can fetch app metadata (icons, ratings, descriptions) from Google Play and Apple App Store.
- Create an account at RapidAPI
- Subscribe to the App Store & Google Play API
- Enter your X-RapidAPI-Key in the settings
GeoIP Country Targeting
The plugin includes a bundled MaxMind GeoLite2 Country database that runs entirely locally — no external API calls are made. The settings page shows the database status and version information.
Email Settings
Navigate to Zeal Ad Manager → Settings → Emails
Configure the sender information and customize all notification emails. Each email can be individually enabled/disabled and has customizable subject, heading, and body fields with placeholder support.
Sender Options
| Setting | Description |
|---|---|
| From Name | The name emails are sent from. Defaults to your site name |
| From Email | The email address emails are sent from. Defaults to admin email |
Email Notifications (8 Templates)
| Recipient | Trigger | Placeholders | |
|---|---|---|---|
| New Ad Submission | Admin | Advertiser submits a new campaign for review | {site_title}, {ad_title}, {user_name}, {review_link} |
| Ad Approved | Advertiser | Admin approves a campaign | {user_name}, {ad_title}, {dashboard_link} |
| Ad Rejected | Advertiser | Admin rejects a campaign | {user_name}, {ad_title}, {dashboard_link} |
| Budget Low | Advertiser | Campaign budget is running low | {user_name}, {ad_title}, {dashboard_link} |
| Site Approved | Publisher | Admin approves a publisher site | {user_name}, {site_url}, {dashboard_link} |
| Withdrawal Processed | Publisher | Admin processes a withdrawal request | {user_name}, {amount}, {dashboard_link} |
| Fill Rate Reduced | Publisher | Fraud detection automatically reduces ad fill rate | {user_name}, {site_url}, {new_fill_rate}, {dashboard_link} |
| Fill Rate Restored | Publisher | Activity returns to normal, fill rate auto-restored | {user_name}, {site_url}, {dashboard_link} |
Tools
Navigate to Zeal Ad Manager → Settings → Tools
- Export Settings — Download all plugin settings as a JSON file for backup or migration
- Import Settings — Upload a previously exported JSON settings file
- Clear Plugin Cache — Clears all transient caches used by the plugin
- Debug AI Models — Lists available Gemini AI models for troubleshooting
- Delete Data on Uninstall — When checked, all plugin data (posts, tables, settings, roles) will be permanently deleted upon uninstallation
Warning: The "Delete Data on Uninstall" option is destructive and irreversible. Only enable this if you are certain you want to remove all ad network data when uninstalling the plugin.
Ad Formats
Zeal Ad Manager supports 7 standard ad formats, each designed for different advertising objectives. Admins can enable or disable any format from the Ad Network Settings.
Spotlight Ad (300×250)
The classic medium rectangle ad. Ideal for sidebar placements and in-content advertising.
- Dimensions: 300 × 250 pixels
- Content: Image with headline, description, and CTA button
- Best for: General brand awareness and product promotion
Banner Ad (728×90)
The traditional leaderboard banner for header and footer placements.
- Dimensions: 728 × 90 pixels
- Content: Horizontal image with headline and CTA
- Best for: High-visibility header/footer placements
Story Ad (Vertical)
A vertical, full-height ad format inspired by social media stories.
- Content: Vertical image with overlay text, headline, and CTA
- Best for: Mobile-first campaigns and social media-style advertising
App Install Ad
A specialized format for promoting mobile applications. When an advertiser enters a Google Play or Apple App Store URL, the plugin automatically fetches the app's icon, name, rating, and description.
- Content: App icon, name, star rating, description, and "Install" CTA
- Auto-populated: Data is fetched automatically from app stores via RapidAPI
- Requires: RapidAPI key configured in settings
- Best for: App download campaigns
Animated Ad Builder
A powerful in-dashboard studio that lets advertisers create engaging animated HTML5 and video ads without any coding knowledge. The builder features live preview and 18+ professional animation templates.
Available Animation Templates
| Template | Description |
|---|---|
| Classic Slide | Clean sliding transitions with professional motion design |
| Minimal Style | Elegant minimalist animations with subtle effects |
| E-Commerce Ad | Product-focused with pricing callouts and buy-now CTAs |
| Instagram Style | Social media-inspired gradient and story-style animations |
| Twitter / X Style | Clean, card-based animations mimicking social feeds |
| TikTok Style | Vertical, bold, high-energy animations for youth audiences |
| Google Style | Material Design-inspired clean animations |
| Luxe Watch | Premium luxury product showcase with cinematic effects |
| Luxury Perfume | Elegant fragrance advertising with bokeh and shimmer effects |
| Elite Casino | High-energy casino and gaming promotional animations |
| Golden Spin | Prize wheel and spin-to-win style engagement |
| DeFi Pulse | Cryptocurrency and fintech ads with data-driven aesthetics |
| Focus Zoom | Cinematic zoom and focus effects for dramatic reveals |
| Ken Burns | Smooth pan-and-zoom photo animation effect |
| Image Reveal | Dramatic image reveal with masking transitions |
| Glitch Decode | Cyberpunk-inspired glitch effects with text decoding |
| Text Spotlight | Typography-focused with spotlight and highlighting effects |
| GIF Style | Frame-by-frame animation recreating classic GIF aesthetics |
Builder Features
- Live Preview — See your ad animate in real-time as you customize it
- Customizable Colors — Background colors, gradients, and accent colors
- Typography Control — Font selection, sizes, and text styling
- CTA Button Styling — Customize button text, colors, and shapes
- Media Upload — Upload images and videos for your animations
- JSON Recipe System — Templates use a JSON-based recipe for reproducible rendering
HTML Custom Ad
For advanced advertisers who want full creative control. Write custom HTML and CSS that renders inside the ad container.
- Content: Custom HTML markup with inline CSS
- Slot Limit: Configurable maximum number of active HTML ads (default: 5)
- Security: Rendered inside Shadow DOM for CSS isolation
- Best for: Custom interactive ads and rich media campaigns
AI-Powered Dynamic Ad
Let Google Gemini AI automatically generate ad copy from a URL. The AI analyzes the landing page content and creates multiple variations for automatic rotation.
- Auto-generated: 5 headlines + 3 descriptions + relevant keywords
- A/B Testing: Variations are automatically rotated across impressions
- Weekly Refresh: Content is regenerated weekly via cron to stay current
- Requires: Gemini API key configured in settings
- Best for: Advertisers who want quick, professional ad copy without manual effort
ZealUp Premium Ad Formats
ZealUp formats are high-impact overlay ads that appear on top of publisher page content. They deliver significantly higher visibility and engagement rates compared to standard in-page ads.
Note: ZealUp ads are served using dedicated JavaScript files that publishers embed on their sites alongside the standard ad-serving script. Each format has its own script for optimal performance.
Anchor Ad
A small, sticky ad that floats in the bottom-right corner of the viewport. It stays visible as the user scrolls and includes a close button for user control.
- Position: Bottom-right corner, fixed on scroll
- Behavior: Appears after page load, dismissible by the user
- Shadow DOM: Rendered in an isolated Shadow DOM container for CSS safety
- Best for: Persistent brand exposure without disrupting content consumption
Sticky Bar
A full-width bar that sticks to the top or bottom of the viewport. Commonly used for announcements, promotions, and high-visibility CTA campaigns.
- Position: Top or bottom of the viewport, full width
- Behavior: Fixed position, scrolls with the page, dismissible
- Best for: Site-wide promotional banners and time-sensitive offers
Vignette (Full-Screen Interstitial)
A full-screen overlay ad that appears between page loads. This premium format captures maximum attention and is commonly used by major ad networks.
- Position: Full-screen overlay covering the entire viewport
- Behavior: Triggered between navigation events, dismissible with a close button
- Frequency Cap: Built-in session-based frequency limiting to avoid user fatigue
- Best for: High-value campaigns requiring maximum visibility and engagement
Dynamic Pricing Engine
At the heart of Zeal Ad Manager is an intelligent, real-time pricing engine that calculates ad costs dynamically based on multiple factors. This creates a fair, performance-based ecosystem where high-quality publishers earn more and advertisers pay appropriate rates.
How Pricing Works
Every impression and click is priced using this formula:
Final Price = Base Rate × Geographic Multiplier × Performance Multiplier
Base Rates
- CPC (Cost Per Click) — The base amount charged per ad click (configurable in settings)
- CPM (Cost Per 1,000 Impressions) — The base amount charged per 1,000 ad impressions (configurable in settings)
Geographic Multiplier
Different countries have different advertising value. Configure tier-based multipliers in settings:
# Example Country Tier Configuration
US,CA,GB,AU:1.5 # Tier 1 - Premium markets (1.5x rate)
DE,FR,JP,KR:1.2 # Tier 2 - Strong markets (1.2x rate)
BR,MX,IN,ID:0.8 # Tier 3 - Emerging markets (0.8x rate)
# All unlisted countries default to 1.0x
Performance Multiplier
Publisher sites with higher click-through rates (CTR) command higher prices, rewarding quality content and engaged audiences. This multiplier is calculated automatically based on historical performance data.
Revenue Split
After the final price is calculated, the revenue is split between the network (you) and the publisher based on the Publisher Revenue Share percentage configured in General Settings.
# Example with 70% Publisher Share
Ad Click Revenue: $0.30
Publisher Earnings: $0.30 × 70% = $0.21
Network Earnings: $0.30 × 30% = $0.09
Advertiser Dashboard
The advertiser dashboard is a self-service frontend interface where advertisers manage their campaigns, track performance, and fund their accounts. It's rendered by the [zam_advertiser_dashboard] shortcode.
Creating a Campaign
- Log in as an Advertiser and navigate to the Advertiser Dashboard
- Click "Create New Ad"
- Choose an ad format (Spotlight, Banner, Story, App Install, HTML, Animated, or AI Dynamic)
- Fill in the campaign details:
- Campaign Name — Internal name for your campaign
- Destination URL — Where users go when they click the ad
- Creative Assets — Upload images, write headlines, descriptions, and CTA text
- Configure targeting options (see below)
- Set your campaign budget
- Submit the campaign for review (or it goes live immediately if auto-approve is enabled)
- Complete payment via WooCommerce checkout
Targeting Options
Advertisers can narrow their audience using the following targeting criteria:
| Targeting Type | Description |
|---|---|
| Device Targeting | Target Desktop only, Mobile only, or All Devices |
| Country Targeting | Select specific countries from a list of 200+ options (powered by GeoIP) |
| Site Category Targeting | Target ads to specific publisher site categories (e.g., Technology, Sports, Finance) |
Campaign Analytics
Each campaign includes detailed performance metrics:
- Impressions — How many times the ad was displayed
- Clicks — How many times users clicked the ad
- CTR (Click-Through Rate) — Percentage of impressions that resulted in clicks
- Total Spend — Amount consumed from the campaign budget
- Remaining Budget — How much budget is left
- Geographic Breakdown — Performance data broken down by country
Billing & Funding
- Advertisers fund campaigns through the WooCommerce checkout flow
- The campaign budget is set during ad creation and can be topped up later
- When the budget runs low, an email notification is sent automatically (if enabled)
- Campaigns are automatically paused when the budget reaches zero
- View complete billing history and transaction records in the dashboard
Publisher Dashboard
The publisher dashboard is a frontend interface where publishers manage their sites, get ad code, track earnings, and request withdrawals. It's rendered by the [zam_publisher_dashboard] shortcode.
Adding a Site
- Log in as a Publisher and navigate to the Publisher Dashboard
- Click "Add New Site"
- Enter your site details:
- Site URL — The full URL of your website
- Site Name / Description — A description of your site's content
- Category — Select the most relevant site category
- Submit the site for verification
Site Verification
To prove site ownership, publishers must add a verification meta tag to their site's <head> section:
<meta name="zeal-ad-verification" content="YOUR_UNIQUE_CODE">
The unique verification code is provided in the publisher dashboard after submitting a site. Once the tag is in place:
- Manual Verification: An admin manually verifies the site from the admin panel
- Auto-Verification: If enabled in settings, the system automatically checks for the meta tag and approves the site
Upon verification, the plugin triggers AI keyword analysis (if Gemini is configured) to extract relevant content keywords from the publisher's site for better ad matching.
Getting the Ad Code
Once a site is approved, publishers can access their ad-serving code from the dashboard. The code consists of JavaScript snippets that they paste into their site's HTML:
<!-- Zeal Ad Manager - Standard Ad Zone -->
<div id="zam-ad-zone" data-site-id="YOUR_SITE_ID" data-template="spotlight"></div>
<script src="https://your-network.com/wp-content/plugins/zeal-ad-manager/public/zam-ad-server.js"></script>
For ZealUp premium formats, separate scripts are provided:
<!-- Anchor Ad -->
<script src=".../public/zealup-anchor.js" data-site-id="YOUR_SITE_ID"></script>
<!-- Sticky Bar -->
<script src=".../public/zealup-sticky-bar.js" data-site-id="YOUR_SITE_ID"></script>
<!-- Vignette -->
<script src=".../public/zealup-vignette.js" data-site-id="YOUR_SITE_ID"></script>
Earnings & Withdrawals
- Earnings Dashboard — View total earned, pending balance, and paid-out amounts
- Earnings Breakdown — See per-site performance with impressions, clicks, and revenue
- Ad Fill Rate — Percentage of ad requests that return an ad (adjustable by the publisher, may be auto-reduced by fraud detection)
- Withdrawal Request — Request a payout when balance exceeds the minimum withdrawal amount
- Payment Methods — Save preferred payment methods (PayPal, Bank Transfer, Payoneer, etc.)
- Withdrawal History — Track the status of all past withdrawal requests
Note: Publisher earnings are calculated from the revenue split defined in General Settings. Earnings are processed via scheduled cron jobs (every 30 minutes for impressions, hourly for clicks).
Ad Serving Architecture
Zeal Ad Manager uses a modern, high-performance ad delivery system built on vanilla JavaScript with no framework dependencies.
Shadow DOM Isolation
All ads are rendered inside a Shadow DOM container. This provides complete CSS isolation between the ad creative and the publisher's site, preventing style conflicts in either direction.
- Publisher CSS cannot accidentally break ad layouts
- Ad CSS cannot leak into and affect the publisher's page design
- Each ad gets its own isolated DOM tree with dedicated stylesheets
- Stylesheets are loaded asynchronously with a FOUC prevention system — ads remain hidden until all styles are fully loaded
GeoIP Targeting
Geographic targeting is powered by the bundled MaxMind GeoLite2 Country database. This database operates entirely locally on your server:
- No external API calls — All IP-to-country lookups are performed locally
- 200+ countries supported
- Used for: Country-based ad targeting, geographic pricing multipliers, and fraud detection country analysis
- Database location:
includes/geoip/GeoLite2-Country.mmdb
CORS & Security
Since ads are served cross-origin (from your WordPress site to external publisher sites), the plugin implements a secure CORS policy:
- Dynamic CORS Headers — The API only responds with CORS headers for approved publisher domains
- Referer Check — Optionally verifies that ad requests originate from registered publisher domains
- Domain Verification — Publishers must prove site ownership before serving ads
Performance Features
- Lightweight Scripts — Vanilla JavaScript with no framework dependencies (~20KB total)
- Lazy Loading — Uses
IntersectionObserverAPI to only load ads when they enter the viewport - Fetch API — Modern
fetch()for efficient, non-blocking API requests - Async Style Loading — CSS stylesheets load in parallel without blocking page rendering
Scheduled Background Tasks
The plugin registers several WordPress cron jobs for background processing:
| Task | Frequency | Purpose |
|---|---|---|
| Process Impressions | Every 30 minutes | Calculates charges and publisher earnings from impression data |
| Process Clicks | Hourly | Calculates charges and publisher earnings from click data |
| Calculate Pending Earnings | Every 30 minutes | Updates publisher pending balance totals |
| Fraud Detection | Daily | Analyzes click/impression patterns for suspicious activity |
| Regenerate AI Content | Weekly | Refreshes AI-generated ad copy for dynamic ads |
| Re-Analyze Publisher Keywords | Weekly | Updates AI-generated keywords for publisher sites |
Important: WordPress cron is triggered by site visits. For a production ad network, it's strongly recommended to set up a real server cron job to ensure tasks run on schedule regardless of traffic. Add to your server's crontab:
*/5 * * * * wget -q -O - https://your-site.com/wp-cron.php?doing_wp_cron > /dev/null 2>&1
Shortcodes Reference
Zeal Ad Manager provides 9 shortcodes for embedding dashboards, registration forms, and ad zones on any WordPress page. The three dashboard/registration shortcodes are automatically placed on pages created during plugin activation.
Dashboard & Registration Shortcodes
| Shortcode | Description | Parameters | Access |
|---|---|---|---|
[zam_advertiser_dashboard] |
Full advertiser dashboard with campaign management, creation, analytics, and billing history | None | zam_advertiser role or admin |
[zam_publisher_dashboard] |
Full publisher dashboard with site management, ad code, earnings tracking, and withdrawals | None | zam_publisher role or admin |
[zam_register_form] |
Registration form with Advertiser/Publisher role selection. Shows a "go to dashboard" message if already logged in | None | Public (logged-out users) |
Ad Display Shortcodes
These shortcodes display ad zones on your own WordPress site. They are primarily used for internal ad serving — publisher sites use the JavaScript ad code from their dashboard instead.
General Ad Zone
[zam_ad_zone] — The primary shortcode for displaying any ad format. All parameters can be configured to control exactly which ads appear.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
site_id |
Integer | Yes | — | The publisher site ID. Determines which ads are eligible to serve. Find this in the publisher dashboard or admin panel under the site's listing. |
template |
String | No | spotlight |
The ad format to display. Accepted values: spotlight, banner, story, app-install, html, ai-dynamic-text, animated |
ad_id |
String | No | Empty | Comma-separated list of specific ad IDs to serve. When empty, any eligible ad matching the template and targeting criteria will be shown. |
Examples
<!-- Display a Spotlight ad (300x250) -->
[zam_ad_zone site_id="42" template="spotlight"]
<!-- Display a Banner ad (728x90) -->
[zam_ad_zone site_id="42" template="banner"]
<!-- Display a Story ad (vertical) -->
[zam_ad_zone site_id="42" template="story"]
<!-- Display an App Install ad -->
[zam_ad_zone site_id="42" template="app-install"]
<!-- Display a custom HTML ad -->
[zam_ad_zone site_id="42" template="html"]
<!-- Display an AI Dynamic ad -->
[zam_ad_zone site_id="42" template="ai-dynamic-text"]
<!-- Display an Animated ad -->
[zam_ad_zone site_id="42" template="animated"]
<!-- Display a specific ad by ID -->
[zam_ad_zone site_id="42" template="spotlight" ad_id="105"]
<!-- Display one of several specific ads (randomly selected) -->
[zam_ad_zone site_id="42" template="banner" ad_id="105,210,315"]
Template-Specific Convenience Shortcodes
For convenience, each ad format also has its own dedicated shortcode that automatically sets the template parameter. These accept the same site_id (required) and ad_id (optional) parameters.
| Shortcode | Equivalent To | Ad Format |
|---|---|---|
[zam_spotlight_ad_zone site_id="42"] |
[zam_ad_zone site_id="42" template="spotlight"] |
Spotlight (300×250) |
[zam_banner_ad_zone site_id="42"] |
[zam_ad_zone site_id="42" template="banner"] |
Banner (728×90) |
[zam_story_ad_zone site_id="42"] |
[zam_ad_zone site_id="42" template="story"] |
Story (Vertical) |
[zam_app_install_ad_zone site_id="42"] |
[zam_ad_zone site_id="42" template="app-install"] |
App Install |
[zam_html_ad_zone site_id="42"] |
[zam_ad_zone site_id="42" template="html"] |
HTML Custom |
Convenience Shortcode Examples
<!-- These pairs are equivalent: -->
[zam_spotlight_ad_zone site_id="42"]
[zam_ad_zone site_id="42" template="spotlight"]
<!-- With specific ad IDs -->
[zam_banner_ad_zone site_id="42" ad_id="105,210"]
[zam_ad_zone site_id="42" template="banner" ad_id="105,210"]
Note: The site_id parameter is always required for ad zone shortcodes. Without it, no ads will be served. You can find a site's ID in the admin panel under the publisher sites listing, or in the publisher's dashboard.
How Ad Zones Work
When an ad zone shortcode is placed on a page:
- The shortcode renders a
<div class="zeal-ad-unit">container with data attributes forsite_id,template, and optionallyad_id. - The
zam-ad-server.jsscript detects the container and calls the REST API endpoint (/wp-json/zeal-ad-manager/v1/serve). - The API selects an eligible ad based on template, targeting (device, country, categories), budget availability, and fill rate.
- The ad is rendered inside a Shadow DOM container for complete CSS isolation from the host page.
- Impressions are tracked automatically when the ad becomes 50% visible in the viewport via IntersectionObserver.
- Clicks are tracked and redirected through the plugin's click tracking endpoint.
User Roles & Capabilities
The plugin creates two custom WordPress user roles upon activation:
| Role | ID | Capabilities |
|---|---|---|
| Advertiser | zam_advertiser |
|
| Publisher | zam_publisher |
|
Note: Both roles have the WordPress admin bar hidden for a cleaner frontend experience. Users register via the [zam_register_form] shortcode and select their role during registration.
Fraud Detection System
Zeal Ad Manager includes an automated fraud detection system that runs daily to protect advertisers from invalid clicks and suspicious activity.
What It Monitors
- Suspicious CTR Patterns — Flags publisher sites with abnormally high click-through rates that may indicate click fraud
- Geographic Anomalies — Detects unusual concentrations of clicks from single geographic regions
- Rapid Click Patterns — Identifies rapid, repeated clicks from the same sources
Automated Actions
- Fill Rate Reduction — When suspicious activity is detected, the publisher's ad fill rate is automatically reduced (limiting the percentage of ad requests that return an ad)
- Email Notification — The publisher is notified via email that their fill rate has been reduced
- Auto-Restoration — Once activity returns to normal levels, the fill rate is automatically restored to 100%
- Restoration Notification — The publisher is notified when their fill rate is restored
Admin Visibility
The admin dashboard surfaces fraud detection findings in reports, allowing admins to manually investigate flagged sites and take additional action if needed.
External Services
Zeal Ad Manager connects to the following external services. All connections are opt-in and require manual configuration.
Google Gemini AI API
| Detail | Information |
|---|---|
| Purpose | Auto-generate keywords for ads and publisher sites; generate AI ad copy |
| Data Sent | Website URLs and public HTML content (no visitor data) |
| When Used | When admin enables AI and provides a Gemini API key |
| Provider | Google LLC |
| API Endpoint | https://generativelanguage.googleapis.com/v1/ |
| Terms of Service | ai.google.dev/gemini-api/terms |
| Privacy Policy | policies.google.com/privacy |
RapidAPI — App Store Data Service
| Detail | Information |
|---|---|
| Purpose | Fetch app icons, ratings, descriptions for App Install ads |
| Data Sent | App store URLs only (no user data) |
| When Used | When an advertiser creates an App Install ad with an app store URL |
| Provider | RapidAPI |
| API Endpoint | https://app-store-and-google-play-api.p.rapidapi.com/ |
| Terms of Service | rapidapi.com/terms |
| Privacy Policy | rapidapi.com/privacy |
MaxMind GeoLite2 Database (Bundled)
| Detail | Information |
|---|---|
| Purpose | IP-to-country lookups for geographic targeting |
| Data Sent | None — operates entirely locally |
| Database File | includes/geoip/GeoLite2-Country.mmdb |
| License | CC BY-SA 4.0 |
| More Info | MaxMind GeoLite2 |
Uninstallation
Zeal Ad Manager can be cleanly uninstalled with optional data removal.
Standard Uninstall
Deactivating and deleting the plugin via the WordPress Plugins page will remove all plugin files. By default, your data (ads, sites, settings, tables) is preserved for safety.
Complete Data Removal
If you want to remove all plugin data permanently, follow these steps before uninstalling:
- Go to Zeal Ad Manager → Settings → Tools
- Check the "Delete Data on Uninstall" checkbox
- Save settings
- Then deactivate and delete the plugin
Warning: With this option enabled, uninstalling the plugin will permanently delete:
- All plugin files
- Custom database tables (
zeal_ad_stats,zeal_ad_targeting) - All ad listings, publisher sites, and withdrawal posts
- Custom user roles (Advertiser, Publisher) — users will have no role until re-assigned
- All plugin options and settings from the database
Your site's content, other plugins, and themes are never affected.
Troubleshooting
Common issues and their solutions.
Ads Not Displaying on Publisher Sites
Check CORS Settings
Symptom: Browser console shows CORS errors, ads don't load
Solution:
- Go to Zeal Ad Manager → Settings → Ad Network
- Ensure "Enable Cross-Origin Ad Serving" is checked
- Verify the publisher's site is approved and active
Check Publisher Site Status
Symptom: API returns empty results
Solution:
- Verify the publisher site is in "Approved" status in the admin panel
- Ensure the site URL matches the domain serving the ad code
- Check that "Serve Ads on Unapproved Sites" is properly configured
Check Ad Availability
Symptom: Site is approved but no ads appear
Solution:
- Verify active, approved ads exist in the system with remaining budget
- Check targeting — do any ads target the visitor's country/device?
- Verify the
site_idandtemplatein the ad code are correct
Ads Appear Unstyled or Broken
Symptom: Ads display with broken layout or no styling on first load
Solution: This is typically a caching issue. The plugin includes a built-in FOUC (Flash of Unstyled Content) prevention system. If you still see this issue:
- Clear your browser cache
- Clear any server-side caching (CDN, page cache, object cache)
- Verify the CSS files are accessible at the plugin's URL
WooCommerce Integration Issues
Advertiser Can't Fund Campaign
Solution:
- Verify WooCommerce is active and properly configured
- Check that the Ad Credit Product ID is correct in settings
- Ensure the WooCommerce product is published (not draft)
- Verify at least one payment gateway is enabled in WooCommerce
AI Features Not Working
Keywords Not Generating
Solution:
- Verify your Gemini API Key is entered correctly in settings
- Use the "Debug AI Models" tool in Settings → Tools to verify the API connection
- Ensure your server can make outbound HTTPS requests to
generativelanguage.googleapis.com - Check that the landing page URL is publicly accessible
Emails Not Sending
Solution:
- Verify the specific email notification is enabled in Email Settings
- Check that the From Email is valid and properly configured
- Test with an SMTP plugin (e.g., WP Mail SMTP) for reliable delivery
- Check your spam/junk folder
Cron Jobs Not Running
Symptom: Earnings not updating, fraud detection not running
Solution: WordPress cron is "pseudo-cron" triggered by page visits. For a production ad network:
- Add
define('DISABLE_WP_CRON', true);towp-config.php - Set up a real server cron job:
*/5 * * * * wget -q -O - https://your-site.com/wp-cron.php?doing_wp_cron > /dev/null 2>&1
Publisher Verification Failing
Solution:
- Ensure the meta tag is in the site's
<head>section (not inside<body>) - Verify the verification code matches exactly (no extra spaces)
- Check that the site is publicly accessible (not behind a password or firewall)
- Clear server-side caching on the publisher's site to ensure the meta tag is visible
Support & Updates
Getting Support
Need Help?
If you encounter issues not covered in this documentation, we're here to help:
- Support Portal: Submit a ticket edubrazeal.com
- Documentation: Check this guide for detailed setup and troubleshooting
- Response Time: We typically respond within 24-48 business hours
When contacting support, please include:
- Your WordPress version and PHP version
- Plugin version number
- A description of the issue with screenshots if possible
- Any browser console errors (right-click → Inspect → Console tab)
- Whether the issue occurs with other plugins deactivated
Updates
Zeal Ad Manager receives regular updates with new features, bug fixes, and security patches.
Installing Updates
Always back up your site before updating! Use a backup plugin or your hosting provider's backup tools.
- Go to Plugins → Add New → Upload Plugin
- Upload the new zip file
- Click "Replace current with uploaded"
- Verify everything works correctly after the update
Best Practices
- Regular Backups — Schedule automated backups of your database and files
- Server Cron — Set up a real server cron job for reliable scheduled task execution
- SSL Certificate — Always use HTTPS for your ad network site (required for secure API connections)
- WooCommerce Updates — Keep WooCommerce updated for payment security
- Monitor Reports — Regularly review fraud detection reports and network analytics
- Review Ads Promptly — Approve or reject pending ads quickly to maintain advertiser satisfaction
- Process Withdrawals — Pay publishers promptly to build trust and retain quality sites
- GeoIP Database — The bundled GeoLite2 database is updated with plugin releases. For more frequent updates, consider a MaxMind license