Frequency

Frequency answers: once we know the trigger fired, should this specific visitor actually see the popup, given how often they’ve already seen it? Four modes, configured on the Overview tab in the Frequency & dismissal card.

Frequency types

Once per session (session)

The default. The visitor sees the popup once per browser session. Closing the tab (or letting the session expire) resets the suppression — they see it again on the next visit.

Suppression storage: PHP session always; sessionStorage also when GDPR consent allows. Pick this for one-shot announcements you want every returning visitor to see again on a new visit.

Once every N days (days)

The visitor sees the popup once, then it’s suppressed for N days (set by the Days between shows field). After N days, it can show again.

Suppression storage: localStorage with an expiry timestamp (when consent allows). When consent is withheld, falls back to PHP session (which effectively reverts to session-only suppression for that visitor).

Pick this for periodic nudges where session-only is too noisy but always-on is too aggressive — weekly newsletter prompts, monthly sale reminders.

Always show (always)

No suppression. The popup fires every single time the trigger fires (every page load with immediate, every page that meets a scroll threshold, etc.).

Pick this for cookie banners that legally must show until acknowledged, or for global notices that visitors must explicitly dismiss every time.

Until permanently dismissed (permanent)

The popup shows on every page load until the visitor clicks the Don’t show again button. Once dismissed, it never shows again for that visitor unless they clear their browser storage.

Suppression storage: localStorage with no expiry (when consent allows). When consent is withheld, the dismiss flag is stored in PHP session — which means the permanent setting effectively degrades to “until this session ends”.

Pick this when the popup is informational and should keep nagging until acknowledged (e.g. a top banner about an ongoing maintenance window).

Dismissal controls

Three optional UI affordances that decide how the visitor can dismiss the popup. Toggle them in the Frequency & dismissal card:

Show close (X) button

Renders a small × in the corner of the shell. Clicking it closes the popup and records a close event. Recommended on for accessibility (visitors can always escape).

Close on overlay click

Clicking outside the popup (on the dimmed overlay) closes it. Only meaningful for modal display type — other variants don’t have a click-target overlay. Recommended on for modal.

Show permanent dismiss button

Renders a Don’t show again button that closes the popup AND writes the permanent suppression flag.

Behaviour depends on Frequency:

• Frequency = Always show — the button is disabled in the editor with the help text: “Disabled — frequency is set to ‘Always show’, so the popup re-appears even after a permanent dismiss.” The intent of Always show is to keep appearing; permanent dismiss would contradict it.
• Frequency = Until permanently dismissed — the button is required with the help text: “Required — frequency is set to ‘Until permanently dismissed’, so the popup needs this button to let visitors close it for good.”
• Frequency = Session / N days — the button is optional. When on, clicking it acts like the visitor opted into permanent suppression (overriding the configured frequency for that visitor).

Clicking permanent dismiss records a permanent_dismiss event.

Frequency value semantics

The Days between shows field is visible only when Frequency = Once every N days. Other frequencies hide it.

How frequency interacts with GDPR

Frequency state has to be persisted somewhere. The gdprMode system setting picks where:

• Wait for cookie acceptance (default) — no client storage until the visitor accepts cookies. While consent is missing, suppression lives only in PHP session, which expires when the browser closes. Practical effect: N days frequency degrades to session-only for visitors who never consent.
• Use browser storage — write sessionStorage / localStorage immediately. Frequency works as documented.
• Use cookies — same as storage mode but with cookies.

See Storefront → GDPR & storage for the full picture.

How frequency interacts with display mode

When more than one popup is eligible on the same page, the system-wide Popup display mode decides what happens:

• Only first (highest priority) — only the single highest-priority eligible popup is shown. Other eligible popups are skipped for this page load (but their frequency state is not marked as “shown” — they’ll be considered again on the next page).
• Queue (sequential) — they appear one after the other in priority order, subject to the per-session cap (maxPerSession).

Where to go next

• Triggers — when the popup would fire.
• Storefront → GDPR & storage — exactly where suppression state lives.
• Stages → Popup — close button and overlay click in context of each display variant.