Athenian SiteAds

Developer starting point

This baseline documents SiteAds configuration and rendering code. It does not claim that live ad delivery, tracking, or provider reporting has been exercised.

Admin Workflow

1. Create an Ad

An administrator creates a new Site Ad from the WordPress admin. The record supports a title and featured image, with additional details controlled from the Ad Details metabox.

2. Choose Billing Target

The admin selects whether the ad should bill an affiliate or vendor. The plugin then shows the appropriate dropdown sourced from existing aam_affiliate or ab_vendor posts.

3. Configure Destination

The ad can point to a custom target URL or a WooCommerce product ID. If the custom target URL is blank and a product ID is present, the plugin uses the product permalink.

4. Choose Creative

The admin can provide custom HTML, a remote image URL, or a featured image. If none exists, the plugin renders a text fallback from the ad title.

5. Set Pricing and Dates

The admin chooses CPM, CPC, or fixed pricing, sets the rate, and optionally provides start/end dates in GMT using YYYY-MM-DD format.

6. Assign Slot

The admin assigns one or more ad-slot taxonomy terms, allowing template authors to place rotating ads by slot name.

7. Render on the Storefront

A shortcode is inserted into a page, post, template, widget, Bricks element, or other shortcode-capable surface.

8. Review Reporting and Billing

The report screen shows daily metrics and billing status. Billing can run automatically by WP-Cron or manually through WP-CLI.

Technical Architecture

Main Bootstrap

Primary plugin file:

athenian-siteads.php

The plugin defines constants and boots on plugins_loaded:

define('ATH_SITEADS_VERSION', '0.1.1');
define('ATH_SITEADS_FILE', __FILE__);
define('ATH_SITEADS_PATH', plugin_dir_path(__FILE__));
define('ATH_SITEADS_URL', plugin_dir_url(__FILE__));

The plugin header currently lists version 0.1.0, while the runtime constant is 0.1.1. The constant appears to be the newer operational version and is used for install/update checks and asset versioning.

Namespaces and Classes

Namespace:

Athenian\SiteAds

Main classes:

| Class | Responsibility | | --- | --- | | Plugin | Singleton container, component initialization, logging, OwlPay detection. | | Ads | CPT/taxonomy registration, shortcode rendering, public assets, rewrite route, click redirect. | | Tracking | REST route registration, impression/click event recording, daily rollups. | | Billing | WP-Cron scheduling and OwlPay debit processing. | | Admin | Metaboxes, ad list columns, reports screen, settings screen, settings save handler. | | Installer | Activation setup, database table creation, rewrite flush. | | DB | Centralized table-name properties. | | Settings | Option read/update wrapper for ath_siteads_settings. | | CLI | WP-CLI root command and subcommand router. | | Util | Money formatting, string clamp helper, SHA hashing, public-context helper. |

Autoloading

The plugin includes a simple namespace-based autoloader in:

includes/autoload.php

It maps Athenian\SiteAds\ClassName to:

includes/ClassName.php

It also exposes a global helper:

ath_siteads()

WordPress Hooks and Integration Points

Boot and Activation

| Hook | Purpose | | --- | --- | | plugins_loaded | Boot the plugin singleton. | | register_activation_hook | Install custom tables and flush rewrites. | | admin_init | Run table install/update when version changes. |

Content and Rendering

| Hook/API | Purpose | | --- | --- | | init | Register CPT, taxonomy, meta, and rewrite tag/rule. | | add_shortcode('ath_siteads') | Render ads by ID or slot. | | wp_enqueue_scripts | Enqueue public JavaScript and CSS. | | template_redirect | Process tracked click redirects. |

Admin UI

| Hook | Purpose | | --- | --- | | add_meta_boxes_ath_sitead | Add the Ad Details metabox. | | save_post_ath_sitead | Save ad campaign metadata. | | manage_ath_sitead_posts_columns | Add custom list table columns. | | manage_ath_sitead_posts_custom_column | Render slot, bill-to, model, rate, and today's metrics. | | admin_menu | Register reports and settings submenu pages. | | admin_enqueue_scripts | Load admin CSS for SiteAds screens. | | admin_post_ath_siteads_save_settings | Save settings securely with nonce and capability checks. |

REST and Tracking

| Hook/API | Purpose | | --- | --- | | rest_api_init | Register the public impression endpoint. | | ath-siteads/v1/impression | Record an impression for an active ad. |

Billing

| Hook | Purpose | | --- | --- | | init | Ensure the daily billing event is scheduled. | | ath_siteads_bill_daily | Run daily OwlPay billing for unbilled rows. |

Data Model

Options

| Option | Purpose | | --- | --- | | ath_siteads_installed | Stores the installed schema/version marker. | | ath_siteads_settings | Stores debug and dedupe settings. |

Post Meta

All ad metadata uses the _ath_siteads_ prefix.

| Meta Key | Type | Purpose | | --- | --- | --- | | _ath_siteads_bill_to_type | string | affiliate or vendor. | | _ath_siteads_bill_to_id | integer | Selected affiliate/vendor record ID. | | _ath_siteads_affiliate_id | integer | Legacy affiliate mirror for compatibility. | | _ath_siteads_product_id | integer | Optional WooCommerce product destination. | | _ath_siteads_target_url | string | Optional explicit destination URL. | | _ath_siteads_html | string | Optional custom creative HTML. | | _ath_siteads_image_url | string | Optional remote image creative. | | _ath_siteads_model | string | cpm, cpc, or fixed. | | _ath_siteads_rate | number | USD rate for CPM/CPC pricing. | | _ath_siteads_status | string | active or paused. | | _ath_siteads_start_at | string | Optional GMT start date, YYYY-MM-DD. | | _ath_siteads_end_at | string | Optional GMT end date, YYYY-MM-DD. | | _ath_siteads_notes | string | Internal notes. |

Custom Database Tables

The plugin installs two custom tables through dbDelta().

#### Event Table

Table name:

{prefix}_ath_siteads_events

Purpose: raw impression/click event ledger.

Key columns:

| Column | Purpose | | --- | --- | | id | Primary key. | | ad_id | Site ad post ID. | | affiliate_id | Legacy affiliate ID for compatibility. | | bill_to_type | affiliate or vendor. | | bill_to_id | Billing target ID. | | event_type | impression or click. | | cost | Cost accrued by the event. | | ip_hash | SHA-256 hash of requester IP. | | ua_hash | SHA-256 hash of user agent. | | wp_user_id | Logged-in WordPress user ID, if available. | | created_at | GMT timestamp. |

Indexes include ad ID, affiliate ID, bill-to pair, event type, and created date.

#### Daily Table

Table name:

{prefix}_ath_siteads_daily

Purpose: aggregated daily metrics and billing state.

Key columns:

| Column | Purpose | | --- | --- | | id | Primary key. | | day | GMT day. | | ad_id | Site ad post ID. | | affiliate_id | Legacy affiliate ID. | | bill_to_type | affiliate or vendor. | | bill_to_id | Billing target ID. | | impressions | Daily impression count. | | clicks | Daily click count. | | cost | Daily campaign cost. | | billed | Whether the row has been billed. | | billed_ledger_id | OwlPay ledger entry ID after billing. | | created_at | GMT creation timestamp. | | updated_at | GMT update timestamp. |

The table enforces a unique key on (day, ad_id), allowing ON DUPLICATE KEY UPDATE rollups.

Security and Operational Notes

Public Impression Endpoint

The impression endpoint is public by design because anonymous visitors must be able to record impressions. The endpoint validates that the ad exists, is published, is active, and falls within the date window before recording.

For high-traffic or paid-campaign environments, future versions may want rate limiting, bot filtering, or server-side viewability logic.

Cookie Dedupe

Impression dedupe is cookie-based. This reduces accidental repeated impressions from the same visitor in a short window but does not provide fraud-proof advertising measurement.

Hashed IP and User-Agent Storage

Raw IP addresses and user-agent strings are not stored. Instead, the plugin stores SHA-256 hashes, which is a better privacy posture for basic event logging.

Custom HTML Creative

The plugin can render custom HTML from the ad record. The admin note states that this output is not sanitized beyond WordPress capability checks. This is flexible for trusted administrators, but sites should restrict ad editing to trusted roles only.

External URL Redirect Behavior

The click redirect uses wp_safe_redirect(). This is conservative and safer, but WordPress may block external campaign destinations unless the host is allowed through WordPress redirect host filtering. If external ad destinations are a primary requirement, the redirect behavior should be verified in a live install and adjusted with explicit URL validation and allowed-host handling.

Version Marker Mismatch

The plugin header lists 0.1.0, while the ATH_SITEADS_VERSION constant is 0.1.1. Aligning these values will reduce confusion in plugin inventory, cache busting, and update tracking.

Example Implementation Scenarios

Vendor Sponsored Product Placement

A vendor funds a homepage or category sidebar ad. The admin creates a SiteAd, selects vendor as the bill-to type, chooses the vendor record, assigns the homepage-sidebar slot, sets a CPC rate, and renders the slot in the storefront template.

Affiliate Campaign Banner

An affiliate sponsors a campaign banner that links to a specific WooCommerce product. The ad is assigned to an affiliate record, linked to a product ID, priced by CPM, and rendered in content blocks or landing pages.

Internal House Promotion

The store runs a fixed/no-billing ad promoting a seasonal category. The campaign still records impressions and clicks, giving the team performance visibility without partner billing.

Multi-Ad Rotation

A template renders several random ads from the same slot:

[ath_siteads slot="sidebar" limit="3" order="rand"]

This allows lightweight creative rotation without a separate ad-management interface.

Implementation Summary

Athenian SiteAds provides a compact but commercially useful onsite advertising layer for WooCommerce. It combines native WordPress ad management, placement slots, public shortcodes, impression/click tracking, CPM/CPC cost accrual, daily reporting, and optional OwlPay debiting for affiliates or vendors.

For Athenian Platform builds, the plugin fills an important monetization gap: it turns promotional surfaces inside the storefront into structured, measurable, and potentially billable inventory without introducing an external ad-server stack.