Kudonics Promo Banner Builder

What the plugin does

Kudonics Promo Banner Builder creates reusable promotional campaigns without an external SaaS: design, targeting, and metrics stay in WordPress. WooCommerce, Elementor, and a third-party page builder are not required for core functionality.

System requirements & compatibility

For the admin area, modern versions of Chrome, Safari, Firefox, or Edge are recommended. Plugin responsive breakpoints: Desktop — 1025 px and up, Tablet — 768–1024 px, Mobile — up to 767 px.

Installation & activation

Via WordPress Admin

1. Open Plugins → Add New → Upload Plugin.
2. Select the plugin release ZIP and click Install Now.
3. When installation is complete, click Activate Plugin.
4. In the left-hand menu, open Promo Builder.

Manual installation

1. Extract the directory kudonics-promo-banner-builder.
2. Upload it to /wp-content/plugins/ without an extra nested directory level.
3. Activate Kudonics Promo Banner Builder on the Plugins screen.

What happens during activation

• The capability is registered: manage_promo_banner_builder_campaigns for Administrator and, if present, Shop Manager.
• Metrics tables are created and a daily cleanup is scheduled.
• Eight draft starter campaigns are created once, without overwriting any later changes you make.
• The private custom post type is registered: promobanner_campaign.

Quick start: a campaign in 5 steps

1. Open Promo Builder and click Add campaign or open one of the starter drafts.
2. Give the campaign a clear name: the format type — offer — audience/period makes searching and reporting easier.
3. In Banner builder edit the text, CTA, colors, sizes, and positions.
4. In Display rules choose the mode, schedule, trigger, and pages.
5. Click Publish. For a static banner, copy the shortcode; for a popup, check Enable campaign or insert a manual trigger button.

Dashboard widget

The widget provides quick access to campaign creation, the campaign list, and full metrics, and also shows all-time totals.

CTR is calculated as clicks ÷ views × 100. Close-button clicks are not included in clicks, so closes are reported separately.

Campaign list & lifecycle

Duplicate

The Duplicate action creates an exact copy of post data, design/display meta, and taxonomies. The name gets a “Copy” suffix, and the status is inherited — after duplicating, check that the copy has not become active at the same time as the original.

Eight starter templates

Templates are created as Drafts and serve as fully editable examples. They do not appear on the frontend until you publish them and configure placement/rules.

Static banners

Popups

Visual builder: workspace structure

Working on the canvas

• Clicking an element selects it and opens the corresponding style panel.
• Drag changes position; resize handles change size; the rotate handle changes the angle.
• Changes appear in the preview immediately, but are written to the database only after Save/Update/Publish.
• The arrow button collapses the tools panel, freeing more space for the canvas.
• Fullscreen mode opens Quick View with tools, theme toggle, and a large canvas.

Layers & keyboard commands

Element types

Shape library

Rich text sanitization

Textarea allows limited safe HTML: strong, b, em, i, u, s, strike, br, p, div, ul, ol, li, span with hex color and a[href]. This means arbitrary scripts/styles are not saved.

Styles, transform & entrance animations

Wrapper

Supported width units are px, % or vw; height units are px or vh; transparent/solid/linear-gradient backgrounds; background image with size/repeat/position; border radius, width, style, and color. Static banners support left/center/right alignment; popups support 9 positions from center to corners and an optional dark backdrop.

Transform

Animation presets

None Fade in Slide up Slide down Slide from left Slide from right Zoom in Pop Soft bounce Custom movement

Easing: ease-out, ease-in-out, linear, spring. Repeat: once, twice, or loop. Do not use loop on large text blocks — it hurts readability and distracts from the CTA.

Desktop, Tablet & Mobile

Desktop is the base design. Tablet and Mobile store only overrides, so unchanged values are inherited.

Recommended workflow

1. Finish the composition on Desktop.
2. Switch to Tablet and adjust width, headline size, and overflow.
3. Switch to Mobile, increase tap targets, and check height, the close button, and the CTA.
4. Use Hide on Desktop/Tablet/Mobile only for secondary decoration, not critical information.
5. Check the actual page, not only the scaled preview.

Display rules

Campaign mode

Static banner ads ON disables popup Enable campaign and displays the banner shortcode. Static banner ads OFF creates a popup; for manual trigger/automatic display rendering, Enable campaign.

Trigger logic

If both a delay and scroll trigger are set, the popup opens only after both conditions are met. A manual trigger ignores the automatic page rule and delay, but it does not ignore Publish/Enable or the schedule.

Schedule

Start/End are entered in the site timezone from Settings → General, stored in UTC, and converted back when editing. An empty Start means “active immediately”; an empty End means “no end limit”.

Priority

Range: 0–100. Higher priority is sorted first; when priority is equal, the lower campaign ID comes first. Priority determines the order of automatically eligible popups, but does not replace page/schedule checks.

Show on

Reset popup display

A closed popup stays hidden until the end of the current browser session. Reset clears dismissal only for the current browser and this campaign; other visitors are unaffected. After reset, reload the frontend page.

Shortcodes & manual placement

Static banner

[promo_banner id="123"]

Campaign 123 must be Published, in Static banner mode, and within its schedule. Page targeting does not apply to static banners: placement is determined by the shortcode itself.

Popup trigger button

[promo_popup_button id="123" text="Open offer"]

Supported attributes are id, text and class. Enclosed content takes priority over text:

[promo_popup_button id="123" class="my-offer-button"]Get discount[/promo_popup_button]

Where you can insert it

• Shortcode block in Gutenberg.
• Classic Editor content.
• Text/Custom HTML/Block widgets.
• A page builder element that executes WordPress shortcodes.
• A PHP theme template through the standard do_shortcode() — only in custom development.

Gutenberg & Elementor

Gutenberg blocks

1. In the block editor, click Add block.
2. Search for “promo” or the plugin name.
3. Select a published campaign in Inspector controls.
4. For the popup button, set the label and alignment.
5. Check the frontend: the blocks are dynamic and use the same renderer as the shortcodes.

Elementor

After Elementor is activated, the category Kudonics Promo Banner Builder appears with the widgets Static Promo Banner and Promo Popup Button. They select a campaign from the list of published-compatible campaigns; the popup widget also has Button Text.

Asset loading

Frontend CSS/JS loads only when there is a matching automatic campaign, shortcode/block/widget placement, or preview context. A theme/renderer can explicitly declare placement through the filter described in Developer reference.

WooCommerce integration

WooCommerce is optional. Without it, the plugin continues to work, and the builder shows an informational note instead of product controls.

Product element

Search returns up to 20 published simple products that are purchasable and in stock. You can add title, image, price, and an AJAX add-to-cart button together or selectively.

Product styles

Card width/padding/radius/background, text/title/price colors and sizes, image width, button background/color/font size/radius/padding. Product scale remains proportional.

Targeting

• Shop pages: shop archive, product categories, and product tags.
• Product pages: only single product.
• If a WooCommerce rule is saved and WooCommerce is deactivated, the rule will not match until WooCommerce is active again.

Metrics & reports

Metrics are stored locally in the WordPress database. Overview supports 7/30/90 days or All time, search, CSV export, print, and dark mode.

Events

Detail report

An individual campaign shows views, unique sessions, clicks, CTR, closes, close rate, daily activity, and breakdowns: clicks by element, devices, browsers, countries, pages, referrers, languages, and time zones.

How to read the metrics

• CTR = clicks / views. A low CTR may indicate a weak CTA or incorrect targeting.
• Close rate = closes / views. Review a high value together with delay and page relevance.
• Unique sessions — privacy-safe sessions, not people or lifetime unique users.
• Clicks by element help compare multiple CTAs within a single banner.

Data management

Privacy, retention & data deletion

What may be stored

Event type, campaign, element ID/type, placement, device category, browser family, page ID/path, referring host, browser language, browser time zone, and country code — only if the hosting/CDN provides it through a supported header.

What is not stored

• Raw IP address.
• Full referrer URL — only the host is stored.
• External analytics identifier.
• User contact details.
• Raw browser session ID: an HMAC SHA-256 salted non-reversible hash is stored.

Data-volume safeguards

By default, a maximum of 5,000 new dimension rows per campaign/day and 50,000 unique sessions per campaign/event/day are allowed. Identical dimensions are aggregated into a counter row. Limits and rate intervals can be changed with filters.

Retention

Default — 365 days. Daily WP-Cron cleanup deletes old rows. Available values are 30, 90, 180, 365, 730 days, or indefinitely. If WP-Cron is disabled, configure a server cron to run WordPress cron regularly.

Uninstall

By default, campaigns, metrics, and settings remain after uninstall. To delete everything, first enable “Delete all campaigns, metrics, and plugin settings when the plugin is uninstalled”, save the setting, and only then delete the plugin.

Accessibility recommendations

• Popup markup uses dialog semantics, aria-modal, the campaign title as the label, and manages aria-expanded on the trigger.
• A static banner has a region role and an accessible campaign label.
• Add meaningful Alternative text to images; leave alt empty for decorative images.
• The CTA should describe the result: “Get −20%”, not “Click here”.
• Check contrast for normal/hover states and visible focus.
• Do not hide critical legal/offer content through device visibility.
• Plugin CSS respects prefers-reduced-motionby disabling transition duration for relevant elements.
• The close button should be visible, high-contrast, and large enough on Mobile.

Roles, permissions & security

Managing campaign UI and metrics requires manage_promo_banner_builder_campaigns. The capability is automatically added to the roles administrator and shop_manager. For a custom role, assign the capability through a role-management plugin or code.

• Campaign saves, AJAX searches, shortcode preview, duplication, and metrics actions check the capability.
• State-changing admin requests are protected by WordPress nonces.
• Design/display values go through type checks, allowlists, bounds, and sanitization.
• Shape SVG is selected only from the plugin-owned library; arbitrary SVG markup is not accepted.
• Frontend metric requests validate the nonce, published campaign, event allowlist, and session format.
• Links opened in a new tab receive noopener noreferrer.

Troubleshooting

Frequently asked questions

Developer reference

Storage identifiers

Filters

Custom asset detection example

add_filter(
    'promo_banner_builder_should_enqueue_frontend_assets',
    function ( $should_enqueue ) {
        return $should_enqueue || is_page_template( 'templates/promo-landing.php' );
    }
);

Rendering API

For integration code, you can get the singleton through \PromoBannerBuilder\Plugin::instance() and use public render methods. In most cases, using a shortcode/block is safer because they also register the required assets and popup footer markup.

Performance notes

• The campaign query runs once per request and is cached in instance properties.
• Frontend assets are not enqueued without matching/manual placement.
• Metrics use aggregate dimensions with a unique key and upsert counter.
• Product cart fragments are enqueued only when an actual product element is present.
• Images receive decoding="async"; file optimization remains the responsibility of the Media Library/CDN.

Production checklist

Recommended acceptance test

1. Open the page in an incognito session.
2. Test the delay + scroll trigger and confirm that only one expected popup appears.
3. Follow the CTA and verify the URL/new tab behavior.
4. Close the popup and confirm that it does not reopen during the same session.
5. Repeat on a mobile viewport and with keyboard navigation.
6. Open Metrics after the events have been processed and verify attribution.

Glossary