Understanding Lightbox Display Rules

The Lightbox Display Rules feature allows you to control when, where, and to whom a lightbox is shown.

Note: The display rules are only available if you have selected Web Event as your launch method. See our lightbox publishing guide for more information.

By combining different rules, you can create targeted Experiences that are relevant to your users, avoiding overexposure and driving positive interaction.

This article explains each display rule available in the Lightbox Rule Builder and how it controls when your lightbox appears, as well as how to use display rules so that you can set the conditions under which your lightbox will appear.

How display rules work

Display rules are organised into four categories:

  • Who – Which users should see the lightbox

  • Where – Where the lightbox should appear

  • When – When or how it is triggered

  • How often – How frequently it is shown

You can combine rules using AND / OR logic and group them together to create more advanced targeting scenarios.

  • Match All (AND) – Every rule must be true for the lightbox to display

  • Match Any (OR) – At least one rule must be true

Note: You can add multiple rules and rule groups to create more advanced targeting logic for different visitor behaviors or scenarios.

Operators

Each rule uses operators to define the condition.

Common operators include:

  • Text operators: Contains, Starts with, Ends with, Equals

  • Numeric operators: Greater than, Less than, Between

  • Multi-value operators: Equals any of, Contains any of

  • Negative operators: Does NOT contain, Does NOT equal

  • Existence operators: Exists, Does NOT exist

Note: Available operators vary depending on the rule type.

Who

Use Who rules to target visitors based on what you know about them. These rules can use data such as UTM parameters or browser storage to determine whether a visitor matches your audience criteria.

For example, you might use Who rules to show a lightbox asking for a phone number to visitors who have not already opted in to your SMS marketing program.

JavaScript

Many websites expose information about the current user or session using JavaScript variables (for example, whether a user is logged in or what type of customer they are). This rule allows you to use that information for targeting.

This will check the value of a JavaScript variable on the page/browser and displays the lightbox if it matches your rule.

Note: We only recommend using these if you have experience with JavaScript code.

JavaScript variable

Triggers the lightbox based on a variable value in the browser.

For example, you can use this to show the lightbox when isLoggedIn = false.

JavaScript function

Use JavaScript Function when you need more advanced or custom conditions that cannot be handled with standard rules; instead of checking a single value, this rule lets you define logic that evaluates multiple conditions together.

Note: This rule may require updates to your Content Security Policy (CSP) settings.

Referrer and web source

Define rules based on where they came from.

Search engine

Targets users based on the search engine used (for example, Google or Bing).

This allows you to customize your messaging for search traffic and show introductory messaging to users from a specific engine, such as Google search.

Web source

Targets users based on where they came from; the platform analyses the referrer and categorises it into source types such as direct traffic, organic search, paid ads, or social.

For example, you could show a discount offer only to those arriving from paid campaigns.

UTM parameters

UTM parameters are appended to URLs (for example, in emails or ads), and this rule reads those values to determine targeting. This rule checks the UTM parameters present in the page URL to identify the marketing campaign that brought the user to the site.

Campaign tracking parameters can include:

  • Campaign name

  • Source

  • Medium

  • Term

This is useful for targeting specific campaigns, such as email or paid media.

Storage-based targeting

These rules target users based on stored browser data.

Cookie values

Cookies store user information across sessions, allowing you to recognize returning users and track past behavior. This rule checks whether a specific cookie exists in the user’s browser and optionally evaluates its value.

This can be used to prevent showing lightboxes repeatedly.

Local storage

Local storage can store larger amounts of data than cookies and remains available even after the browser is closed. These rules read values stored in the browser’s local storage, which persists across sessions, allowing you to track long-term user behavior.

Session storage

Session storage resets when the browser tab or session ends, therefore it will reads values stored for the current browsing session only.

This can be used to control lightbox behavior within a single visit.

Where

Use Where rules to control where the lightbox can appear. These rules define the page, URL or device where a visitor must be for the lightbox to qualify.

For example, you might use Where rules to show a lightbox only on checkout pages.

URL Targeting

Target users based on values within the URL.

  • Current page URL - Matches the URL of the page the user is currently viewing to target specific pages or sections of your site.

  • Landing page - Identifies the first page the user visited during their session to personalize experiences based on how users entered your site

  • Referring website - Checks the URL of the external site the user came from which is then analyzed against your rule conditions. This allows you to tailor experiences based on external traffic sources

  • URL path, host, or query string - Allows targeting based on specific parts of the URL such as /blog, e.g. for more precise targeting beyond full URL matching

  • Pages visited during the session - Tracks the pages a user has visited during their current session; the system builds a list of visited URLs, checks it against your rule conditions, and triggers based on browsing behavior and engagement

Device targeting

Target users based on:

  • Device type - identifies whether the user is using a mobile device, tablet, or desktop to tailor experiences to device type

  • Browser (Chrome, Safari, Firefox, etc.) - Identifies the web browser being used to handle browser-specific behaviour or targeting if needed

  • Operating system (Windows, macOS, Linux) - Detects the user’s operating system for OS-specific use cases or targeting scenarios

When

Use When rules to control timing or behavior that triggers the lightbox. These determine when the visitor should see the lightbox based on actions or conditions such as time on page, idle behavior, or exit intent.

User actions

These are based on user behavior or their interaction with the site.

  • HTML/CSS selector - This rule checks the page for matching HTML or a CSS selector. If the matching content or element is found, the lightbox can appear.

Date-based rules

Controls when a lightbox is active based on date conditions which allows you to display seasonal campaigns during specific date ranges. Examples include, but are not limited to:

  • Show on a specific date

  • Show within a date range

  • Use conditions such as before, after, or between dates

Visitor history

Target based on user engagement:

  • Page views (lifetime) - Tracks the total number of pages a user has viewed across visits to target based on overall engagement

  • Page views (session) - Tracks the number of pages viewed in the current session to trigger a lightbox based on current engagement

  • Past visits - Tracks how many times a user has visited your site to differentiate between new and returning visitors

  • Days since last visit - Measures how long it has been since the user last visited your site to trigger a "welcome back" campaign, for example.

These rules help tailor experiences based on user activity.

Frequency capping

Frequency capping controls how often a visitor can see the same lightbox. This helps prevent the experience from feeling repetitive or intrusive.

After you define Who, Where, and When a lightbox should appear, use frequency capping to decide how often it can be shown to the same visitor. For example, only per visitor or once every 30 days.

This is useful when you want to avoid showing the same message too often, especially for returning visitors or visitors who continue browsing after dismissing the lightbox.

Options include:

  • Always show - Lightbox appears every time the visitor meets the targeting rules.

  • Once - The lightbox appears only one time for each visitor.

  • Once per visit - The lightbox can appear once during each visit or session.

  • Once per X days - The lightbox can appear once within a custom number of days.

  • Once per week - The lightbox can appear once per week for each visitor.

  • Once per month - The lightbox can appear once per month for each visitor.

For example, you can limit a lightbox to display once per session to avoid overexposure. These rules are used with the aim of avoiding repeatedly showing the same message.