Database Schema

Get Started

WB Ad Manager uses a combination of custom database tables and WordPress post meta to store ad data, analytics events, email submissions, managed links, link partnerships, and rate limiting data. This reference documents every table, column, index, and post meta key used by the plugin.

Understanding the database schema is essential if you need to write custom queries, build reporting tools, or integrate with external analytics systems.

Custom Tables

wbam_analytics

Stores impression and click tracking events. Each row represents a single event (one impression or one click) with visitor information including device, location, and referrer data.

CREATE TABLE {prefix}wbam_analytics (
    id bigint(20) UNSIGNED NOT NULL AUTO_INCREMENT,
    ad_id bigint(20) UNSIGNED NOT NULL,
    campaign_id bigint(20) UNSIGNED DEFAULT NULL,
    event_type varchar(20) NOT NULL,
    user_id bigint(20) UNSIGNED DEFAULT NULL,
    ip_hash varchar(64) DEFAULT NULL,
    country varchar(2) DEFAULT NULL,
    device_type varchar(20) DEFAULT NULL,
    browser varchar(50) DEFAULT NULL,
    referrer varchar(2000) DEFAULT NULL,
    placement varchar(100) DEFAULT NULL,
    page_url varchar(2000) DEFAULT NULL,
    visitor_hash varchar(64) DEFAULT NULL,
    ip_address varchar(45) DEFAULT NULL,
    user_agent text,
    referer varchar(2000) DEFAULT NULL,
    created_at datetime DEFAULT CURRENT_TIMESTAMP,
    PRIMARY KEY (id),
    KEY ad_id (ad_id),
    KEY campaign_id (campaign_id),
    KEY event_type (event_type),
    KEY created_at (created_at),
    KEY ad_event (ad_id, event_type)
);

Column Details:

Column Type Description
id bigint(20) Auto-incrementing primary key.
ad_id bigint(20) References the ad post ID from wp_posts.
campaign_id bigint(20) Associated campaign ID (nullable).
event_type varchar(20) Event type: 'impression' or 'click'.
user_id bigint(20) WordPress user ID of the visitor, if logged in.
ip_hash varchar(64) Hashed IP address for anonymized tracking.
country varchar(2) Two-letter ISO country code derived from IP geolocation.
device_type varchar(20) Device category (e.g., 'desktop', 'mobile', 'tablet').
browser varchar(50) Browser name (e.g., 'Chrome', 'Firefox', 'Safari').
referrer varchar(2000) HTTP referrer URL (parsed).
placement varchar(100) Placement ID where the ad was displayed.
page_url varchar(2000) Full URL of the page where the event occurred.
visitor_hash varchar(64) SHA-256 hash for anonymized visitor identification.
ip_address varchar(45) Visitor IP address (supports IPv6).
user_agent text Browser user agent string.
referer varchar(2000) Raw HTTP referer header value.
created_at datetime Timestamp when the event occurred.

wbam_email_submissions

Stores email capture form submissions from email capture ad types.

CREATE TABLE {prefix}wbam_email_submissions (
    id bigint(20) UNSIGNED NOT NULL AUTO_INCREMENT,
    ad_id bigint(20) UNSIGNED NOT NULL,
    email varchar(255) NOT NULL,
    name varchar(200) DEFAULT '',
    ip_address varchar(45) DEFAULT '',
    created_at datetime DEFAULT CURRENT_TIMESTAMP,
    PRIMARY KEY (id),
    KEY ad_id (ad_id),
    KEY email (email)
);

Column Details:

Column Type Description
id bigint(20) Auto-incrementing primary key.
ad_id bigint(20) References the ad post ID that captured the email.
email varchar(255) Subscriber email address.
name varchar(200) Subscriber name (optional).
ip_address varchar(45) Submitter’s IP address.
created_at datetime Timestamp of submission.

Stores managed links for affiliate tracking, link cloaking, and partnership monetization. Each row represents a single link with its configuration, redirect settings, and revenue tracking data.

CREATE TABLE {prefix}wbam_links (
    id bigint(20) UNSIGNED NOT NULL AUTO_INCREMENT,
    name varchar(255) NOT NULL,
    destination_url text NOT NULL,
    slug varchar(100) DEFAULT NULL,
    link_type varchar(20) DEFAULT 'affiliate',
    cloaking_enabled tinyint(1) DEFAULT 1,
    nofollow tinyint(1) DEFAULT 1,
    sponsored tinyint(1) DEFAULT 0,
    new_tab tinyint(1) DEFAULT 1,
    category_id bigint(20) UNSIGNED DEFAULT 0,
    description text,
    parameters text,
    redirect_type int(3) DEFAULT 307,
    click_count bigint(20) UNSIGNED DEFAULT 0,
    status varchar(20) DEFAULT 'active',
    expires_at datetime DEFAULT NULL,
    payment_amount decimal(10,2) DEFAULT 0.00,
    payment_type varchar(20) DEFAULT 'one_time',
    payment_currency varchar(3) DEFAULT 'USD',
    payment_status varchar(20) DEFAULT 'unpaid',
    commission_rate decimal(5,2) DEFAULT 0.00,
    total_revenue decimal(10,2) DEFAULT 0.00,
    created_by bigint(20) UNSIGNED DEFAULT 0,
    created_at datetime DEFAULT CURRENT_TIMESTAMP,
    updated_at datetime DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    PRIMARY KEY (id),
    UNIQUE KEY slug (slug),
    KEY status (status),
    KEY link_type (link_type),
    KEY category_id (category_id),
    KEY payment_status (payment_status)
);

Column Details:

Column Type Description
id bigint(20) Auto-incrementing primary key.
name varchar(255) Display name for the link.
destination_url text Target URL the link redirects to.
slug varchar(100) URL-safe slug used in cloaked link paths (unique).
link_type varchar(20) Link category: 'affiliate', 'sponsored', 'internal', etc.
cloaking_enabled tinyint(1) Whether URL cloaking is active (1 = yes, 0 = no).
nofollow tinyint(1) Whether to add rel="nofollow" (1 = yes).
sponsored tinyint(1) Whether to add rel="sponsored" (1 = yes).
new_tab tinyint(1) Whether to open the link in a new tab (1 = yes).
category_id bigint(20) References wbam_link_categories.id for grouping.
description text Internal description or notes about the link.
parameters text Serialized URL parameters to append to the destination.
redirect_type int(3) HTTP redirect status code (default: 307 Temporary Redirect).
click_count bigint(20) Cached total number of clicks on this link.
status varchar(20) Link status: 'active', 'inactive', 'expired'.
expires_at datetime Optional expiration date after which the link becomes inactive.
payment_amount decimal(10,2) Payment amount associated with this link.
payment_type varchar(20) Payment model: 'one_time', 'recurring', etc.
payment_currency varchar(3) Three-letter ISO currency code (default: 'USD').
payment_status varchar(20) Payment status: 'unpaid', 'paid', 'pending'.
commission_rate decimal(5,2) Commission percentage for affiliate links.
total_revenue decimal(10,2) Cumulative revenue generated by this link.
created_by bigint(20) WordPress user ID of the link creator.
created_at datetime Timestamp when the link was created.
updated_at datetime Timestamp of the last update (auto-updated).

Stores hierarchical categories for organizing managed links.

CREATE TABLE {prefix}wbam_link_categories (
    id bigint(20) UNSIGNED NOT NULL AUTO_INCREMENT,
    name varchar(100) NOT NULL,
    slug varchar(100) NOT NULL,
    description text,
    parent_id bigint(20) UNSIGNED DEFAULT 0,
    count int(11) DEFAULT 0,
    created_at datetime DEFAULT CURRENT_TIMESTAMP,
    PRIMARY KEY (id),
    UNIQUE KEY slug (slug),
    KEY parent_id (parent_id)
);

Column Details:

Column Type Description
id bigint(20) Auto-incrementing primary key.
name varchar(100) Category display name.
slug varchar(100) URL-safe category slug (unique).
description text Optional category description.
parent_id bigint(20) Parent category ID for nesting (0 = top-level).
count int(11) Cached count of links in this category.
created_at datetime Timestamp when the category was created.

Stores basic click tracking events for managed links (free version). Each row represents a single click on a managed link.

CREATE TABLE {prefix}wbam_link_clicks (
    id bigint(20) UNSIGNED NOT NULL AUTO_INCREMENT,
    link_id bigint(20) UNSIGNED NOT NULL,
    clicked_at datetime DEFAULT CURRENT_TIMESTAMP,
    PRIMARY KEY (id),
    KEY link_id (link_id),
    KEY clicked_at (clicked_at)
);

Column Details:

Column Type Description
id bigint(20) Auto-incrementing primary key.
link_id bigint(20) References wbam_links.id for the clicked link.
clicked_at datetime Timestamp when the click occurred.

Stores link partnership inquiries submitted through the partnership form.

CREATE TABLE {prefix}wbam_link_partnerships (
    id bigint(20) UNSIGNED NOT NULL AUTO_INCREMENT,
    name varchar(255) NOT NULL,
    email varchar(255) NOT NULL,
    website_url varchar(2000) NOT NULL,
    partnership_type varchar(30) NOT NULL DEFAULT 'paid_link',
    target_post_id bigint(20) UNSIGNED DEFAULT NULL,
    anchor_text varchar(255) DEFAULT NULL,
    message text,
    budget_min decimal(10,2) DEFAULT NULL,
    budget_max decimal(10,2) DEFAULT NULL,
    status varchar(20) DEFAULT 'pending',
    admin_notes text,
    ip_address varchar(45) DEFAULT NULL,
    created_at datetime DEFAULT CURRENT_TIMESTAMP,
    responded_at datetime DEFAULT NULL,
    PRIMARY KEY (id),
    KEY status (status),
    KEY partnership_type (partnership_type),
    KEY email (email),
    KEY created_at (created_at)
);

Column Details:

Column Type Description
id bigint(20) Auto-incrementing primary key.
name varchar(255) Contact name of the partnership applicant.
email varchar(255) Contact email address.
website_url varchar(2000) Applicant’s website URL.
partnership_type varchar(30) Type of partnership (default: 'paid_link').
target_post_id bigint(20) WordPress post ID the partnership targets (if applicable).
anchor_text varchar(255) Requested anchor text for the link.
message text Free-form message from the applicant.
budget_min decimal(10,2) Minimum budget offered.
budget_max decimal(10,2) Maximum budget offered.
status varchar(20) Partnership status: 'pending', 'accepted', 'rejected'.
admin_notes text Internal notes added by administrators.
ip_address varchar(45) Submitter’s IP address.
created_at datetime Timestamp of submission.
responded_at datetime Timestamp when admin responded (accepted/rejected).

wbam_rate_limits

Stores atomic rate limiting counters for throttling operations such as form submissions and API requests. Entries expire automatically and are cleaned up periodically.

CREATE TABLE {prefix}wbam_rate_limits (
    id bigint(20) UNSIGNED NOT NULL AUTO_INCREMENT,
    `key` varchar(255) NOT NULL,
    `count` int(11) NOT NULL DEFAULT 0,
    expires bigint(20) UNSIGNED NOT NULL,
    PRIMARY KEY (id),
    UNIQUE KEY `key` (`key`),
    KEY expires (expires)
);

Column Details:

Column Type Description
id bigint(20) Auto-incrementing primary key.
key varchar(255) Unique identifier for the rate limit bucket (e.g., IP + action).
count int(11) Current number of requests within the time window.
expires bigint(20) Unix timestamp when this rate limit entry expires.

Post Meta Keys

Ad configuration is stored as WordPress post meta on the wbam_ad custom post type. These are the meta keys used by the plugin:

Meta Key Type Description
_wbam_enabled int Ad enabled status (1 = enabled, 0 = disabled).
_wbam_ad_data array (serialized) Ad type-specific data (image URL, HTML content, AdSense code, etc.).
_wbam_placements array (serialized) Array of placement IDs where this ad should display.
_wbam_schedule array (serialized) Schedule settings (start date, end date, days of week, time ranges).
_wbam_display_rules array (serialized) Display rules for page-level targeting (include/exclude specific pages, categories, etc.).
_wbam_visitor_conditions array (serialized) Visitor-level conditions (device type, logged-in status, user roles, geo-location, etc.).

Table Prefix

All custom tables use the WordPress database table prefix (typically wp_). The actual table names are:

  • wp_wbam_analytics
  • wp_wbam_email_submissions
  • wp_wbam_links
  • wp_wbam_link_categories
  • wp_wbam_link_clicks
  • wp_wbam_link_partnerships
  • wp_wbam_rate_limits

The prefix is determined by the $wpdb->prefix property and may differ in multisite installations or custom configurations.

Database Versioning

The plugin tracks its database schema version internally and runs migrations automatically on plugin update. Table creation and alterations are handled by the Installer class using WordPress’s dbDelta() function.

Last updated: March 4, 2026