WP Manifestindependent plugin directory
manifest / analytics / wp-server-side-ab

Server-Side A/B

Server-side A/B testing for WordPress that survives page caching. No flicker, no JavaScript.

★ 0stars

Install

Download source zip No release zip yet

This is the repository archive. It installs, but the folder name will carry the branch suffix and updates will not flow.

Install straight from GitHub with WP-CLI:

wp plugin install https://github.com/avilavi44/wp-server-side-ab/archive/refs/heads/main.zip
No built-in updater. New versions won't appear under Dashboard → Updates. Install new releases yourself, or let Git Updater track the repository.

A small WordPress plugin for server-side A/B testing. PHP picks the variant before the page is sent, so there is no flicker and no JavaScript dependency.

The problem

Client-side A/B tools swap content after the page loads, which causes flicker and hurts page speed. Doing it on the server fixes that, but creates a new problem: WordPress sites usually sit behind a page cache, and a cache will happily serve one visitor's variant to everyone. This plugin handles the assignment and takes care of the cache side.

How it works

  • Sticky, deterministic bucketing. A visitor gets one random id in a cookie (ssab_id). The variant is a hash of the experiment key and that id, so nothing is stored per experiment, and a visitor's bucket in one test is independent of their bucket in another.
  • Cache safety. See Page caches below.
  • Signed preview links. An HMAC token forces a variant for whoever opens the link, until it expires. It works for reviewers with no account on the site, and it sets no cookie and reports no exposure.
  • Exposure reporting. An action fires once per experiment per request, for your analytics to hook.

The bucketing and signing live in plain PHP classes (includes/class-ssab-bucketer.php and includes/class-ssab-preview-token.php) that call no WordPress functions.

Install

Copy this folder into wp-content/plugins/ and activate it. There is no build step. Needs WordPress 6.0 and PHP 7.4 or newer.

Usage

Register an experiment. The first variant is the control:

add_action( 'init', function () {
    ssab_register_experiment( 'hero-copy', array( 'control' => 50, 'short' => 50 ) );
} );

Keys may use lowercase letters, digits, - and _. Keep the variants in a stable order: changing their order or weights moves visitors between buckets.

In post content:

[ssab_variant experiment="hero-copy" name="control"]Everything you need to run your shop.[/ssab_variant]
[ssab_variant experiment="hero-copy" name="short"]Run your shop.[/ssab_variant]

In a template, using the helpers:

ssab_render_variant( 'hero-copy', array(
    'control' => '<h1>Everything you need to run your shop.</h1>',
    'short'   => '<h1>Run your shop.</h1>',
) );

if ( 'short' === ssab_get_variant( 'hero-copy' ) ) {
    get_template_part( 'parts/short-hero' );
}

The cookie must be sent before the page starts to print. The plugin finds the shortcode by itself, but it cannot see inside a template, so tell it which pages use the helpers:

add_filter( 'ssab_page_has_experiment', function ( $found ) {
    return $found || is_front_page();
} );

A visitor who reaches a helper too late for a cookie sees the control, and no exposure is counted.

Report exposures to your analytics. This runs during page rendering, so keep it fast:

add_action( 'ssab_exposure', function ( $experiment, $variant, $visitor_id ) {
    my_analytics_track( 'experiment_exposure', compact( 'experiment', 'variant', 'visitor_id' ) );
}, 10, 3 );

Respect a consent banner. Without consent the visitor sees the control and no cookie is set:

add_filter( 'ssab_can_set_cookie', 'my_visitor_has_consented' );

Make a preview link, or find ready-made ones under Tools, A/B previews:

$url = ssab_preview_url( 'hero-copy', 'short', home_url( '/pricing/' ), HOUR_IN_SECONDS );

Page caches

Every response from a page that runs an experiment is protected:

Request What the plugin sends
No cookie yet nocache_headers(), and a new cookie
Has a cookie Cache-Control: private, max-age=0 and Vary: Cookie
Preview link nocache_headers()

It also defines DONOTCACHEPAGE, which WordPress page-cache plugins honour.

That covers caches that respect these signals. You should still tell your cache to bypass any request carrying the cookie, so a stale copy can never be served to a bucketed visitor:

Cache Setting
WP Rocket Advanced Rules, Never Cache Cookies: ssab_id
LiteSpeed Cache Cache, Excludes, Do Not Cache Cookies: ssab_id
W3 Total Cache Page Cache, Advanced, Rejected Cookies: ssab_id
Cloudflare Cache Rule, when http.cookie contains "ssab_id": Bypass cache

Nginx FastCGI cache:

if ($http_cookie ~* "ssab_id") { set $skip_cache 1; }
fastcgi_cache_bypass $skip_cache;
fastcgi_no_cache $skip_cache;

Varnish:

sub vcl_recv {
    if (req.http.Cookie ~ "ssab_id") { return (pass); }
}

A cookie rule applies across the site, so a bucketed visitor misses the cache on every page. If that costs too much, exclude only the experiment's URLs from the cache instead. Either way, make sure the ssab_preview query string is not stripped or ignored by the cache.

Limitations

  • A visitor can edit their own cookie and so choose a bucket. That is harmless for a marketing test, but do not use a variant to control access to anything.
  • Exposures are counted per page view, so deduplicate by visitor id in your analytics.
  • Crawlers are bucketed like anyone else.

Tests

composer install
composer test                               # both suites
vendor/bin/phpunit --testsuite unit         # plain PHP only, no WordPress and no stubs
composer lint                               # WordPress Coding Standards

The glue suite runs the WordPress side against the small stubs in tests/glue/wp-stubs.php, not a full WordPress install, so try the plugin on a staging site before relying on it.

License

MIT