Overlay Campaigns

Overlays render site-targeted banners, popups, modals, capture forms, offers, quizzes, and recommendation blocks through the browser SDK.

Create the campaign

1. Open Dashboard → Overlays and create a campaign.
2. Choose the target site and a built-in or merchant template.
3. Give the campaign an operational name that identifies audience and goal.
4. Build content from supported blocks such as text, image, video, product, recommendations, CTA, coupon, countdown, email capture, spacer, or governed custom HTML.
5. Set style, layout, close behavior, and responsive presentation.
6. Save as Draft while you configure delivery.

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 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

Common triggers include page load or delay, scroll, exit intent, URL conditions, and behavioral rules supported by the editor.

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

The editor rejects an ALL set of URL rules that cannot possibly match the same page. Configure frequency caps deliberately so previews and repeated QA visits do not look like targeting failures.

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.

Submissions and measurement

Capture blocks submit through /api/v1/overlay-submissions; authorized merchants can list and export submissions. 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 site key, 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.
• 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.