How widgets load and display
Personizely widgets are delivered with your site's snippet and decided entirely in the visitor's browser. On each page view, every active widget checks its page-level rules, then waits for its trigger, re-checks its audience at that moment and appears. This page explains that sequence and its consequences, so you can predict when a widget will or won't show.
How it works
- The widget is already on the page. Active widgets are part of your site's snippet, so showing one doesn't wait for an extra request. Drafts, paused and ended widgets aren't included. When you start, stop or edit a widget, the snippet is updated within moments.
- Widgets start once the page is ready. A widget that needs visitor data waits for it first: widgets that print Dynamic text (personalization variables) such as {visitor.firstName} or {geo.city}, widgets with prefilled form fields, widgets whose audience uses filters answered by the server (such as visit history or location) and widgets whose audience uses cart filters.
- Page-level rules are checked. Pages, Subdomains, Product pages, Product pages with tags, Frequency, Days of week and Timeframe, plus the widget's start and end dates. If any of them fails, the widget does nothing on this page view.
- Triggers start listening. Each trigger, such as a time delay, a scroll depth or exit intent, waits for its moment. If the widget has a Teaser (minimized widget) set to show before the trigger, the teaser appears now.
- A trigger fires and the audience is re-checked. The Target, Query string and Widget interaction rules are evaluated at this moment, using what's true now, such as the current cart value. If they pass, the widget appears.
- The widget is shown and the view is recorded. The widget's other triggers stop for the rest of the page view. Close triggers start counting.
- Interactions are recorded as they happen: clicks, form submits, wheel spins, coupon copies and applies, countdowns reaching zero. Widget automations run, and goals the visitor reaches later are credited to the widget. See Widget goals and conversions.
Widgets don't run at all for visitors excluded by Traffic filtering and bots, for recognized bots, or while tracking is paused. See How Personizely works.
Once per page view
A widget is shown at most once per page view by its triggers. After it closes, it can only appear again on the same page when:
- the visitor clicks its Teaser (minimized widget);
- your code calls ply.showWidget();
- another widget's Show widget automation automation opens it.
On single-page apps and headless storefronts, each detected page change resets widgets that aren't visible and evaluates them again for the new page. A widget that's open when the page changes stays open.
What's remembered for each visitor
Personizely remembers, in the visitor's browser, how they've interacted with each widget: views, closes, conversions, whether it's minimized to its teaser, the step it was left on, and the variation they were assigned in an experiment. This is what the Frequency rule, Widget steps (multi-step widgets) and Widget A/B testing rely on.
- It's per browser and per domain. The same person on another device or browser, in a private window, or after clearing site data is treated as new.
- Previews aren't remembered and never count toward frequency.
- See Visitor identity, sessions and storage for what counts as a session.
Frequency
The Frequency rule rule limits how often a visitor sees a widget: stop for good, or pause for a period or for the rest of the session, once the widget has been closed, converted, viewed N times or minimized. It's checked at page load, against what's remembered in the visitor's browser, so it's per browser. Views by visitors in an experiment's control group count too, even though they see nothing. The Frequency rule page explains exactly what each setting means for the visitor, what counts as each event and what a session is.
How widgets look on your site
- Widgets inherit some of your site's CSS. Use the widget's custom CSS to override it.
- Popups, callouts, bars and teasers appear above your page content, including sticky headers and other overlays present when the widget opens. Embedded widgets sit in the page flow, inside the element you chose.
- Images are preloaded as soon as the widget is armed, so they appear immediately when it shows. Google Fonts and custom fonts used by your widgets are loaded with the page.
- Scripts in an HTML element don't run. Put JavaScript in the widget's custom code or an Execute JavaScript code automation automation instead.
Accessibility
- Popups keep keyboard focus inside while open: Tab and Shift+Tab cycle through the popup's controls.
- Popups and callouts move focus to their first form field, or to the widget itself if there's no form, when they open.
- Esc closes popups, callouts and bars when Close on Esc is on (the default).
- Focus returns to the element the visitor was on when a widget opened by a Click or Hover trigger closes.
- Give the close button a Label so screen readers announce it. See Widget display options.
Behavior details and limitations
- Rules checked at page load aren't re-checked later on the same page. If a Timeframe ends while a visitor sits on the page, a trigger that fires afterwards still shows the widget. The next page view respects the new time.
- The audience is checked when the trigger fires. A widget targeted at "cart value over $50" with an exit-intent trigger shows if the cart reached $50 before the visitor tried to leave, even if it was empty on page load.
- Several widgets can show at once. Each widget is independent. To avoid a popup opening on top of another, add a Widget interaction rule such as "Don't show if a popup is already open".
- A widget with no trigger never shows by itself. It can still be opened with ply.showWidget() or a Show widget automation.
- Embedded widgets wait for their spot. If the element they go into doesn't appear on the page within 5 seconds, the widget isn't shown on that page view. See Embedded widgets and placeholders.
Showing a widget from code
// Show widget 5521 if its rules pass
ply.showWidget(5521)
// Show it regardless of rules and schedule, on a specific step
ply.showWidget(5521, true, 3)showWidget ignores the widget's triggers. Without the second argument, it checks the schedule and all rules first. See the JavaScript API.
Troubleshooting
- Widget never shows → open the page with ?ply_debug=1 and check the browser console: it logs each rule's result for each widget. Common causes are a Pages pattern that doesn't match (patterns match the path only), a Frequency rule your own browser has already used up (try a private window), or a trigger that can't fire on that page.
- Widget shows on the first page but not after → a Frequency rule is working as configured, or the widget's trigger fired and it was already shown once on that page.
- Widget looks different on the site than in the builder → your theme's CSS is reaching the widget. Override it in the widget's custom CSS.
- Widget appears late → it waits for visitor, company, server-side targeting or cart data, depending on its content and audience. Remove dynamic text or audience filters it doesn't need.
Related
- Widgets