Overlay Campaigns

Overlays render site-targeted popups, slide-ins, banners, fullscreen takeovers, notifications, and embedded placements through the browser SDK. Content is built from blocks such as forms, offers, quizzes, and product recommendations.

Create the campaign

1. Open Dashboard → Overlays and create a campaign.
2. Choose the target site, the overlay type, and a template from the Upsurge catalog, or start blank. Pick a theme to set colors and typography.
3. Give the campaign an operational name that identifies audience and goal.
4. Build content from blocks (see below).
5. Set style, layout, close behavior, and responsive presentation.
6. Save as Draft while you configure delivery.

Overlay types

Type	Behavior
Popup, slide-in, banner, fullscreen, notification	Floating surfaces opened by triggers and limited by frequency caps.
Embedded	Rendered inside a storefront element with mountEmbeddedOverlay(). Triggers and frequency caps do not apply.

The overlay type cannot be changed after creation.

Blocks

Group	Blocks
Content	Text, Image, Video, HTML
Commerce	Product, Recommendations, Recent Products, Quiz
Actions	Button, Coupon, Countdown, Form
Layout	Divider, Spacer, Columns

An overlay holds up to 12 blocks, with up to 6 per column. Buttons can open a URL, close the overlay, or copy a code. The Form block starts from a preset (email signup, contact request, event registration, or feedback) or a custom field set. A Coupon block can use a manually entered code or an imported store coupon.

Duplicating a campaign creates a new draft. Deleting through the merchant flow archives it.

If your workspace has access to the Dashboard Assistant, you can request a draft or an edit to selected canvas content. Assistant changes stay in the unsaved editor with undo; saving and activation use the existing manual controls.

Video blocks select MP4 or WebM assets from the media library. They always show playback controls and support muted autoplay, looping, contain/cover/fill sizing, a required accessible label, an optional poster image, and optional HTTPS WebVTT captions. Autoplay is muted for browser compatibility and suppressed when the visitor prefers reduced motion. Captioned video and WebVTT origins must allow anonymous cross-origin requests. Verify that your storefront Content Security Policy allows both delivery origins through media-src.

Target the audience

Targeting conditions can match a saved audience (see Audiences), page/URL, device, and country, region, or city. Choose explicit ALL or ANY logic. Location is resolved server-side from trusted geo context; the SDK does not receive the visitor’s raw IP or resolved location.

Optional intent targeting can include or exclude category, purchase-stage, brand, price-band, product, and audience-segment traits. Use the reach estimate as directional inventory, then validate on a controlled audience.

Profile variables use {{profile.field_name}}, for example {{profile.first_name}} or {{profile.loyalty_tier}}. Only fields allowed for the overlay surface are rendered; missing values become empty strings.

Configure triggers and frequency

Available triggers are Immediate, Time on Page, Scroll Depth, Exit Intent, Inactivity, Page Count, and Element Click (a CSS selector). Choose ANY trigger (OR) or ALL triggers (AND):

• ANY launches after the first configured trigger matches.
• ALL waits until every configured trigger rule has fired.

Frequency caps limit displays Per session, Per day, and Per lifetime, with an optional cooldown in minutes. Configure them deliberately so previews and repeated QA visits do not look like targeting failures. Use Schedule (start and end date) to bound a campaign in time and Priority to choose between overlapping campaigns.

Preview and activate

1. Preview desktop and mobile layouts.
2. Exercise every interactive block, close path, form, coupon, countdown, quiz branch, and destination URL.
3. Confirm the actual target page matches targeting and trigger rules.
4. Activate the campaign.
5. Load the storefront in a clean session and verify /api/v1/overlays/config returns the campaign.
6. Confirm upsurge-overlays.min.js loads only after a campaign matches.

Test variants

Use the editor's A/B test variants workspace to create up to four versions of an overlay, then run them as an experiment. Variant editing has restrictions while an experiment is running.

Submissions and measurement

Form blocks submit through /api/v1/overlay-submissions. Submissions appear in Dashboard → Leads, where you can deliver them to Mailchimp, Constant Contact, or SendGrid, retry failed deliveries, export, or delete them. See Leads. Do not request data you do not need, and handle capture data according to your consent and retention policy.

Overlay analytics distinguish:

• overlay_shown
• overlay_clicked
• overlay_dismissed
• quiz answers, completion, result impressions, and result clicks

Quiz events use stable IDs and remain separate from ordinary overlay clicks so answer selection does not inflate CTR.

Troubleshooting

• Config is empty: check the site ID, active status, target URL/device/location, schedule, and campaign archive state.
• Config exists but nothing renders: check the feature bundle request, content validation, trigger state, frequency storage, and browser console.
• Coupon overlay never appears: an imported coupon it uses has become unavailable; the overlay is suppressed until you select an available code.
• Personalization is blank: confirm consent, identified/device context, allowed surface fields, and exact variable names.
• Preview differs from live: reproduce the live viewport, URL, theme CSS, and trigger sequence; preview PNGs are thumbnails, not runtime proof.
• Video is unavailable: confirm the media asset still exists, the browser supports its codec, and the storefront CSP permits its origin in media-src.