WordPress plugin

The BannerFlex WordPress plugin stores banners and campaigns in your site and evaluates schedule and geolocation in PHP or via REST. Use the shortcode for quick placement or the PHP API for full control in themes and custom code.

Shortcode

Insert the shortcode in any post or page. Replace the IDs with your Banner ID and Campaign ID from BannerFlex → Edit banner in WP Admin.

[bannerflex banner_id="BANNER_UUID" campaign_id="bnrflx-CAMPAIGN_UUID" /]

The shortcode outputs a placeholder; a script calls the REST API and, when the campaign should show, renders a fixed top bar using your content fields (e.g. headline, body). You can change this by editing the plugin's assets/front.js.

REST API

When the plugin is active, these endpoints are available (no auth required for GET):

• GET /wp-json/bannerflex/v1/campaign-config?bannerId=&campaignId= — Returns show, campaignId, contentFields. Optional query params: country (ISO2), date (for testing schedule).
• GET /wp-json/bannerflex/v1/should-show?bannerId=&campaignId= — Returns { "show": true } or { "show": false }.

Geo is resolved from the country query param, the bannerflex_country filter, or the CF-IPCOUNTRY header (e.g. Cloudflare).

PHP API: bannerflex_get_campaign()

Use this function in your theme or custom plugin to get the evaluated campaign result (show/hide and content fields) without an HTTP request. Schedule and geolocation rules are applied in PHP. Useful for server-rendered banners or when you want to output HTML yourself.

Signature

bannerflex_get_campaign( $banner_id, $campaign_id, $country = null, $now = null )

Parameters

Return value

An associative array with:

• show (bool) — Whether to show the banner for this campaign given schedule and geo.
• campaignId (string|null) — The campaign ID, or null if banner/campaign not found.
• contentFields (array) — List of content field objects: id, key, label, type, value. Empty if not found.

// When campaign should show and has content fields:
array(
  'show'          => true,
  'campaignId'    => 'uuid',
  'contentFields' => array(
    array( 'id' => '...', 'key' => 'headline', 'label' => '', 'type' => 'text', 'value' => 'Free shipping today' ),
    array( 'id' => '...', 'key' => 'body', 'label' => '', 'type' => 'text', 'value' => '...' ),
  ),
)

// When banner/campaign not found or should not show:
array( 'show' => false, 'campaignId' => null, 'contentFields' => array() )

Behavior

• Schedule: If the campaign has start/end dates, $now (or current time) must fall within that range or show is false.
• Geolocation: If geo is enabled on the campaign, $country (or the filter/header value) is used with the campaign's default behavior and country overrides to decide show/hide.

Example: theme template

$result = bannerflex_get_campaign( 'banner-uuid', 'bnrflx-campaign-uuid' );

if ( ! empty( $result['show'] ) && ! empty( $result['contentFields'] ) ) {
    echo '<div class="bannerflex-banner">';
    foreach ( $result['contentFields'] as $field ) {
        echo '<div class="' . esc_attr( $field['key'] ) . '">' . wp_kses_post( $field['value'] ) . '</div>';
    }
    echo '</div>';
}

Example: with country and date (testing)

// Simulate US visitor for geo
$result = bannerflex_get_campaign( $banner_id, $campaign_id, 'US' );

// Test schedule as of a specific date
$now = new \DateTime( '2025-12-25 12:00', wp_timezone() );
$result = bannerflex_get_campaign( $banner_id, $campaign_id, null, $now );

Filter: bannerflex_country

When bannerflex_get_campaign() or the REST API is called without a country argument, the plugin runs this filter so you can provide the country from your own geo source (e.g. another plugin or CDN header).

add_filter( 'bannerflex_country', function ( $country, $request ) {
    // $request is null when called from bannerflex_get_campaign(); for REST it's WP_REST_Request.
    if ( $country !== null ) {
        return $country;
    }
    // Example: from a custom header or cookie
    return isset( $_SERVER['HTTP_X_COUNTRY'] ) ? strtoupper( substr( $_SERVER['HTTP_X_COUNTRY'], 0, 2 ) ) : null;
}, 10, 2 );