Help › Triggers and rules
Triggers and rules
A trigger is the moment the overlay appears. Several can be active; the overlay appears at most once per page view.
The triggers
| Trigger | Detects | Best for |
|---|---|---|
| Exit intent | The mouse moves up out of the window to the browser bar and stays there for a minimum time. Optionally only at the top left (back button, tabs), only at the top right (close button on Windows and Linux) or in both corners. If the mouse was idle for a long time before (screen saver), leaving does not count | Desktop |
| Fast scroll up | A quick upward flick, measured over a quarter of a second; a lower threshold applies on desktop | Mobile, desktop too |
| Time on page | The visitor has been on the page for a certain time; time in a background tab doesn't count | All |
| Inactivity | No mouse, no typing, no scrolling for a while | All |
| Scroll depth | A share of the scrollable distance has been reached; short pages don't trigger | Long pages, guides |
| Page count | From the nth page in a visit; requires “session” or “persistent” storage | All |
| Return to tab | The visitor comes back after the tab was in the background for at least a while (another tab, another app) | All, especially comparison shoppers |
| Back button | The visitor returns to a page with the back button; the overlay appears there after a minimum time at the earliest. The browser history is never changed, the back button always works normally | All |
| Custom triggers | Your website calls ChurnReturn.trigger('name'), for example when the cart is emptied. Enter the names under “Custom triggers”; once any are entered, only those fire | Shops with their own logic |
Try the triggers
Under Try the triggers, every trigger of the demo has its own page: only that trigger is armed there, the page tells you what to do to fire it, and a status line shows live what the script is doing. It works the same way on your own website: add ?cr_trigger=exit_intent (or another type; for custom triggers cr_trigger=custom:name) to the address of a page, and only that trigger is armed while all others stay off, including on the following pages in that tab; ?cr_trigger=all reverts this. That way you can test each one individually without time on page or inactivity getting in the way. The parameter isn't part of the page and doesn't affect product detection.
Single-page applications and anchor links
If your website changes pages without reloading (React, Vue, Shopware Storefront with the History API), the script detects the change via pushState, replaceState and the back button: the overlay disappears, timers and triggers restart, the URL rules apply to the new address, and the page count keeps counting. If your router doesn't use the History API, call ChurnReturn.pageview() after each change. Fast scroll up only counts real input with the mouse wheel or a finger; anchor links, “back to top” buttons and smooth scrolling by script don't trigger anything.
Levels
Each trigger has four levels. “Slow” triggers rarely and late, “fast” early and often. The dashboard explains in plain words under each level what it means for that trigger. We recommend starting with “normal”.
| Level | Time on page | Inactivity | Scroll depth | Page count | Exit intent, minimum time |
|---|---|---|---|---|---|
| 1 slow | 120 s | 90 s | 90 % | from 5th page | 8 s |
| 2 calm | 75 s | 60 s | 80 % | from 4th page | 5 s |
| 3 normal | 45 s | 30 s | 70 % | from 3rd page | 3 s |
| 4 fast | 20 s | 15 s | 50 % | from 2nd page | 1.5 s |
Devices
Each trigger applies to desktop and mobile, desktop only or mobile only. Mobile means a device with touch input or a width of less than 768 pixels. Defaults: “Exit intent” desktop only, “Fast scroll up” mobile only.
Priority
If two triggers fire at the same moment, the one higher up wins: exit intent before fast scroll up before time on page before inactivity before scroll depth before page count. The overlay itself opens only once per page view, even if more triggers fire afterwards.
Frequency
“Pause after showing” in minutes and “Max per day” limit how often a visitor sees the overlay. Both require storage in the browser, see Privacy and consent. Without storage, this protection only applies within a single page view.
Safeguards
Under “Triggers & rules”, they apply to all triggers, including custom ones:
- Not while typing (on by default): while the cursor is in a text field, such as search, the address form or a coupon code, nothing fires.
- Only for visitors from outside (off by default): the overlay only appears on the landing page of visitors who come from outside (ads, search, partner links, typed address). Visitors who click on within the shop no longer see it. The “Page count” trigger then has no effect.
- Focus on “Close” (on by default): when the overlay opens, keyboard focus moves to the close button and returns when it closes. Important for keyboard and screen reader users.
- Not over other windows: while an element matching the CSS selectors you entered is visible, such as an open cart or the cookie banner, nothing fires.
Regardless of these settings, nothing ever fires while the tab is in the background.
Where the overlay appears
Under “Triggers & rules” in the card “Where the overlay appears”: Only show on (empty = all pages) and Never show on by address, see URL rules below. In addition by page content with CSS selectors: Only on pages with this element, such as .product-detail for product pages only, and Never on pages with this element, such as .checkout-step or your own marker like <div data-no-churnreturn>. When a trigger fires, the snippet checks whether a matching element is on the page, visible or not; this also works in single-page shops. An invalid selector has no effect.
URL rules
Regular expressions on the path and query of the page, one rule per line. Examples:
| Rule | Effect |
|---|---|
/checkout | all addresses containing “/checkout” |
^/$ | exactly the home page |
^/en/ | everything under /en/ |
[?&]utm_source=newsletter | visits from the newsletter |
Never show on: typically cart, checkout, account, order confirmation. Only on the first visit of the day: pages where the overlay should appear only once a day on the first load, such as the home page. This also requires storage in the browser.
Next: Designing the overlay →