Popups not appearing
Use this when a popup does not show, the wrong one shows, or a blacklisted one still appears.
Many reports that "the popup is broken" describe the popup manager doing what it was built to do. Rule that out first.
Diagnose
1. Rule out expected behaviour. The manager tries the first popup 5 seconds after page load, then checks every 15 seconds. It opens a popup only when nothing else is open and fewer than two have opened on this page view. The 15-second countdown pauses while the tab is in the background. Wait at least 20 seconds with the tab in front before you draw any conclusion.
2. Use a clean browser. Several definitions skip themselves when a Klaviyo profile cookie is present, and the
Klaviyo adapter will not reopen a form Klaviyo has recorded as closed in localStorage. Test in a private window.
3. Turn on logging and reload.
window.enableLogging('popup-logic,need-help-popup-definition');4. Inspect the monitor's state.
window.popupMonitor.getPopups(); // everything registered, highest priority first
window.popupMonitor.getActivePopup(); // what is open now
window.popupMonitor.getCurrentPopupCount();
window.popupMonitor.getMaxPerPage();
window.popupMonitor.canShowPopup();An empty map means nothing registered. A count equal to the maximum means the shopper has already seen two popups on this page view.
5. Check the manager is enabled.
window.theme?.popupManagerConfig;If this is undefined, Enable popup manager is off in theme settings, and snippets/popup-logic.liquid outputs
nothing.
6. Check the blacklist.
window.theme.popupManagerConfig.blacklist;Then look for the style tags Liquid rendered to hide each entry:
document.querySelectorAll('[id^="popup-logic-style-"]');7. For a Klaviyo form, confirm the ID. The snippet builds the hiding selector from the form ID, so a CSS class in the blacklist does nothing for a Klaviyo form. Find the form's ID in the DOM:
document.querySelectorAll('[data-testid^="klaviyo-form-"]');Repair
Nothing registered. The definition is not registered in src/entrypoints/popup-logic.ts. Three definition files are
not registered: global-popup, whose import is commented out, and cash-vouchers and street-sale, which nothing
imports. Registering one of them is a code change, not a settings change.
A blacklisted popup still appears. First check that the entry matches. For Klaviyo, use the form ID alone with type
klaviyo. For a theme popup, use a CSS selector with type custom. Look for stray spaces, because the entry is split
on the comma and each half is trimmed.
If the entry matches and the popup still appears after 5 seconds or more, check whether it is in
window.popupMonitor.getPopups(). When the monitor opens a registered popup, it deletes that popup's hiding style. No
script reads the blacklist, so the monitor does not skip blacklisted popups. For a Klaviyo form, turn the form off or
change its targeting in Klaviyo. For a theme popup, stop registering it in code.
The wrong popup opens first. The order comes from priorities set in code. Each definition file sets its priority, and the Klaviyo sniffer gives detected forms negative priorities. Changing the order is a code change.
A popup flashes, then hides. It rendered before the monitor knew about it, and a sniffer registered it late. Check that Liquid renders a hiding style for it, so it is not visible before the monitor takes over.
The offers link does nothing. This link does not use the definitions. src/entrypoints/klaviyo-popup-trigger.ts
reads window.offerPopupConfig and returns early if either the desktop or the mobile form ID is missing, so check both
Klaviyo theme settings. The link also does nothing while another popup is open, because its popup does not have a higher
priority.
A Klaviyo form opens on every collection page on desktop. An inline script in snippets/popup-logic.liquid opens
the form from the collection's custom.klaviyo_form_id_desktop metafield. It reads a device-specific cookie but always
writes the mobile cookie, so the desktop check never finds a cookie. Clear the collection metafield to stop the popup,
or fix the cookie name in the snippet.
Too many popups. The limit is two per page view, and no setting changes it. The custom.max_allowed_popups
metafield has no effect, because no script reads the value Liquid writes for it. To change the limit, pass maxPerPage
when src/entrypoints/popup-logic.ts constructs PopupMonitor.
Verify
- Open a private window and load the page.
- Wait 5 seconds with the tab in front, and confirm the expected popup opens.
- Close it, wait another 15 seconds, and confirm the next popup behaves as expected.
- Close that one, wait another 15 seconds, and confirm no third popup appears.
- Repeat at mobile width, because desktop and mobile use different Klaviyo form IDs.
- If you changed the blacklist, wait through at least two 15-second checks and confirm the hidden popup never appears.