We have built some custom actions into AdSanity to help developers like yourself extend the default behaviors. Below is a list of actions that we include in the plugin and its add-ons. Custom code can be placed in your theme’s functions.php file or in a custom plugin. The examples use a myprefix_ prefix and myprefix text domain, so swap those for your own. Looking for filters? Check out Avançado: Filtros.
Quick Reference
- Ad Display: adsanity_before_ad_wrapper, adsanity_before_ad, adsanity_after_ad, adsanity_after_ad_wrapper
- Click Tracking: adsanity_before_track_click, adsanity_before_redirect
- Post Type: ads_init
- Settings & Admin Screens: adsanity_register_settings, adsanity_automatic_inclusion_after_fields, adsanity_about_screen, adsanity_changelog_screen, adsanity_support_screen, adsanity_elementor_register_widgets
- Reports: adsanity_after_reports_page_heading, adsanity_before_stats_dashboard, adsanity_after_stats_columns, adsanity_group_block_table_header, adsanity_custom_stats_before_ad_selection, adsanity_custom_reports_table_heading, adsanity_custom_reports_table_total
- Ad Meta Data: adsanity_pre_update_meta, adsanity_pre_update_meta_{$meta_key}, adsanity_after_update_meta, adsanity_after_update_meta_{$meta_key}, adsanity_pre_delete_meta, adsanity_pre_delete_meta_{$meta_key}, adsanity_after_delete_meta, adsanity_after_delete_meta_{$meta_key}
- Advertiser Reporting Add-on: adsanity_ar_placeholder_text
- Rotating Ad Widget Add-on: adsanity_raw_iframe_head, adsanity_raw_iframe_footer
Ad Display
These fire every time an ad unit is rendered, whether it came from a widget, block, shortcode, or template tag.
# adsanity_before_ad_wrapper
Fires right before the ad’s wrapper <div> is output. Anything you echo here lands outside the ad unit.
Parameters
WP_Post$ad: The ad being displayed.int$ad_id: The ad ID.
Example
/**
* Adds an "Advertisement" label above every ad.
*/
function myprefix_ad_label() {
echo '<p class="ad-label">Advertisement</p>';
}
add_action( 'adsanity_before_ad_wrapper', 'myprefix_ad_label' );# adsanity_before_ad
Fires inside the wrapper, right before the ad itself. The Google Analytics Tracking add-on uses this to open its tracking container.
Parameters
WP_Post$ad: The ad being displayed.int$ad_id: The ad ID.
Example
/**
* Shows the ad's title above the ad.
*
* @param WP_Post $ad The ad being displayed.
* @param int $ad_id The ad ID.
*/
function myprefix_ad_title( $ad, $ad_id ) {
printf( '<span class="ad-title">%s</span>', esc_html( get_the_title( $ad_id ) ) );
}
add_action( 'adsanity_before_ad', 'myprefix_ad_title', 10, 2 );# adsanity_after_ad
Fires inside the wrapper, right after the ad itself.
Parameters
WP_Post$ad: The ad being displayed.int$ad_id: The ad ID.
Example
/**
* Adds a "Sponsored" note below the ad.
*/
function myprefix_ad_disclosure() {
echo '<small class="ad-disclosure">Sponsored</small>';
}
add_action( 'adsanity_after_ad', 'myprefix_ad_disclosure' );# adsanity_after_ad_wrapper
Fires right after the ad’s wrapper <div> is closed.
Parameters
WP_Post$ad: The ad being displayed.int$ad_id: The ad ID.
Example
/**
* Adds an "Advertise with us" link after every ad.
*/
function myprefix_ad_cta() {
printf(
'<p class="ad-cta"><a href="%s">Advertise with us</a></p>',
esc_url( home_url( '/advertise/' ) )
);
}
add_action( 'adsanity_after_ad_wrapper', 'myprefix_ad_cta' );Click Tracking
When someone clicks an ad, they pass through the ad’s tracking URL before being sent on to the destination. These fire during that trip.
# adsanity_before_track_click
Fires before the click is counted.
Parameters
WP_Post$post: The ad that was clicked.
Example
/**
* Keeps a running ad click count for each logged in user.
*/
function myprefix_count_user_clicks() {
if ( ! is_user_logged_in() ) {
return;
}
$user_id = get_current_user_id();
$clicks = (int) get_user_meta( $user_id, 'myprefix_ad_clicks', true );
update_user_meta( $user_id, 'myprefix_ad_clicks', $clicks + 1 );
}
add_action( 'adsanity_before_track_click', 'myprefix_count_user_clicks' );# adsanity_before_redirect
Fires after the click is counted, right before the visitor is redirected to the ad’s URL.
Parameters
WP_Post$post: The ad that was clicked.
Example
/**
* Saves the time an ad was last clicked.
*
* @param WP_Post $post The ad that was clicked.
*/
function myprefix_last_clicked( $post ) {
update_post_meta( $post->ID, 'myprefix_last_clicked', current_time( 'mysql' ) );
}
add_action( 'adsanity_before_redirect', 'myprefix_last_clicked' );Post Type
# ads_init
Fires right after the ads post type is registered on init. AdSanity registers the ad-group taxonomy here, so it’s a good spot to register your own taxonomies for ads too.
Parameters: none
Example
/**
* Registers an Advertisers taxonomy for ads.
*/
function myprefix_register_advertisers() {
register_taxonomy(
'advertiser',
'ads',
array(
'label' => __( 'Advertisers', 'myprefix' ),
'hierarchical' => true,
'show_in_rest' => true,
)
);
}
add_action( 'ads_init', 'myprefix_register_advertisers' );Settings & Admin Screens
# adsanity_register_settings
Fires after AdSanity registers its own settings sections and fields on admin_init. Use it to register additional settings with the Settings API.
Parameters: none
Example
/**
* Registers the settings for a custom add-on tab.
*/
function myprefix_register_settings() {
register_setting(
'adsanity-my-addon-options',
'myprefix_options',
array( 'sanitize_callback' => 'myprefix_sanitize_options' )
);
add_settings_section(
'myprefix_section',
__( 'My Add-on', 'myprefix' ),
'__return_false',
'adsanity-my-addon-options'
);
add_settings_field(
'myprefix_label',
__( 'Ad Label', 'myprefix' ),
'myprefix_label_field',
'adsanity-my-addon-options',
'myprefix_section'
);
}
add_action( 'adsanity_register_settings', 'myprefix_register_settings' );
/**
* Renders the Ad Label field.
*/
function myprefix_label_field() {
$options = get_option( 'myprefix_options', array() );
printf(
'<input type="text" name="myprefix_options[label]" value="%s">',
esc_attr( $options['label'] ?? '' )
);
}
/**
* Sanitizes the add-on settings.
*
* @param array $options The submitted settings.
* @return array
*/
function myprefix_sanitize_options( $options ) {
return array(
'label' => sanitize_text_field( $options['label'] ?? '' ),
);
}# adsanity_automatic_inclusion_after_fields
Fires after the fields for each Automatic Inclusion rule, before the rule’s buttons. Use it to add your own fields to a rule, then save them with the adsanity_save_admin_options filter.
Parameters
int$key: The index of the rule.array$rule: The rule’s saved settings.
Example
/**
* Adds a Heading field to each Automatic Inclusion rule.
*
* @param int $key The index of the rule.
* @param array $rule The rule's saved settings.
*/
function myprefix_rule_heading_field( $key, $rule ) {
printf(
'<label>%s <input type="text" name="adsanity-options[adsanity_in_content_rules][%d][myprefix_heading]" value="%s"></label>',
esc_html__( 'Heading', 'myprefix' ),
intval( $key ),
esc_attr( $rule['myprefix_heading'] ?? '' )
);
}
add_action( 'adsanity_automatic_inclusion_after_fields', 'myprefix_rule_heading_field', 10, 2 );# adsanity_about_screen
Fires near the bottom of the AdSanity About screen, before the footer links.
Parameters: none
Example
/**
* Adds an ad policy card to the About screen.
*/
function myprefix_about_card() {
printf(
'<section class="card"><h2>%s</h2><p>%s</p></section>',
esc_html__( 'Our Ad Policy', 'myprefix' ),
esc_html__( 'All ads are reviewed before they go live.', 'myprefix' )
);
}
add_action( 'adsanity_about_screen', 'myprefix_about_card' );# adsanity_changelog_screen
Fires near the bottom of the AdSanity Changelog screen. Our add-ons use this to show their own release notes.
Parameters: none
Example
/**
* Adds release notes to the Changelog screen.
*/
function myprefix_changelog_card() {
printf(
'<section class="card"><h2>%s</h2><p>%s</p></section>',
esc_html__( 'My Add-on 1.1', 'myprefix' ),
esc_html__( 'Added an ad label setting.', 'myprefix' )
);
}
add_action( 'adsanity_changelog_screen', 'myprefix_changelog_card' );# adsanity_support_screen
Fires at the bottom of the AdSanity Support screen.
Parameters: none
Example
/**
* Adds a contact email to the Support screen.
*/
function myprefix_support_contact() {
$email = get_option( 'admin_email' );
printf(
'<p>%s <a href="%s">%s</a></p>',
esc_html__( 'Need help with ads on this site? Email', 'myprefix' ),
esc_url( 'mailto:' . $email ),
esc_html( $email )
);
}
add_action( 'adsanity_support_screen', 'myprefix_support_contact' );# adsanity_elementor_register_widgets
Fires after AdSanity registers its Elementor widgets. Use it to register your own widgets alongside ours.
Parameters
\Elementor\Widgets_Manager$widgets_manager: Elementor’s widget manager.
Example
/**
* Registers a custom Elementor widget alongside AdSanity's.
*
* @param \Elementor\Widgets_Manager $widgets_manager Elementor's widget manager.
*/
function myprefix_register_elementor_widgets( $widgets_manager ) {
require_once __DIR__ . '/class-myprefix-ad-widget.php';
$widgets_manager->register( new Myprefix_Ad_Widget() );
}
add_action( 'adsanity_elementor_register_widgets', 'myprefix_register_elementor_widgets' );Relatórios
# adsanity_after_reports_page_heading
Fires right after the heading on the Reports screen, before the report tabs.
Parameters: none
Example
/**
* Adds a note under the Reports heading.
*/
function myprefix_reports_note() {
printf( '<p class="description">%s</p>', esc_html__( 'Stats are updated in real time.', 'myprefix' ) );
}
add_action( 'adsanity_after_reports_page_heading', 'myprefix_reports_note' );# adsanity_before_stats_dashboard
Fires at the top of the Reports dashboard tab, before the all-time summary.
Parameters: none
Example
/**
* Adds a notice to the top of the Reports dashboard.
*/
function myprefix_dashboard_notice() {
printf(
'<div class="notice notice-info inline"><p>%s</p></div>',
esc_html__( 'Reports reset at midnight in the site\'s timezone.', 'myprefix' )
);
}
add_action( 'adsanity_before_stats_dashboard', 'myprefix_dashboard_notice' );# adsanity_after_stats_columns
Fires at the bottom of the Reports dashboard tab, after all of the stats columns.
Parameters: none
Example
/**
* Shows the number of published ads below the dashboard stats.
*/
function myprefix_published_ad_count() {
$count = wp_count_posts( 'ads' );
printf(
'<p>%s %s</p>',
esc_html__( 'Published ads:', 'myprefix' ),
esc_html( number_format_i18n( $count->publish ) )
);
}
add_action( 'adsanity_after_stats_columns', 'myprefix_published_ad_count' );# adsanity_group_block_table_header
Fires at the end of the header and footer rows of the ad group stats table on the dashboard. Echo a <th> here to add a column. Since it fires twice, your callback runs once for each row.
Parameters: none
Example
/**
* Adds an Advertiser column heading to the ad group stats table.
*/
function myprefix_group_table_heading() {
printf( '<th>%s</th>', esc_html__( 'Advertiser', 'myprefix' ) );
}
add_action( 'adsanity_group_block_table_header', 'myprefix_group_table_heading' );# adsanity_custom_stats_before_ad_selection
Fires on the Custom Reports tab, right before the ad search field. The Advertiser Reporting add-on uses this to add an advertiser dropdown. It also fires on the Google Analytics Tracking reports screen when that add-on is active.
Parameters: none
Example
/**
* Adds a tip above the ad search field.
*/
function myprefix_custom_report_tip() {
printf(
'<p class="description">%s</p>',
esc_html__( 'Tip: pick up to 15 ads at a time.', 'myprefix' )
);
}
add_action( 'adsanity_custom_stats_before_ad_selection', 'myprefix_custom_report_tip' );# adsanity_custom_reports_table_heading
Fires at the end of the header and footer rows of the Custom Reports table. Echo a <th> here, then fill the matching cells with the adsanity_custom_report_table_cell filter.
Parameters: none
Example
/**
* Adds an Ad Size column heading to the Custom Reports table.
*/
function myprefix_custom_report_heading() {
printf( '<th>%s</th>', esc_html__( 'Ad Size', 'myprefix' ) );
}
add_action( 'adsanity_custom_reports_table_heading', 'myprefix_custom_report_heading' );# adsanity_custom_reports_table_total
Fires at the end of the totals row of the Custom Reports table. Echo a <th> here so your custom column lines up.
Parameters: none
Example
/**
* Keeps the totals row lined up with the extra Ad Size column.
*/
function myprefix_custom_report_total() {
echo '<th> </th>';
}
add_action( 'adsanity_custom_reports_table_total', 'myprefix_custom_report_total' );Ad Meta Data
AdSanity reads and writes ad data through its own meta data helper, and these fire along the way. They only fire for data saved through AdSanity, not for direct calls to update_post_meta(). The update actions also fire every time a view or click is counted, so check the meta key and bail early to keep your ads fast. The dynamic versions use the meta key exactly as it’s stored, so an ad’s size (_size) fires adsanity_pre_update_meta__size (note the double underscore).
# adsanity_pre_update_meta
Fires before any AdSanity meta value is saved.
Parameters
string$object_type: The object type, usuallypost.int$object_id: The object ID.string$meta_key: The meta key.mixed$meta_value: The value being saved or removed.mixed$prev_value: The previous value to replace, if one was given.
Example
/**
* Saves the time an ad's schedule last changed.
*
* This fires for every tracked view and click too, so bail early on keys you don't need.
*
* @param string $object_type The object type.
* @param int $object_id The object ID.
* @param string $meta_key The meta key.
*/
function myprefix_schedule_changed( $object_type, $object_id, $meta_key ) {
if ( ! in_array( $meta_key, array( '_start_date', '_end_date' ), true ) ) {
return;
}
update_post_meta( $object_id, 'myprefix_schedule_changed', current_time( 'mysql' ) );
}
add_action( 'adsanity_pre_update_meta', 'myprefix_schedule_changed', 10, 3 );# adsanity_pre_update_meta_{$meta_key}
Fires before a specific meta value is saved.
Parameters
string$object_type: The object type, usuallypost.int$object_id: The object ID.mixed$meta_value: The value being saved or removed.mixed$prev_value: The previous value to replace, if one was given.
Example
/**
* Keeps a copy of an ad's URL (_url) before it changes.
*
* @param string $object_type The object type.
* @param int $object_id The object ID.
*/
function myprefix_keep_previous_url( $object_type, $object_id ) {
update_post_meta( $object_id, 'myprefix_previous_url', get_post_meta( $object_id, '_url', true ) );
}
add_action( 'adsanity_pre_update_meta__url', 'myprefix_keep_previous_url', 10, 2 );# adsanity_after_update_meta
Fires after any AdSanity meta value is saved.
Parameters
string$object_type: The object type, usuallypost.int$object_id: The object ID.string$meta_key: The meta key.mixed$meta_value: The value being saved or removed.mixed$prev_value: The previous value to replace, if one was given.
Example
/**
* Clears a cached value when an ad's URL changes.
*
* This fires for every tracked view and click too, so bail early on keys you don't need.
*
* @param string $object_type The object type.
* @param int $object_id The object ID.
* @param string $meta_key The meta key.
*/
function myprefix_clear_link_cache( $object_type, $object_id, $meta_key ) {
if ( '_url' !== $meta_key ) {
return;
}
delete_transient( 'myprefix_ad_links_' . $object_id );
}
add_action( 'adsanity_after_update_meta', 'myprefix_clear_link_cache', 10, 3 );# adsanity_after_update_meta_{$meta_key}
Fires after a specific meta value is saved.
Parameters
string$object_type: The object type, usuallypost.int$object_id: The object ID.mixed$meta_value: The value being saved or removed.mixed$prev_value: The previous value to replace, if one was given.
Example
/**
* Emails the site admin when an ad's end date (_end_date) changes.
*
* @param string $object_type The object type.
* @param int $object_id The object ID.
*/
function myprefix_end_date_changed( $object_type, $object_id ) {
wp_mail(
get_option( 'admin_email' ),
__( 'Ad end date changed', 'myprefix' ),
/* translators: %s: Ad title. */
sprintf( __( 'The end date for "%s" was updated.', 'myprefix' ), get_the_title( $object_id ) )
);
}
add_action( 'adsanity_after_update_meta__end_date', 'myprefix_end_date_changed', 10, 2 );# adsanity_pre_delete_meta
Fires before any AdSanity meta value is deleted.
Parameters
string$object_type: The object type, usuallypost.int$object_id: The object ID.string$meta_key: The meta key.mixed$meta_value: The value being saved or removed.bool$delete_all: Whether matching meta is being deleted from every object.
Example
/**
* Keeps a copy of an ad's URL before it's deleted.
*
* @param string $object_type The object type.
* @param int $object_id The object ID.
* @param string $meta_key The meta key.
*/
function myprefix_before_url_deleted( $object_type, $object_id, $meta_key ) {
if ( '_url' !== $meta_key ) {
return;
}
update_post_meta( $object_id, 'myprefix_previous_url', get_post_meta( $object_id, '_url', true ) );
}
add_action( 'adsanity_pre_delete_meta', 'myprefix_before_url_deleted', 10, 3 );# adsanity_pre_delete_meta_{$meta_key}
Fires before a specific meta value is deleted.
Parameters
string$object_type: The object type, usuallypost.int$object_id: The object ID.mixed$meta_value: The value being saved or removed.bool$delete_all: Whether matching meta is being deleted from every object.
Example
/**
* Keeps a copy of an ad's URL (_url) before it's deleted.
*
* @param string $object_type The object type.
* @param int $object_id The object ID.
*/
function myprefix_before_url_meta_deleted( $object_type, $object_id ) {
update_post_meta( $object_id, 'myprefix_previous_url', get_post_meta( $object_id, '_url', true ) );
}
add_action( 'adsanity_pre_delete_meta__url', 'myprefix_before_url_meta_deleted', 10, 2 );# adsanity_after_delete_meta
Fires after any AdSanity meta value is deleted.
Parameters
string$object_type: The object type, usuallypost.int$object_id: The object ID.string$meta_key: The meta key.mixed$meta_value: The value being saved or removed.bool$delete_all: Whether matching meta is being deleted from every object.
Example
/**
* Clears a cached value when an ad's URL is deleted.
*
* @param string $object_type The object type.
* @param int $object_id The object ID.
* @param string $meta_key The meta key.
*/
function myprefix_after_url_deleted( $object_type, $object_id, $meta_key ) {
if ( '_url' !== $meta_key ) {
return;
}
delete_transient( 'myprefix_ad_links_' . $object_id );
}
add_action( 'adsanity_after_delete_meta', 'myprefix_after_url_deleted', 10, 3 );# adsanity_after_delete_meta_{$meta_key}
Fires after a specific meta value is deleted.
Parameters
string$object_type: The object type, usuallypost.int$object_id: The object ID.mixed$meta_value: The value being saved or removed.bool$delete_all: Whether matching meta is being deleted from every object.
Example
/**
* Resets the expiration reminder when an ad's end date (_end_date) is deleted.
*
* @param string $object_type The object type.
* @param int $object_id The object ID.
*/
function myprefix_end_date_deleted( $object_type, $object_id ) {
delete_post_meta( $object_id, 'myprefix_reminder_sent' );
}
add_action( 'adsanity_after_delete_meta__end_date', 'myprefix_end_date_deleted', 10, 2 );Advertiser Reporting Add-on
# adsanity_ar_placeholder_text
Fires after the list of email placeholders on the Advertiser Reporting settings screen. If you add your own placeholders with the adsanity_advertiser_reporting_email_message filter, this is where you can document them for your team.
Parameters: none
Example
/**
* Documents a custom *|SITE|* email placeholder.
*/
function myprefix_site_placeholder_text() {
printf(
'<p><code>*|SITE|*</code> %s</p>',
esc_html__( 'The name of this site', 'myprefix' )
);
}
add_action( 'adsanity_ar_placeholder_text', 'myprefix_site_placeholder_text' );Rotating Ad Widget Add-on
The Rotating Ad Widget can show each ad in its own iframe. These fire inside that iframe’s page.
# adsanity_raw_iframe_head
Fires inside the iframe’s <head>. Handy for adding styles or scripts that the ad needs.
Parameters
int$ad_id: The ad being displayed.
Example
/**
* Loads a stylesheet inside rotating ad iframes.
*/
function myprefix_rotating_ad_styles() {
printf(
'<link rel="stylesheet" href="%s">', // phpcs:ignore WordPress.WP.EnqueuedResources.NonEnqueuedStylesheet -- This page doesn't call wp_head().
esc_url( get_stylesheet_directory_uri() . '/css/rotating-ads.css' )
);
}
add_action( 'adsanity_raw_iframe_head', 'myprefix_rotating_ad_styles' );# adsanity_raw_iframe_footer
Fires right before the iframe’s closing </body> tag.
Parameters
int$ad_id: The ad being displayed.
Example
/**
* Adds a data attribute marker to the bottom of rotating ad iframes.
*
* @param int $ad_id The ad being displayed.
*/
function myprefix_rotating_ad_footer( $ad_id ) {
printf( '<div class="myprefix-ad-loaded" data-ad-id="%d"></div>', intval( $ad_id ) );
}
add_action( 'adsanity_raw_iframe_footer', 'myprefix_rotating_ad_footer' );Didn’t find what you were looking for?
If you’re a subscriber to AdSanity and don’t find an answer to your specific question please submit a request and our support department will address your issue quickly.
