Widget triggers
A trigger decides the moment a widget appears: as the visitor lands, after a delay, at a scroll depth, on exit intent, after a period of inactivity, on a click or hover, when they add a product to the cart, or when they head to checkout. Rules decide whether the widget may appear at all; the trigger decides when. A widget can have several triggers, and the first one to fire wins.
Available on: all platforms. Adding to cart and Proceeding to checkout need Shopify, Shopify Hydrogen or Wix.
How it works
- The page loads. Personizely checks the widget's schedule (start and end date) and its page-load rules, such as Pages, Frequency and Timeframe. If any of them fails, the widget's triggers don't start on this page.
- The triggers start listening. Every trigger on the widget listens at the same time. Widgets whose content or audience needs visitor, company or cart data start once that data has loaded.
- A trigger fires. Its conditions are checked first. Then the Target, Query string and Widgets interaction rules are checked at that exact moment.
- The widget is shown if everything passes, and all of the widget's triggers stop for the rest of the page view.
Triggers are set per widget on the widget's page, in the Triggers card ("The moment when the widget shows up"). Click Add trigger and pick a type.
Trigger types
Trigger | Fires when | Default | Conditions available | Platforms |
|---|---|---|---|---|
The page has loaded and the rules have passed | — | None | All | |
The visitor has spent Delay seconds on the page, or on your site within a session | 7 s | Max scroll reached | All | |
The visitor scrolls to Scroll distance percent of the page | 30% | Time spent | All | |
The visitor is about to leave the page | Sensitivity 10 px | Both | All | |
The visitor does nothing for Timeout seconds | 10 s | Both | All | |
The visitor clicks an element that matches a CSS selector | — | Both | All | |
The mouse pointer moves onto an element that matches a CSS selector | — | Both | All | |
The visitor adds a product, or one of the products you picked, to the cart | Any product | Both | Shopify, Hydrogen, Wix | |
The visitor starts checkout | — | Both | Shopify, Hydrogen, Wix |
To close a widget automatically after it has appeared, use close triggers.
Trigger conditions
Conditions narrow down when a trigger counts. They're optional, and they're checked at the moment the trigger fires.
Condition | Passes when | Options |
|---|---|---|
Time spent on current page | The visitor has been on this page more (or less) than N seconds | Relative to the whole session: compares the total time on your site in this session, including the current page, instead, shown as Time spent during session |
Max scroll reached | The furthest point the visitor has scrolled to on this page is more (or less) than N% | — |
- All conditions must pass. If you add both, the widget shows only when both are true at the moment the trigger fires.
- "Max scroll reached" uses the deepest scroll, not the current position. A visitor who scrolled to 80% and back to the top has still reached 80%. A page too short to scroll counts as 100% scrolled.
- "Time spent during session" counts the whole session. It's the total time on your site in this session, including the current page.
- A failed condition doesn't always end the trigger. Event-based triggers (Scroll, Exit, Inactivity, Click, Hover, Adding to cart) check again the next time their event happens. The Time trigger fires once per page, so if its condition fails, it doesn't try again. On Shopify, Proceeding to checkout only reacts to the first checkout attempt on a page.
One show per page view
Once any trigger has shown the widget, every trigger on that widget stops until the next page load. Closing the widget doesn't re-arm them. On the same page, the widget can only appear again through:
- its teaser, when the visitor clicks it;
- the JavaScript API (ply.showWidget);
- a Show widget automation in another widget.
Use the Frequency rule to control how often the widget appears across pages and sessions.
Which rules are checked when
Rules aren't all checked at the same time, which matters for triggers that fire long after the page has loaded, such as Exit or Inactivity.
- Page-load rules (schedule, Pages, Product pages, Product pages with tags, Subdomains, Frequency, Days of week, Timeframe) decide whether the triggers start, and aren't re-checked later on the same page. If a Timeframe ends while the visitor is still on the page, the trigger can still show the widget.
- Trigger-time rules (Target, Query string, Widgets interaction) are checked when the trigger fires, so they see the latest data, such as products added to the cart since the page loaded.
See Rules for the full table.
Manual trigger
You can show a widget from your own code or from another widget, regardless of its triggers.
- JavaScript API: ply.showWidget(id, suppressRules?, step?) returns a promise that resolves to a truthy value when the widget is shown. See the JavaScript API.
- Show widget automation: an element in another widget, such as a button, opens this widget. See Show widget.
Both ignore the widget's own triggers. By default they still check the schedule and all rules; set suppressRules to true (or tick Suppress rules in the automation) to skip them. The widget must be active.
document.querySelector('#open-size-guide').addEventListener('click', (e) => {
e.preventDefault()
ply.showWidget(5521, true)
})Behavior details and limitations
- Several widgets can show on the same page. Each widget's triggers are independent. To stop a popup from opening on top of another, add a Widgets interaction rule such as "Don't show if a popup widget is already open".
- Widget A/B tests. Triggers and close triggers are set per variation; rules are shared by all variations. Visitors in the control group see nothing, but a view is recorded for them when any trigger from any variation fires. See Widget A/B testing.
- Minimized widgets. While a widget is minimized to its teaser, its triggers don't run; the teaser shows on every page until the visitor clicks it. See Teaser.
- Single-page apps. On themes that change pages without a full reload, triggers reset with each detected page change, unless the widget is open at that moment.
- Filtered traffic. Visitors excluded by traffic filtering don't see widgets at all.
- Preview ignores triggers. A preview link shows the widget straight away, whatever its triggers and rules.
Examples
- Welcome offer: Landing trigger, Frequency "Show only once per session", Target "first visit".
- Engaged readers: Time trigger of 20 seconds with the condition "Max scroll reached more than 50%".
- Two ways in: Exit trigger for desktop plus Scroll trigger at 60% for mobile on the same widget. Whichever fires first shows it.
Troubleshooting
- Widget never appears → a page-load rule failed. Open the page with ?ply_debug=1 and check the console for each rule's result.
- Widget appears once, then not again after closing → expected: triggers stop after the first show on a page. Use ply.showWidget for elements that should reopen it every time.
- Widget shows outside its timeframe → the visitor loaded the page inside the timeframe; page-load rules aren't re-checked later.
- Two popups open at once → add a Widgets interaction rule to one of them.