WB Ad Manager provides a comprehensive set of WordPress actions and filters that let you customize nearly every aspect of the plugin’s behavior. Use these hooks to integrate with third-party services, modify ad display logic, or extend functionality without editing plugin files.
All hooks follow the wbam_ prefix convention and are documented with their parameters, types, and the version they were introduced.
Actions
Ad Lifecycle
/**
* Fires when an ad impression is recorded.
*
* @since 2.3.0
* @param int $ad_id Ad post ID.
* @param string $placement Placement ID where ad was displayed.
*/
do_action( 'wbam_ad_impression', $ad_id, $placement );
/**
* Fires when an ad is clicked.
*
* @since 1.0.0
* @param int $ad_id Ad post ID.
* @param string $placement Placement ID.
*/
do_action( 'wbam_ad_clicked', $ad_id, $placement );
/**
* Fires after ad data is saved.
*
* @since 1.0.0
* @param int $post_id Ad post ID.
* @param array $ad_data Saved ad data.
*/
do_action( 'wbam_ad_saved', $post_id, $ad_data );
Email Capture
/**
* Fires before processing email capture submission.
*
* @since 2.2.0
* @param string $email Subscriber email.
* @param string $name Subscriber name.
* @param int $ad_id Ad ID.
* @param array $_POST Raw POST data.
*/
do_action( 'wbam_email_form_submission_before', $email, $name, $ad_id, $_POST );
/**
* Fires when an email is captured (integrate with email services here).
*
* @since 2.2.0
* @param string $email Subscriber email.
* @param string $name Subscriber name.
* @param int $ad_id Ad ID.
*/
do_action( 'wbam_email_captured', $email, $name, $ad_id );
/**
* Fires after successful email capture submission.
*
* @since 2.2.0
* @param string $email Subscriber email.
* @param string $name Subscriber name.
* @param int $ad_id Ad ID.
*/
do_action( 'wbam_email_form_submission_after', $email, $name, $ad_id );
Link Partnerships
/**
* Fires when a partnership inquiry is submitted.
*
* @since 2.3.0
* @param int $partnership_id Partnership record ID.
* @param array $data Submitted data.
*/
do_action( 'wbam_partnership_submitted', $partnership_id, $data );
/**
* Fires when partnership status changes.
*
* @since 2.3.0
* @param int $partnership_id Partnership ID.
* @param string $new_status New status.
* @param string $old_status Previous status.
*/
do_action( 'wbam_partnership_status_changed', $partnership_id, $new_status, $old_status );
/**
* Fires when a partnership inquiry is submitted (after form processing).
*
* @since 2.3.0
* @param object $partnership Partnership object.
* @param array $data Submitted data.
*/
do_action( 'wbam_partnership_form_submission_after', $partnership, $data );
/**
* Fires when partnership is created.
*
* @since 2.3.0
* @param object $partnership Partnership object.
*/
do_action( 'wbam_partnership_created', $partnership );
/**
* Fires when partnership is accepted.
*
* @since 2.3.0
* @param object $partnership Partnership object.
*/
do_action( 'wbam_partnership_accepted', $partnership );
/**
* Fires when partnership is rejected.
*
* @since 2.3.0
* @param object $partnership Partnership object.
*/
do_action( 'wbam_partnership_rejected', $partnership );
Links
/**
* Fires when a link is clicked.
*
* @since 2.0.0
* @param int $link_id Link ID.
*/
do_action( 'wbam_link_clicked', $link_id );
/**
* Fires before link redirect.
*
* @since 2.3.0
* @param object $link Link object.
* @param string $destination Destination URL.
*/
do_action( 'wbam_before_link_redirect', $link, $destination );
/**
* Fires when a link is created.
*
* @since 2.3.0
* @param int $link_id Link ID.
* @param array $data Link data.
*/
do_action( 'wbam_link_created', $link_id, $data );
/**
* Fires when a link is updated.
*
* @since 2.3.0
* @param int $link_id Link ID.
* @param array $data Link data.
*/
do_action( 'wbam_link_updated', $link_id, $data );
/**
* Fires when a link is deleted.
*
* @since 2.3.0
* @param int $link_id Link ID.
*/
do_action( 'wbam_link_deleted', $link_id );
System
/**
* Fires after placements are initialized.
*
* @since 1.0.0
* @param Placement_Engine $engine Placement engine instance.
*/
do_action( 'wbam_placements_init', $engine );
/**
* Fires during ad type registration.
*
* @since 1.0.0
* @param Placement_Engine $engine Placement engine instance.
*/
do_action( 'wbam_register_ad_types', $engine );
/**
* Fires during placement registration.
*
* @since 1.0.0
* @param Placement_Engine $engine Placement engine instance.
*/
do_action( 'wbam_register_placements', $engine );
Filters
Ad Display
/**
* Filter whether an ad should be displayed.
*
* @since 1.0.0
* @param bool $should_display Whether to display the ad.
* @param int $ad_id Ad post ID.
*/
$should_display = apply_filters( 'wbam_should_display_ad', $should_display, $ad_id );
/**
* Filter display rules before evaluation.
*
* @since 2.3.0
* @param array $rules Display rules array.
* @param int $ad_id Ad post ID.
*/
$rules = apply_filters( 'wbam_ad_display_rules', $rules, $ad_id );
/**
* Filter ads returned for a placement.
*
* @since 2.3.0
* @param array $ad_ids Array of ad IDs that passed targeting.
* @param string $placement_id Placement ID.
* @param array $original_ids Original array before targeting.
*/
$ad_ids = apply_filters( 'wbam_ads_for_placement', $ad_ids, $placement_id, $original_ids );
/**
* Filter the final ad output HTML.
*
* @since 1.0.0
* @param string $output Ad output HTML.
* @param int $ad_id Ad post ID.
* @param string $placement Placement ID.
*/
$output = apply_filters( 'wbam_ad_output', $output, $ad_id, $placement );
Ad Data
/**
* Filter ad data before saving.
*
* @since 2.3.0
* @param array $ad_data Ad data array.
* @param int $post_id Ad post ID.
*/
$ad_data = apply_filters( 'wbam_ad_data_before_save', $ad_data, $post_id );
/**
* Filter ad data after retrieval.
*
* @since 1.0.0
* @param array $ad_data Ad data array.
* @param int $ad_id Ad post ID.
*/
$ad_data = apply_filters( 'wbam_ad_data', $ad_data, $ad_id );
Email Capture
/**
* Filter email capture form validation.
*
* Return WP_Error to fail validation.
*
* @since 2.2.0
* @param true|WP_Error $valid True if valid, WP_Error to fail.
* @param string $email Subscriber email.
* @param string $name Subscriber name.
* @param int $ad_id Ad ID.
* @param array $_POST Raw POST data.
*/
$valid = apply_filters( 'wbam_email_form_validation', true, $email, $name, $ad_id, $_POST );
/**
* Filter the email capture success message.
*
* @since 2.2.0
* @param string $message Success message.
* @param string $email Subscriber email.
* @param int $ad_id Ad ID.
*/
$message = apply_filters( 'wbam_email_capture_success_message', $message, $email, $ad_id );
Links
/**
* Filter link output HTML.
*
* @since 2.0.0
* @param string $html Link HTML.
* @param array $link Link data.
* @param array $options Rendering options.
*/
$html = apply_filters( 'wbam_link_output', $html, $link, $options );
/**
* Filter link redirect URL.
*
* @since 2.0.0
* @param string $url Destination URL.
* @param int $link_id Link post ID.
*/
$url = apply_filters( 'wbam_link_redirect_url', $url, $link_id );
/**
* Filter link redirect type (301, 302, etc).
*
* @since 2.3.0
* @param string $type Redirect type.
* @param object $link Link object.
*/
$type = apply_filters( 'wbam_link_redirect_type', $type, $link );
/**
* Filter link data before saving.
*
* @since 2.3.0
* @param array $data Link data.
* @param int $link_id Link ID.
* @param array $_POST Raw POST data.
*/
$data = apply_filters( 'wbam_link_save_data', $data, $link_id, $_POST );
Link Partnerships
/**
* Filter partnership form data before saving.
*
* @since 2.3.0
* @param array $data Partnership data.
* @param array $_POST Raw POST data.
*/
$data = apply_filters( 'wbam_partnership_form_data', $data, $_POST );
/**
* Filter partnership form validation.
*
* @since 2.3.0
* @param bool $valid Validation result.
* @param array $data Partnership data.
* @param array $_POST Raw POST data.
*/
$valid = apply_filters( 'wbam_partnership_form_validation', true, $data, $_POST );
/**
* Filter partnership types available in form.
*
* @since 2.3.0
* @param array $types Array of partnership types.
*/
$types = apply_filters( 'wbam_partnership_form_types', $types );
/**
* Filter whether to send admin notification.
*
* @since 2.3.0
* @param bool $send Whether to send.
* @param object $partnership Partnership object.
*/
$send = apply_filters( 'wbam_send_partnership_admin_notification', true, $partnership );
Code Examples
Integrate Email Capture with Mailchimp
add_action( 'wbam_email_captured', function( $email, $name, $ad_id ) {
$api_key = 'your-mailchimp-api-key';
$list_id = 'your-list-id';
$data = array(
'email_address' => $email,
'status' => 'subscribed',
'merge_fields' => array(
'FNAME' => $name,
),
);
$response = wp_remote_post(
"https://usX.api.mailchimp.com/3.0/lists/{$list_id}/members",
array(
'headers' => array(
'Authorization' => 'Basic ' . base64_encode( 'anystring:' . $api_key ),
'Content-Type' => 'application/json',
),
'body' => wp_json_encode( $data ),
)
);
}, 10, 3 );
Custom Validation for Email Capture
add_filter( 'wbam_email_form_validation', function( $valid, $email, $name, $ad_id, $post_data ) {
// Block disposable email domains
$blocked_domains = array( 'tempmail.com', 'throwaway.com' );
$email_domain = substr( strrchr( $email, '@' ), 1 );
if ( in_array( $email_domain, $blocked_domains, true ) ) {
return new WP_Error( 'blocked_domain', __( 'Please use a valid email address.', 'my-plugin' ) );
}
return $valid;
}, 10, 5 );
Exclude Ads for Specific Users
add_filter( 'wbam_should_display_ad', function( $should_display, $ad_id ) {
// Don't show ads to users with premium role
if ( is_user_logged_in() && current_user_can( 'premium_member' ) ) {
return false;
}
return $should_display;
}, 10, 2 );
Modify Ads for Specific Placement
add_filter( 'wbam_ads_for_placement', function( $ad_ids, $placement_id, $original_ids ) {
// Limit sidebar to max 2 ads
if ( 'sidebar' === $placement_id && count( $ad_ids ) > 2 ) {
return array_slice( $ad_ids, 0, 2 );
}
return $ad_ids;
}, 10, 3 );
Add Custom Field to Ad Data
// Add field to admin form
add_action( 'wbam_ad_settings_after', function( $ad_id ) {
$data = get_post_meta( $ad_id, '_wbam_ad_data', true );
$sponsor = isset( $data['sponsor'] ) ? $data['sponsor'] : '';
?>
<p>
<label for="wbam_sponsor"><?php esc_html_e( 'Sponsor Name', 'my-plugin' ); ?></label>
<input type="text" id="wbam_sponsor" name="wbam_ad_data[sponsor]"
value="<?php echo esc_attr( $sponsor ); ?>" class="widefat">
</p>
<?php
} );
// Modify output to include sponsor
add_filter( 'wbam_ad_output', function( $output, $ad_id, $placement ) {
$data = get_post_meta( $ad_id, '_wbam_ad_data', true );
if ( ! empty( $data['sponsor'] ) ) {
$sponsor_html = sprintf(
'<div class="wbam-sponsor">%s %s</div>',
esc_html__( 'Sponsored by', 'my-plugin' ),
esc_html( $data['sponsor'] )
);
$output = $sponsor_html . $output;
}
return $output;
}, 10, 3 );
Log All Ad Clicks to External Service
add_action( 'wbam_ad_clicked', function( $ad_id, $placement ) {
$post = get_post( $ad_id );
wp_remote_post( 'https://your-analytics-service.com/track', array(
'body' => array(
'event' => 'ad_click',
'ad_id' => $ad_id,
'ad_title' => $post->post_title,
'placement' => $placement,
'timestamp' => current_time( 'mysql' ),
'url' => isset( $_SERVER['HTTP_REFERER'] ) ? $_SERVER['HTTP_REFERER'] : '',
),
'blocking' => false, // Non-blocking request
) );
}, 10, 2 );