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

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.