Page caching

WP Ad Inserter decides which ad to show while WordPress generates a page. A full-page cache skips that step for most visitors, and this changes what the rules can do.

What happens

A caching plugin, a server cache or a CDN that caches HTML works like this:

  1. The first visitor asks for a page. WordPress and WP Ad Inserter generate it: the plugin checks the visitor’s country, device, language and time and chooses the ad.
  2. The cache stores the finished HTML.
  3. Every next visitor receives that stored HTML. WordPress and the plugin do not run, so nothing is checked again.

The IP lookup itself works correctly. The problem is that it runs once per cached page, for whoever came first. If that visitor was a bot or came from another country, everybody receives the ad chosen for them until the cache expires or is cleared.

What is affected

Works with a cacheApplies to the first visitor only (unless the campaign is in browser mode)
  • Positions and the Display in switches
  • Post IDs, categories, tags, keywords, post types, author, minimum words, page address and URL parameters (they depend on the page, not on the visitor)
  • Rotation off (a stable ad per post)
  • The impression counter
  • Country and city
  • Devices, referrer, cookies and browser
  • System language codes
  • Weekdays and showtime ranges
  • Rotate on
  • Ad behavior limits

Browser mode

Switch on Load this ad in the browser (Placement tab, row Delivery) for a campaign and the ad is chosen for every visitor, not once for the cached page:

  1. The page contains only an empty marker where the ad belongs. The position, Display in and the post rules (post IDs, categories, tags, keywords, post types) are still decided when the page is generated, because they depend on the page and not on the visitor.
  2. A small script in the visitor’s browser asks your site, with one POST request to /wp-json/wpai/v1/ads, which ad to show. The request is never cached.
  3. Your site checks the visitor rules for this visitor (country, city, language, device, weekdays, hours, dates, login status), applies the ad behavior limits, picks the ad and returns its code.
  4. The script inserts the code at the marker and runs the scripts in it, so AdSense and similar code work as usual.

The price of this mode:

  • The ad appears a moment after the page has loaded.
  • Visitors without JavaScript do not see it, and the REST API of your site must be reachable.
  • Every page with such an ad makes one extra request to your site.
  • Ad blockers may block the request.
  • User roles are not applied. Login status is read from the login cookie.
  • Ad behavior limits are counted separately from the campaigns that are not loaded in the browser.

Fast endpoint

By default the request of the browser mode goes to the WordPress REST API, which first loads your theme and every active plugin. On a site with many plugins this takes seconds, and the ad appears that much later. The switch Fast endpoint for the browser mode on the Settings page sends the request to wp-content/plugins/wpadinserter/ads.php instead. That file loads only the WordPress core (the database and the options), so it answers in a fraction of the time.

  • Campaigns with Execute PHP are always answered through the REST API, because their PHP may use functions of WordPress or of other plugins that the fast endpoint does not load.
  • If the fast endpoint cannot be reached (a host or firewall blocks PHP files in the plugins folder, WordPress is in an unusual location, an error), the visitor’s browser silently falls back to the REST API.
  • The fast endpoint answers only while the switch is on and the plugin is active.
  • It matters only when at least one campaign loads its ad in the browser.

Use browser mode only for the campaigns that have visitor rules or rotation. Campaigns that depend on the page alone work with a cache as they are, and the impression counter counts browser-mode ads too.

What to do

  • Switch on browser mode for the campaigns with visitor rules or rotation (see above).
  • Or do not cache the pages that carry visitor-dependent ads. Most caching plugins can exclude URLs, page types or visitors with certain cookies.
  • Use a cache that keeps separate copies by country or device type, if yours can. Then every group gets its own generated page.
  • Use the rules that do not depend on the visitor (positions, post rules) on cached pages.
  • Clear the cache after every change to a campaign. Otherwise you will keep looking at the old page.
  • Test from outside. You cannot judge country rules from a logged-in browser that your cache plugin bypasses. Check a cached page in a private window.

If you use a CDN, the plugin reads the visitor address from headers such as CF-Connecting-IP. See GeoIP and visitor IP.

The impression counter was built for cached sites: it works in the visitor’s browser. See Impressions and clicks.