OAds v4.0.1

Ad meta keys

Device targeting (_oads_target_device)

User role targeting (_oads_target_roles)

Comma-separated role slugs. Special values: logged_in (any authenticated user), logged_out (unauthenticated visitors), or any WP role slug such as subscriber, editor. Example: logged_in, subscriber

Category targeting (_oads_target_categories)

Comma-separated category IDs. Ad shows only when the current page belongs to one of those categories. Works on singular posts and category archive pages. Example: 3, 7, 12

Country targeting (_oads_target_countries)

Comma-separated ISO 3166-1 alpha-2 codes. Requires a geo-IP lookup at the theme level. OAds reads the constant or option OADS_VISITOR_COUNTRY. Leave blank to show to all countries.

Frequency cap (_oads_freq_cap)

Maximum impressions per user per day. Implemented in JavaScript using localStorage (key: oads_fc_{ad_id}). Set to 0 to disable.

Date scheduling

Shortcodes

OAds registers four shortcodes covering ad delivery, the advertiser self-serve portal, the advertiser dashboard, and the sellable plans grid.

SHORTCODE[oads]
[oads section="blog" count="2"]
[oads type="inline" section="shop"]
[oads zone="sidebar"]
[oads placement="sidebar" section="global" count="1"]

[oads_portal]              // advertiser submission form
[oads_portal_dashboard]    // logged-in advertiser dashboard (their submissions + status)
[oads_plans]               // sellable plans pricing grid

[oads] attributes

PHP template functions

PHP// Show 1 card ad in blog section
oads_show( 'blog', 1 );

// Show 2 inline ads
oads_show_inline( 'global', 2 );

// Get raw HTML
$html = oads_get( 'homepage', 1 );

// Inject an ad every 6 items in a WP_Query loop
foreach ( $items as $i => $item ) {
    // … render item …
    oads_inject_in_loop( 'blog', 6, $i );
}

// Render a named zone
oads_zone( 'sidebar-top', 'card' );

WP action hook

PHPdo_action( 'oads_zone', 'blog', 'inline' );

Automatic injection

OAds auto-injects ads without any template code, and respects a cap of 3 ads per page. Ads in header and footer elements are automatically hidden via a <style> injection.

Setting up a group

Dashboard metrics

Revenue formula

Set CPM and/or CPC rates per ad in the ad editor. Total revenue is the sum across all ads for the selected period.

Time periods

CSV export

Click Export Impressions CSV or Export Clicks CSV on the Analytics or Log tab. AJAX action: oads_export_csv. Parameters: type (impressions|clicks), period (7d|30d|90d|all).

Consent gate

Enable Settings → Privacy & GDPR → Require consent before tracking. The frontend JS checks localStorage.getItem('oads_consent') === '1' before firing any impression or click tracking. If consent is absent, the ad still displays but no data is recorded.

Your CMP (cookie banner) should set this when the user consents:

JSlocalStorage.setItem('oads_consent', '1');

Data stored

Ad disclosure label

Every ad carries a disclosure label (default: Sponsored). Override per-ad in the editor. Ensures compliance with FTC guidelines and similar requirements.

wp_oads_impressions

SQLid          BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY
ad_id       BIGINT UNSIGNED NOT NULL
page_url    VARCHAR(500)
section     VARCHAR(100)
visitor_ip  VARCHAR(45)
user_agent  VARCHAR(500)
created_at  DATETIME DEFAULT CURRENT_TIMESTAMP

INDEX idx_ad_id (ad_id)
INDEX idx_created (created_at)
INDEX idx_section (section)

wp_oads_clicks

SQLid          BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY
ad_id       BIGINT UNSIGNED NOT NULL
page_url    VARCHAR(500)
section     VARCHAR(100)
visitor_ip  VARCHAR(45)
user_agent  VARCHAR(500)
referrer    VARCHAR(500)
created_at  DATETIME DEFAULT CURRENT_TIMESTAMP

INDEX idx_ad_id (ad_id)
INDEX idx_created (created_at)

wp_oads_zones

SQLid              BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY
name            VARCHAR(100)
slug            VARCHAR(100) UNIQUE
max_width       INT UNSIGNED
max_height      INT UNSIGNED
fill_priority   ENUM('direct','house','remnant')
adsense_code    TEXT
prebid_enabled  TINYINT(1) DEFAULT 0
prebid_sizes    VARCHAR(200) DEFAULT '300x250'
created_at      DATETIME DEFAULT CURRENT_TIMESTAMP

wp_oads_groups

SQLid              BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY
name            VARCHAR(100)
rotation_type   ENUM('random','roundrobin','ab')
ab_winner       BIGINT UNSIGNED DEFAULT 0
created_at      DATETIME DEFAULT CURRENT_TIMESTAMP

wp_oads_video_events

SQLid          BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY
ad_id       BIGINT UNSIGNED NOT NULL
event_type  VARCHAR(20)   /* start, q1, mid, q3, end */
visitor_ip  VARCHAR(45)
created_at  DATETIME DEFAULT CURRENT_TIMESTAMP

INDEX idx_ad_id (ad_id)
INDEX idx_event (event_type)
INDEX idx_created (created_at)

wp_oads_submissions

SQLid              BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY
name            VARCHAR(200)
email           VARCHAR(200)
company         VARCHAR(200)
website         VARCHAR(500)
ad_type         VARCHAR(50)
section         VARCHAR(100)
headline        VARCHAR(300)
body            TEXT
destination_url VARCHAR(500)
image_url       VARCHAR(500)
budget          DECIMAL(10,2)
preferred_start DATE
notes           TEXT
status          VARCHAR(20) DEFAULT 'pending'
post_id         BIGINT UNSIGNED DEFAULT 0
reject_reason   TEXT
created_at      DATETIME DEFAULT CURRENT_TIMESTAMP

INDEX idx_email (email)
INDEX idx_status (status)
INDEX idx_created (created_at)

wp_oads_plans

SQLid              BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY
name            VARCHAR(200)
description     TEXT
price           DECIMAL(10,2)
impressions     BIGINT UNSIGNED
duration_days   INT UNSIGNED DEFAULT 30
ad_types        VARCHAR(200)
sections        VARCHAR(200)
features        TEXT
cta_label       VARCHAR(100) DEFAULT 'Get Started'
cta_url         VARCHAR(500)
wc_product_id   BIGINT UNSIGNED DEFAULT 0
is_featured     TINYINT(1) DEFAULT 0
active          TINYINT(1) DEFAULT 1
created_at      DATETIME DEFAULT CURRENT_TIMESTAMP

OAds_CPT

PHP// Get active ads for a section
OAds_CPT::get_ads( string $section, int $limit, string $placement, array $ctx ): array

// Get all meta for an ad
OAds_CPT::get_ad_data( int $ad_id ): array

// Targeting check: returns false if ad should not be shown
OAds_CPT::passes_targeting( int $ad_id, array $ctx ): bool

OAds_Display

PHPOAds_Display::get_ads_html( string $section, int $count ): string
OAds_Display::get_inline_ads_html( string $section, int $count ): string
OAds_Display::render_ad( WP_Post $ad, string $section, string $format ): string
OAds_Display::detect_section(): string

OAds_Tracker

PHPOAds_Tracker::record_impression( int $ad_id, string $page_url, string $section ): void
OAds_Tracker::record_click( int $ad_id ): void

// Per-ad stats: returns [ impressions, clicks, ctr, revenue ]
OAds_Tracker::get_ad_stats( int $ad_id, string $period ): array

// Overview stats for all ads
OAds_Tracker::get_overview_stats( string $period ): array

// Raw log entries
OAds_Tracker::get_recent_log( int $limit, string $type ): array

// CSV export (exits)
OAds_Tracker::export_csv( string $type, string $period ): never

OAds_Zones

PHPOAds_Zones::get_all(): array
OAds_Zones::get_by_id( int $id ): ?object
OAds_Zones::get_by_slug( string $slug ): ?object
OAds_Zones::save( array $data ): int|false
OAds_Zones::delete( int $id ): bool

OAds_Groups

PHPOAds_Groups::get_all(): array
OAds_Groups::get_by_id( int $id ): ?object
OAds_Groups::get_ads_in_group( int $group_id ): array
OAds_Groups::pick_ad( int $group_id ): ?WP_Post
OAds_Groups::maybe_pick_winner( int $group_id ): void
OAds_Groups::save( array $data ): int|false
OAds_Groups::delete( int $id ): bool

Actions

Filters

Endpoints

Period values: 1d, 7d, 30d, 90d, all.

Auth example

SHcurl -H "Authorization: Bearer ${OADS_API_KEY}" \
  https://your-site.com/wp-json/oads/v1/stats?period=7d