AdSanity Rotating Ad Widget - WordPress Plugin

Guide to Setting Up and Using AdSanity Rotating Ad Widget

AdSanity Rotating Ad Widget is not just for dropping one more ad block into WordPress. Its real purpose is different: it lets you take an existing AdSanity ad group and rotate it in a single spot directly on the page, without waiting for the visitor to load a new page. In this guide, we'll walk through how to prepare your ads, where to enable the add-on, which settings to review after installation, how to use the widget, shortcode, block, and template call, and how to confirm that rotation is actually working.

This guide is written for a site owner, webmaster, editor, or developer who already understands why ad placements matter, but wants to avoid common mistakes: mixing banner sizes, running into cache conflicts, miscounting impressions, violating the rules of an external ad network, or ending up with empty blocks on the front end. It does not cover how to buy or activate a license. The focus here is configuration, implementation, verification, and troubleshooting.

The key idea behind the entire setup is this: Rotating Ad Widget works on top of AdSanity Core and uses existing ad groups. That means the quality of the final result depends not only on the add-on itself, but also on how the ads are grouped, which sizes you choose, how your theme outputs widget areas, and what kind of caching is enabled on the site.

What problem on-page ad rotation solves

A standard AdSanity ad group can already display different ads, but its default logic is tied to a new page view. A visitor opens an article, sees one banner, moves to the next page, and gets a different one. For short pages, that is often enough. But on a long article, reference page, review, recipe, roundup, or any page with high time-on-page, a single ad slot can stay static for too long.

AdSanity Rotating Ad Widget fills exactly that gap. The add-on introduces timed on-page rotation, which means ads inside the selected group change at a set interval. The visitor stays on the same page, while the ad slot displays the next banner in the group. This is especially useful when you have more advertisers than available sidebar or footer slots, and you do not want to clutter the layout with multiple ad blocks in a row.

How the add-on differs from a standard group

A standard group works well when you only need to select one or more ads when the page loads. Rotating Ad Widget is useful when you want to display multiple ads in the same spot during a single reading session. This distinction matters in AdSanity documentation: regular groups in default placements rotate on refresh or when a new page is opened, while Rotating Ad Widget adds time-based rotation directly on the page.

The practical takeaway is simple: if visitors move quickly between pages, a standard group may be enough. If they spend time reading a single article, browsing a gallery, or staying on a documentation page, time-based rotation gives each ad a better chance to be seen without adding more ad zones.

Where the user will see the result

The result appears wherever you insert the rotation: in a theme widget area, inside a post via shortcode, in an editor block, or in a theme template via a template tag. In every case, the logic is the same: you select an ad group, set the rotation interval, optionally enable random order, and limit the width if needed. What changes is only where you manage it.

Who this add-on is a good fit for, and when another approach makes more sense

Rotating Ad Widget works best on sites that use their own banners, affiliate images, sponsor creatives, or internal campaigns. The official add-on page specifically notes that it is intended primarily for self-hosted ads, meaning ads the site manages directly. That is an important limitation, because some external ad networks do not allow you to change how their code is displayed.

A good candidate for this add-on is a content site with multiple advertisers, a blog with long-form posts, a media site with a sidebar, an educational portal, a directory, a community site, or a commercial project that sells fixed ad placements. In those cases, rotation helps you avoid adding too many blocks and turning the page into an ad board.

The plugin may not be the right choice if your entire ad inventory comes from a network that already controls rotation, frequency, auction logic, and display rules. In that scenario, interfering with the display can violate the network's terms. The add-on also does not replace a full ad server with geotargeting, advanced audience rules, frequency caps, and revenue optimization. It solves a narrower problem: cleanly rotating AdSanity ads in a chosen WordPress placement.

What to check before installation

Before installing the add-on, it helps to do a quick technical review. It takes less time than troubleshooting an empty widget, a jumping layout, or questionable stats later. You need to review not only the add-on itself, but also AdSanity Core, your ad groups, banner sizes, theme, cache, and advertiser rules.

AdSanity Core and ad groups

All AdSanity add-ons require AdSanity Core to be installed. This matters even more for Rotating Ad Widget because it does not create a separate ad system. It uses existing ad groups and adds new output methods. Before installation, make sure the AdSanity section is available in the admin area, ads can be created without errors, and the target group already contains several active ads.

If the group is empty, contains only one ad, or includes ads of different sizes, the rotation will be less effective. In the first case, there is nothing to show. In the second, there is nothing to rotate. In the third, visitors will see the block jump in height or width. For a sidebar ad slot, it is usually safest to keep all ads in the same format, for example a consistent rectangle size across the entire group.

Ad types and external network rules

AdSanity supports ads hosted on your site, external ad services, HTML5 ads, and text ads. But Rotating Ad Widget is best planned around self-hosted or otherwise controlled creatives. If you use code from an ad network, review its policy first. The official add-on page warns that some networks may prohibit changing how ads are displayed and may even suspend sites for violating their terms.

Safe check: if an ad comes from an external network, do not enable rotation for it automatically. First, find the network's policy on refresh, rotation, auto-refresh, or changes to the ad container. If you cannot confirm it is allowed, use rotation only for self-hosted banners.

Cache and dynamic output

Caching is the main adjacent layer for any ad delivery setup. AdSanity documentation explains that caching which fully blocks server-side requests is incompatible with dynamic ad selection, because the plugin needs to choose a set of ads when the page loads. At the same time, fragment or object caching may work fine. For Rotating Ad Widget, that means checking two levels: selection of the initial ad on load, and the later time-based rotation on the page itself.

If the site uses aggressive page caching, a CDN, or a script optimizer, create a test page that does not receive critical traffic. Place the rotating ad there, clear the cache, open the page while logged out of the admin area, and see whether the ad changes. Only after that should you move the block into important areas of the site.

Installation and an initial WordPress check

Technically, installing the add-on is similar to installing a regular WordPress ZIP plugin. In the admin area, the path is Plugins - Add New - Upload Plugin, then you select the ZIP file and complete the installation. After that, click Activate. We are not covering the purchase or file download step because that depends on the user's account, and for setup purposes the next stage matters more: whether the new ad placement option appears in the interface.

After activation, check three places. First, the widget list: a new rotating ad widget should appear there. Second, the editor, if you use shortcodes or blocks: AdSanity adds tools for placing ads and groups, and with the add-on active, a rotating ads option becomes available. Third, the AdSanity add-ons settings area, where active add-ons get their own submenu items.

Quick post-activation check

1. Open AdSanity and make sure the group contains at least two active ads.
2. Open the theme widgets screen or the widget editor used by your theme.
3. Find the rotating ad widget and add it to a test area rather than your primary ad slot.
4. Select the group, set the interval, and save the changes.
5. Open the front end of the site in a private window and wait for the ad to rotate.

If the widget does not appear, do not start by reinstalling it. First check whether AdSanity Core is active, whether the add-on is disabled in the plugins list, and whether your current theme supports the widget area where you are trying to place the block.

Post-install configuration: widget, interval, alignment, and external ads

This is the most important section of the guide because mistakes usually happen not during installation, but when choosing the group, rotation time, alignment, and ad type. Rotating Ad Widget does not have dozens of complicated settings, but each available option affects both how the ad looks and how easy it is to troubleshoot.

Selecting an ad group

The group is the foundation of the entire rotation setup. Do not pick a random collection of ads. Choose a group that matches a specific placement on the site. If the widget sits in the sidebar, every ad in the group should be designed for that sidebar. If the block is inserted in the middle of a long article, the banners should work at content width. Otherwise, the add-on may function technically, but the user will see an unstable ad block.

Good practice: name groups by placement and format, not just by advertiser. For example, a sidebar 300x250 group is much clearer than a general mixed-banner group. That way, an editor can choose the right group faster in the widget, shortcode, or block.

Rotation interval

The time setting defines how many seconds an ad stays visible before the next rotation. The shortcode documentation shows an example with time="10", and the template tag documentation includes an example where time is set to 30. Those are not universal best-practice values. They simply demonstrate that the interval is defined in seconds.

For a typical content site, it is better to start with a moderate interval. If ads change too quickly, the block feels distracting and visually noisy. If they change too slowly, the add-on behaves almost like a regular group. Choose the timing based on page length: a long guide or review can use a calmer rotation, while a short sidebar placement should not rely on too many cycles.

How to choose a starting value without guessing

Take one test page and evaluate not just whether the banner changes, but also how it feels during reading. If the ad rotates while the reader is still focused on the paragraph next to it, the interval should probably be longer. If a second ad never appears during a normal page visit, the interval may be too long for that page. This kind of test does not replace analytics, but it helps you avoid a major mistake before launching a campaign.

Alignment and maximum width

Alignment controls where the block sits inside its container. In the shortcode and template tag, you can use values such as alignleft, alignright, aligncenter, and alignnone. For a sidebar, a neutral output is usually enough. For an in-content placement, centered alignment often works better. The max_width parameter helps prevent the ad from stretching wider than intended, especially if the theme makes images flexible.

After saving, be sure to check more than just the desktop view. Narrow the browser window and confirm that the ad block does not overflow the container, overlap text, or change height so abruptly that the reader loses their place in the article. If the ads in the group have different dimensions, fix the group first rather than trying to patch the issue with CSS.

Configuring external ads

The add-on page notes that Rotating Ad Widget includes an option to enable the feature for external ads as well. That does not mean you should turn it on by default. It only makes sense when you are certain that the external ad code allows this kind of display behavior. If you are unsure, leave external ads out of rotation and use the add-on only for self-hosted ads.

Rollback rule: if enabling external ads results in empty containers, complaints from the ad network, console errors, or unstable statistics, turn that mode off, clear the cache, and switch the group back to self-hosted banners.

Rotation logic, impression tracking, and ad order

To use AdSanity Rotating Ad Widget correctly, it helps to understand how it works. The add-on pulls ads from the selected group, shows one ad, and then rotates it based on the defined interval. The official page clarifies that ads are counted once after the initial page-load view. If there are three ads in the group, a full cycle will produce three views, one for each ad.

This behavior is useful for sites that sell impressions to advertisers, but it requires careful interpretation of reports. A single page view can produce multiple view events if the visitor stays on the page long enough to see several ads. That is not an error. It is the expected behavior of rotation. So you should not compare pageviews and ad views directly without context.

Random or sequential order

The shortcode documentation and changelog include a random parameter that controls random order. When enabled, ads do not always appear in the same fixed sequence. That reduces predictability and helps avoid a situation where the first advertiser almost always gets the initial visibility. If your ad commitments require a strict order, do not enable randomness without clearing that decision first.

Why consistent ad sizing matters

Rotation does not fix a poorly structured ad group. If you put a vertical banner, a wide leaderboard, and a small button ad into the same group, the rotation will feel jarring not because the add-on is broken, but because the assets do not belong in the same container. The group should represent a single ad slot, not every ad on the project at once.

How not to confuse impressions with clicks

For self-hosted ads, AdSanity can track both views and clicks. For external networks and HTML5 ads, there are limitations: the official documentation notes that for some ad types, clicks are tracked by the external network or are not tracked in AdSanity without additional integration. That is why it is important to know which ad type is included in the group before interpreting reports. If you mix different types, performance comparisons become less clear.

Placement options: widget, shortcode, block, and template tag

Rotating Ad Widget can be used in several ways. The best choice depends less on what editor is trendy and more on who controls the ad slot. For an editor, a block or shortcode inside a post may be most convenient. For a webmaster who does not want to edit theme files, the widget is often enough. For a developer who wants to hard-code the placement into a template, the template tag is the right option.

Widget for a theme area

The widget is the most straightforward option for a sidebar, footer, or any other widgetized area. Its main advantage is that you do not need to edit a post or template. The downside is that the result depends on the theme: not every theme renders widget areas the same way, and some designs hide sidebar areas at mobile widths.

If your theme uses the block-based widget editor, look for the relevant block or widget in the WordPress interface. If the theme is older and uses the classic widgets screen, add the rotating ad widget there. In both cases, check the front end after saving, not just the admin interface.

Shortcode in a post or page

The shortcode is useful when the ad needs to appear inside a specific piece of content. The official documentation shows the rotating shortcode structure with parameters such as align, time, group_id, max_width, and random. The example below shows the logic, but you should replace the values with your own group ID and a suitable interval.

[adsanity_rotating align="aligncenter" time="20" group_id="2" max_width="300" random="1"/]

Before publishing, open the page in preview mode and make sure the shortcode does not display as plain text. If you can see the raw shortcode string, it usually means the shortcode was inserted into a place where WordPress or the page builder does not process shortcodes, or the add-on is not active.

Editor block for Gutenberg sites

AdSanity documentation describes Gutenberg blocks for placing ads. When add-ons are active, additional blocks appear in the AdSanity section of the block inserter. This method is convenient for editors who do not want to remember shortcode parameters. A block works best when the ad slot is part of a specific page's content and should appear as a distinct element inside the editor.

Template tag for developers

A template tag is appropriate when the ad slot should be part of a theme template, for example after the post title, inside a category template, or in a dedicated area of a single-post template. The official documentation provides the adsanity_show_rotating_ads function. This code should only be added in a child theme or another safe template layer, not in WordPress core files or in the plugin's own files.

<?php
if ( function_exists( 'adsanity_show_rotating_ads' ) ) {
    adsanity_show_rotating_ads( array(
        'random'    => true,
        'group_id'  => 2,
        'align'     => 'aligncenter',
        'time'      => 30,
        'max_width' => 300,
        'return'    => false,
    ) );
}
?>

The post-insertion check is the same: open the page while logged out of the admin area, wait for the ad to rotate, confirm that no PHP errors appear on screen, and make sure the container does not break the layout. If something goes wrong, roll back the change in the child theme and first test the same set of ads through the widget or shortcode.

Practical example: one sponsor slot for multiple advertisers

Let's look at a realistic scenario. You have a site with long educational articles. The sidebar has room for one clean ad slot, but there are three advertisers: a course, a service, and an affiliate product. Stacking three banners one after another would look heavy and cluttered. The solution is to create one ad group and connect it through AdSanity Rotating Ad Widget.

Goal

Create a single ad container in the sidebar that displays three self-hosted ads of the same size and rotates them over time while the reader stays on the page.

Preparation

• AdSanity Core is installed and working.
• Rotating Ad Widget is activated as a separate add-on.
• Three banners of the same format and three destination URLs are ready.
• An ad group for the sidebar has been created.
• The site's theme includes a widget area that is visible on the relevant page types.

Setup steps

1. Create or open each ad in AdSanity and assign the same ad slot size to all of them.
2. Upload the image, enter the destination URL, and verify the publication period for the ad.
3. Assign all ads to one group, for example a sidebar sponsor block group.
4. Open the widgets screen and add the rotating ad widget to the appropriate area.
5. Select the group, set a moderate rotation interval, and save.
6. Clear the page cache if caching is enabled, then open the article in a private window.

Verifying the result

On the front end, you should see a single ad block. First one banner appears, then after the selected interval it changes to the next one. If you let the full cycle run, every ad in the group should appear. You should not draw conclusions from a single manual view in AdSanity reports, but you can confirm that impressions are being recorded in the expected direction.

A detail that often causes trouble

If the block changes height after rotation, the problem is almost always caused by asset size differences or theme CSS. Start by standardizing the banners to one format. If the sizes already match, check whether the theme is adding inconsistent spacing around images, links, or iframes. The fix belongs in the theme's outer container, not in the add-on logic.

Practical use cases for different kinds of sites

Rotating Ad Widget is not limited to the classic sidebar. It can be a clean way to distribute attention if you do not invent extra use cases and stick to the confirmed logic: an ad group, one placement, timed rotation, and result verification.

Long articles and knowledge bases

On pages where readers stay longer than usual, rotation helps you show several relevant offers without overloading the page. For example, a knowledge base can use one block for internal promos: a webinar, a consultation, a paid template, or a support page. Verification is simple: open a long article, scroll to the ad slot, and see whether the block still feels visually stable after rotation.

Seasonal and time-limited campaigns

AdSanity lets you set publication periods for ads, and a group can contain items with different schedules. That is useful for seasonal campaigns, as long as you remember to check which ads are active. The add-on does not replace a calendar of ad commitments, but it helps display active ads in one place. Before launch, make sure expired ads are not still sitting in the group as expected participants in the rotation.

Sponsored packages for multiple advertisers

If the site sells one ad format to multiple partners, rotation makes the offer easier to manage: all advertisers share one block instead of competing for different layout zones. Here it is especially important to agree in advance on how impressions are counted, because a single page view can lead to multiple ads being displayed within one cycle.

Internal promotions without an external ad network

For your own products, content, or events, the add-on is safer than it is for questionable third-party code. You fully control the banner, link, size, and display period. This works well for sites that want to promote their own sections without building a separate banner system.

How to verify results and reports after launch

Result verification should happen in two stages: visual output and statistics. Visual output answers whether the visitor sees a proper ad block. Statistics answer whether impressions and clicks are being recorded the way you expect. Do not mix those two stages, or you may spend a long time chasing a reporting issue when the real problem is cached HTML or an empty group.

Visual verification

1. Open the page in a private window so the administrator session does not affect the result.
2. Check the first ad display immediately after page load.
3. Wait for the selected interval and confirm that the banner changes.
4. Repeat the test on a page with a different template if the widget is displayed globally.
5. Narrow the browser window and make sure the ad does not overflow its container.

Checking reports

In the AdSanity Reports section, you can view summary data, top clicks, click-through rate, and group-level data. For rotation, it is important to understand that ad views may increase faster than page views if a visitor sees multiple ads. That is normal for timed rotation. For external networks and HTML5 ads, review tracking limitations separately: AdSanity documentation explains the differences in measurement across ad types and the separate role of Google Analytics Tracking Integration.

What to document before sending a report to an advertiser

If the statistics are shared outside your team, document the rules for reading the report in advance: where the ad block is placed, how many ads are in the group, which rotation interval is set, what ad type participates in the rotation, and which events AdSanity counts. That way, the advertiser sees not just an abstract impression number, but clear context. This matters especially for sponsored packages where multiple partners share one placement.

For internal verification, it is useful to save a short note in the site's working log: the test page URL, the ad group, the insertion method, and the expected behavior. If the block stops rotating a month later after a theme or optimizer update, that note will shorten troubleshooting because you will quickly see what changed: the group, the placement, the cache, or the JavaScript.

Cache check

If rotation works right after you clear the cache but stops after some time, review your page cache and JavaScript optimization settings. Do not disable all caching blindly. First exclude the test page, verify the behavior, and then decide whether you need an exclusion for the specific ad container or a different caching mode. AdSanity documentation explicitly states that systems which completely block server-side requests for dynamic data are incompatible with its ad selection logic.

Safe appearance tweaks without editing the plugin

Sometimes the rotation works, but the block does not look right: it sits too close to the text, does not center properly, the image exceeds the intended width, or spacing changes noticeably between rotations. The official AdSanity ad placement documentation explains that appearance changes should be handled through theme CSS, and that each ad has a unique ID and size class. That gives you a safe path: do not edit WordPress core, AdSanity, or the add-on itself. Instead, add a small rule to your child theme or the built-in Additional CSS field.

The sample below is not a ready-made selector for every site. It is a safe template. First inspect the page in your browser, find the actual ID or class of the ad block, and replace the sample selector with your own. If you are not sure, limit yourself to the max_width setting in the widget, shortcode, or template tag.

/* Replace #adsanity-example-ad with the actual ad block ID from the HTML. */
#adsanity-example-ad {
    max-width: 300px;
    margin: 0 auto 24px;
}

#adsanity-example-ad img {
    display: block;
    max-width: 100%;
    height: auto;
}

Post-CSS verification is simple: refresh the page without cache, let several ads rotate, and confirm that all banners stay within one container, do not stretch, and do not overlap nearby content. Rolling back is simple too: remove the added rules and clear the CSS cache. If the issue goes away only after hard-coding the height, it is better to go back to the group and verify the source banner dimensions.

Troubleshooting: why rotation is not working or looks wrong

Problems with Rotating Ad Widget are usually not caused by a single issue, but by a chain of factors: the ad group, ad status, ad code type, theme, cache, and placement method. The best approach is to move from simple to complex. First check whether there is anything to display, then where the block is being rendered, then whether the ad changes over time, and only after that move on to cache, external networks, and reports.

The widget is added, but no ads are displayed

Symptom: there is an empty space in the expected page area, or no ad block appears at all. Possible causes include an empty group, unpublished ads, an expired display period, the wrong group being selected, a theme that hides the widget area, or cached delivery of an older page version.

Check the group in AdSanity, make sure it contains active ads, then temporarily place the same output through a shortcode on a test page. If the shortcode works, the problem is more likely related to the widget area or the theme. If the shortcode does not work either, go back to the group and the ads.

The ad appears, but does not rotate over time

Symptom: the first banner is visible, but nothing happens after the selected interval. Make sure the group contains more than one active ad, that you are using the rotating widget or rotating shortcode rather than a standard group, and that there are no JavaScript errors in the browser console. If script optimization is enabled, temporarily disable script combining or deferred loading on the test page.

The block height jumps after the banner changes

Symptom: text around the ad shifts, the sidebar changes height, and the reader loses their place. In most cases, the group contains mixed sizes or images with different aspect ratios. Standardize the banners first. If the sizes already match, inspect the theme CSS and the max_width limit.

The statistics seem too high

Symptom: ad views are higher than expected based on page views. For timed rotation, this may be perfectly normal because one page load can display multiple ads. Check how many ads are in the group, what interval is set, and how long users stay on the page. Do not compare pageviews and ad views without accounting for the rotation cycle.

An external ad network behaves unpredictably

Symptom: empty iframes appear, network errors show up, scrollbars appear around the ad code, or the network sends warnings. In that case, roll back rotation for external ads and return the add-on to self-hosted banners. Then review the ad network's rules separately. If the network already controls rotation and ad refresh on its own, additional timed rotation on the WordPress side may be unnecessary.

Quick troubleshooting path

What you see	First action	When to roll back the setting
Empty block	Check active ads in the group and the publication period.	If the group is not ready, remove the widget from the public page.
No rotation	Check the interval, the number of ads, and script errors.	If script optimization breaks rotation, restore the previous cache settings and look for a targeted exclusion.
Layout jumps	Standardize banner sizes and check max_width.	If advertisers supplied different formats, do not mix them in one group.
Questionable stats	Review the ad type and how impressions are counted.	If reports will be shared with an advertiser, agree on the counting method before the campaign launches.

When AdSanity Rotating Ad Widget is the right choice

AdSanity Rotating Ad Widget is worth using when the site already has AdSanity Core, several self-hosted ads grouped together, and a clear goal: show more advertisers in one clean slot without adding extra blocks. It is especially useful for long-form content, sponsored areas, internal promotions, and sites where an editor needs manageable output through a widget, shortcode, or block.

Before launch, verify three things: the group contains active ads in the same format, the rotation interval does not distract readers, and the selected ads do not violate the rules of an external network. After launch, look at more than the visual result. Review the reports too, because rotation changes what impressions mean: one page view can display multiple ads.

If the scenario fits your site after testing, you can download AdSanity Rotating Ad Widget, install the add-on on a staging copy or a low-visibility page, build your first ad group, and only then move the rotation into your main advertising area.