Troubleshooting

When a stage misbehaves, the cause is almost always one of a small set of categories. This page walks through them with a focus on what to check before assuming something is broken.

Stage doesn’t appear in the storefront

This is the most common report. Walk through the filter pipeline from outermost to innermost — /p2lab-stage/resolve filters fail silently (the popup just isn’t returned), so the only way to find the culprit is to check each gate.

1. Is the master switch on?

Settings → Plugins → P2Lab Stage → Popup → Enable popups on storefront. When off, no popup renders on the affected sales channel. Per-channel, so check the right one.

2. Is the stage active?

On the stage’s Overview tab, Active must be on. The list page shows the active state as a column — confirm it’s green.

3. Is the schedule in range?

active_from and active_to are evaluated against server time (UTC). If you set them in your local timezone, double-check the picker isn’t showing local but writing wrong UTC. The detail page’s overview info card shows the configured dates — read what’s actually stored.

4. Does the sales channel match?

Targeting tab → Channels & customer groups → Sales channels — must include the channel you’re testing, or be empty (= all channels). A common mistake: a stage created on Channel A is left empty during testing, then the merchant assigns it to Channel B for production but forgets to remove the empty constraint.

5. Does the customer group match?

Same card. If the visitor’s customer group isn’t in the list (and the list isn’t empty), the stage is filtered out. Anonymous visitors typically fall into the “default” customer group of the sales channel — confirm what that group is.

6. Do the page filters match?

Targeting tab → Pages. Strict opt-in — empty page types AND empty URL patterns means the stage matches nothing. If you set just one axis, the stage fires only when that one matches. With both set, the Pages / URL match operator (OR / AND) determines combination.

Test specifically: what page type does Shopware compute for the URL you’re visiting? It’s not always obvious — /cart is cart, /checkout/cart might also be cart, but /checkout/confirm is checkout. Inspect the data container in the footer ([data-p2lab-stage-context]) to see what page type the storefront thinks it’s on.

7. Do the rules evaluate?

If rules are set, the visitor’s context must satisfy them per the rule operator. Test with rules removed first — if the stage shows without them, you know which axis to debug.

8. Is the visitor already suppressed?

Open DevTools → Application → Storage:

• sessionStorage — entries prefixed p2lab-stage- indicate session-level suppression.
• localStorage — entries prefixed p2lab-stage- with a value containing an expiry timestamp indicate days/permanent suppression.

Clear them and reload. If the popup now appears, the issue is frequency suppression — either the visitor saw it already, or someone else on the same browser did.

For a clean test, use a private/incognito window or a different browser profile.

9. Is GDPR consent gating storage?

In consent mode, the plugin doesn’t write to sessionStorage / localStorage until cookie acceptance fires. The dismiss state lives in PHP session, which is invisible in DevTools. Hit GET /p2lab-stage/dismissed directly to see what the server thinks is suppressed.

10. Did the trigger fire?

If everything matches but the popup still doesn’t show:

• immediate — should mount on page load. Check the DevTools console for JS errors.
• delay — wait at least triggerValue seconds. Common mistake: testing a 60-second delay and giving up after 5.
• scroll — verify you scrolled past triggerValue% of the page. On short pages this might be impossible (a 100% page is shorter than the viewport).

11. Inspect the resolve response

The decisive check. Open DevTools → Network, filter for resolve, find the POST to /p2lab-stage/resolve. The response’s popups array is the ground truth: if your stage isn’t in it, one of the filters (1–9) rejected it.

Animation glitches

Layers jump or snap instead of animating smoothly

Likely cause: conflicting transforms on a parent element. Mouse parallax adds transform: translate3d(...) rotate3d(...) to .p2lab-stage__layer-wrap. If a parent (e.g. a scene wrapper) is also being transformed by timeline keyframes, the compose order matters.

Fix: animate the leaf layer instead of the container, or disable parallax on the conflicting layer.

Animation runs once and stops

Likely cause: Loop toggle is off on the timeline. Click Loop in the timeline header. For scenes that should keep cycling regardless of the root timeline, the scene’s row has a separate Scene loops independently toggle.

Animation starts but layer disappears mid-frame

Likely cause: opacity keyframe drops to 0 at some point. Check the opacity track for the layer; ensure no keyframe sets opacity to 0 when you didn’t intend it.

Parallax flickering

Subtle jitter on every mouse move

Likely cause: intensity too high + low depth values. The engine snaps to subpixel precision; very small values combined with high intensity can produce visible jitter on some GPUs.

Fix: reduce intensity (Stage Settings → Parallax), or increase depth/tilt values per layer.

Parallax doesn’t engage at all

Walk through these:

1. Visitor isn’t using a touch device (parallax is disabled on coarse pointers).
2. prefers-reduced-motion: reduce isn’t set in OS preferences.
3. The layer has Parallax effect enabled in Layer Style.
4. Both depth and tilt aren’t both 0.
5. Stage intensity isn’t 0.

Theme CSS conflicts

Plugin styles look wrong on one theme but not another

Likely cause: theme overrides CSS variables the plugin expects. Open DevTools → inspect .p2lab-stage__shell, look at the Computed tab. If --p2lab-stage-shell-* variables show values you didn’t pick, the theme is overriding them.

Fix: scope the override in your theme to non-plugin selectors, or set the variables back to the desired values inside .p2lab-stage.

Z-index battles with a sticky header

By default the plugin uses z-index: 9999. If the theme has anything higher (some headers use z-index: 999999), the popup will be hidden behind it.

Fix: bump the plugin’s z-index in your theme (--p2lab-stage-z), or lower the header’s z-index when a popup is visible.

Events / statistics

Stats tab shows zeros

Walk through:

1. Is Track statistics on (Overview tab → Statistics card)?
2. Is the date range correct? Default is the configured retention window — if retention is 90 days but you want to look at month 6, you won’t find it.
3. Did anyone visit the storefront after activating the stage? Stats appear only after real impression events.

cta_click count looks too low

CTA clicks fire only on button layers and layers with Click action enabled. Plain text / image layers without click action don’t count. If you expected them to, enable click action on those layers in Layer Style.

Where to go next

• System config — every system setting.
• Storefront → How stages render — the full pipeline.
• Storefront → GDPR & storage — where suppression actually lives.
• Analytics → Events — what each event records.