OAds v2.0.0

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

Shortcode

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

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 — 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
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

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