Popup shows at the wrong time

Use this runbook when two popups overlap, when a popup never appears, when one appears more often than expected, or when a popup flashes and disappears.

The theme's popup manager coordinates popups from several sources. Most problems come from the manager being switched off, or from a popup the manager does not track.

Expected behaviour

The manager shows at most two popups per page view, one at a time. The first is offered five seconds after load, and the timer offers the next one every fifteen seconds, restarting whenever a popup closes.

A higher-priority popup replaces a lower-priority one that is already open. A popup marked to force itself open bypasses the per-page limit.

Diagnose

1. Confirm the manager is running

window.popupMonitor;

undefined means the manager never initialised. Either Enable popup manager is off in Theme settings under Popup Manager, or the bundle failed to load.

2. Inspect the manager's state

[...window.popupMonitor.getPopups().keys()];
window.popupMonitor.getActivePopup()?.getId();
window.popupMonitor.getCurrentPopupCount();
window.popupMonitor.getMaxPerPage();
window.popupMonitor.canShowPopup();

A popup that is misbehaving and does not appear in the first list is not being managed at all. Go to Repair, case A.

3. Watch the decisions

https://beautyaffairs.com.au/?ba_debug=popup-logic,need-help-popup-definition

Reload and wait thirty seconds. The log records which popup was offered, whether it was shown, and when the timer reset.

4. Check the page type rules

The sitewide signup popup is suppressed on MediSpa pages, and the MediSpa signup popup is suppressed everywhere else.

document.body.classList.contains('template-medispa-v2');
document.body.classList.contains('medispa-lp');
window.PDP?.productData?.vendor;

A page counts as MediSpa when either class is present or the vendor name contains medispa. A product from a MediSpa vendor on an otherwise normal template counts as MediSpa, which is easy to miss.

5. Check the market mapping

Klaviyo form IDs for the signup popup are mapped per market with a default fallback. A market with no entry gets the default form rather than no popup.

The mapping is in src/components/popup-logic/definitions/sign-up-forms.ts. Confirm the ID the log reports matches a form that still exists in Klaviyo.

6. Check the blacklist

window.theme?.popupManagerConfig;

The blacklist hides listed popups before the page renders. A popup that never appears at all may be listed here. Each line is selector,type, where a Klaviyo selector is the form ID.

Repair

Case A: a popup the manager does not know about

The manager detects popups through two sniffers, one for Klaviyo and one for theme popups. A popup from a different source is invisible to it and will overlap with managed popups.

Either add it to the blacklist so it never shows, or register it with the manager by adding a definition under src/components/popup-logic/definitions/.

The blacklist is the faster fix and needs no deploy. Instructions are in Popups and forms.

Case B: a popup never appears

Work through these in order.

Confirm the manager is enabled in Theme settings.

Confirm the popup is not in the blacklist.

Confirm the page type rules do not suppress it (step 4).

Confirm the two-popup limit has not already been used. getCurrentPopupCount() returning 2 explains it.

Confirm the Klaviyo form still exists and is published, using the ID from the log.

Case C: a popup appears too often

The theme tracks popup frequency per browser through localStorage, so a developer reloading repeatedly sees different behaviour from a customer. Test in a fresh private window.

If it repeats within one page view, check for a second PopupMonitor instance. The bootstrapping code assigns one to window.popupMonitor, and a second copy of the bundle would create another.

Case D: a popup flashes then disappears

The manager renders a server-side style tag per popup to keep it hidden until it decides, then removes that tag when it shows the popup. A flash means the popup became visible before the style tag was in place, usually because the popup's own script ran before the manager initialised.

Add the popup to the blacklist, which hides it before the page renders, then register it properly.

Case E: the wrong popup wins

The manager chooses by priority. A higher-priority popup replaces a lower-priority one.

[...window.popupMonitor.getPopups().values()].map((p) => [p.getId(), p.getPriority()]);

Adjust the priority in the popup's definition file. This needs a rebuild and a deploy.

Verify

1. Open the storefront in a fresh private window.
2. Wait five seconds. Confirm exactly one popup appears.
3. Close it. Wait fifteen seconds. Confirm exactly one more appears.
4. Close that one. Wait thirty seconds. Confirm no third popup appears.
5. Repeat on a MediSpa page and confirm the MediSpa signup popup appears there instead.

Escalate

Popup content, targeting rules and audience belong to Klaviyo. The theme controls only whether a popup may open at a given moment.

Background is in Popups and forms.