- What's in This Guide
- URL Conditions
- URL Is
- URL Contains
- URL Begins With
- URL Ends With
- URL Regex Search
- Query Argument Exists
- Query Argument Is
- Browser Conditions
- Device Conditions
- Cookie Conditions
- HTML Conditions
- Keyboard Conditions
- Referrer Conditions
- User Conditions
- Custom Conditions
What’s in This Guide #
The Advanced Targeting Conditions (ATC) extension gives you powerful ways to target your popups. With this comprehensive toolkit, you’ll get advanced URL targeting, browser detection, device targeting, user behavior tracking, and more sophisticated options to “wow” the right visitors at exactly the right time.
This guide covers the settings for all targeting conditions in the ATC extension. You’ll read how to use each setting for the following high-level use cases:
- Target specific URLs and URL patterns
- Detect browsers and screen sizes
- Track user behavior and roles
- Target specific devices and brands
- Use referrer conditions
- Work with cookies
- Target HTML elements
- Use keyboard triggers
- Create custom conditions
Each section includes a description of how the condition works, settings you can configure, and examples of using each setting (where applicable).
URL Conditions #
URL Is #
Your popup will appear when the page URL matches exactly what you’ve entered in the setting field.
Target any URL on your website. This is perfect for those unique pages that don’t fit the standard targeting conditions.
Settings #
- Exact URL: Enter the URL exactly, including “http://” and “https://” protocols.
Examples #
- Good: https://example.com/products/coffee-maker
- Bad: example.com/products/coffee-maker (missing protocol)
URL Contains #
Your popup will appear on any page where the URL contains the text you’ve entered.
Want to show your popup across multiple pages? This condition lets you target entire sections of your site at once. This is excellent for focusing on specific categories or directories.
Settings #
- Contains: Type in text or character that’s within a URL on your website.
Examples #
- Good: /products/ (matches any page under the
/products/
directory such as https://example.com/products/any-page) - Bad: https://example.com/products (don’t need to include the full URL)
URL Begins With #
Perfect for targeting subdomains or specific sections of your site.
Settings #
- Begins With: Enter what the URL begins with, including the protocol (
http://
orhttps://
) and domain.
Examples #
- Good: https://wppopupmaker.com/blog/ (matches all blog posts)
- Bad: blog (missing the protocol and domain)
URL Ends With #
Need to target any page that ends in a specific pattern or word? This condition is your go-to solution for showing popups on pages with particular endings.
Settings #
- Ends With: Type what the URL ends with.
Examples #
- Good: -blackfriday/ (matches any post or page that ends with -blackfriday)
- Bad: https://mycoolstore.cc (this is how URLs begin, not how they end)
URL Regex Search #
Your popup will display based on the regular expression pattern you enter.
If you’re comfortable with regular expressions, you’ll love the flexibility this condition offers for precise popup targeting.
Settings #
- Valid RegExp: Enter your valid Regular Expression.
Examples #
- Good: ^/products/[0-9]+$ (matches URLs like /products/123)
- Bad: products/[0-9]+$ (missing start anchor ^)
Query Argument Exists #
This condition triggers your popup when a specific query argument exists in the URL.
Here’s a powerful way to launch a popup based on whether or not a URL has a query argument (i.e., parameter).
New to query strings? No worries! Check out Wikipedia’s beginner-friendly introduction, explore some practical examples on W3Schools, or learn how to write them correctly in this guide about valid query string parameters.
Settings #
- Argument Name: Enter only the argument name in this field. The placeholder text is just an example of what a full query parameter looks like.
Examples #
- Good: hello (matches example.com/page?hello)
- Bad: ?hello (including the question mark is incorrect)
Query Argument Is #
Need to target a specific subset of visitors? This condition helps you narrow down your audience when a simple query check isn’t enough.
Settings #
- Argument Name: Type only the argument name. The placeholder text is just an example of what a full query parameter looks like.
- Argument Value: Type only the argument value.
Examples #
Argument Name #
- Good: source (matches example.com/page?source=)
- Bad: ?source (including the question mark is incorrect)
Argument Value #
- Good: newsletter (matches example.com/page?source=newsletter)
- Bad: ?newsletter (including the question mark is incorrect)
Browser Conditions #
Browser conditions let you show popups to visitors based on their browser type, version, and window dimensions.
Is Specific Browser #
Your popup will appear when visitors use specific web browsers you select. To add more than 1 browser, click next to the browser you added before to get the dropdown again.
Settings #
- Select Browsers: Choose from Internet Explorer, Firefox, Safari, Chrome, Android Browser, and Opera.
Examples #
- Good: Chrome (popup displays only on Chrome browsers)
- Bad: Internet Explorer, Firefox, Safari, Chrome, Android Browser (to include all but one browser, such as Opera, it’s easier to click the exclamation icon
and choose Opera)
Version Is #
Show popups depending on browser versions.
Settings #
- Higher Than: Enter a minimum browser version number. This will make your popup show for browser versions (strictly) higher than the version you enter, regardless of the browser brand/product.
- Lower Than: Enter a maximum browser version number. This will make your popup show for browser versions (strictly) lower than the version you enter, regardless of the browser brand/product.
Examples #
Higher Than #
- Good: 135 (shows popup for any browser version greater than 135, such as version 135.0.7049.84)
- Bad: 1 (too general to be useful)
Lower Than #
- Good: 137.415 (shows popup for any browser version less than 137.415, such as version136)
- Bad: 5 (too low for most modern browsers, so your popup will never display)
Browser Width #
Display popups depending on how many pixels wide the browser is. Use this condition if you’re working with exact pixel width breakpoints. Otherwise, use Device Conditions to target any mobile device, smartphone only, or tablet only.
Settings #
You can enter More Than (min value), Less Than (max value), or both (range).
- More Than (optional): Enter a minimum pixel width. This will make your popup show for browser widths (strictly) higher than the number you enter.
- Less Than (optional): Enter a maximum pixel width. This will make your popup show for browser widths (strictly) lower than the number you enter.
Examples #
More Than #
- Good: 1024 (desktop width)
- Bad: 8000 (too wide, so your popup will never display)
Less Than #
- Good: 768 (small tablets and handphones)
- Bad: 100 (too narrow, so your popup will never display)
Browser Height #
Display popups depending on how many pixels high the browser is.
Settings #
You can enter More Than (min value), Less Than (max value), or both (range).
- More Than (optional): Enter a minimum pixel height. This will make your popup show for browser heights (strictly) higher than the number you enter.
- Less Than (optional): Enter a maximum pixel height. This will make your popup show for browser heights (strictly) lower than the number you enter.
Examples #
More Than #
- Good: 756
- Bad: 2000 (too high, so your popup will never display)
Less Than #
- Good: 525
- Bad: 100 (too short, so your popup will never display)
Device Conditions #
Show popups to people who are on any mobile device, smartphone only, tablet only, or even specific screen dimensions. If you’ve got a popup you only want to show on mobile devices, this is for you.
Device Is Mobile #
Your popup will appear when visitors use any mobile device, including phones and tablets.
Device Is Phone #
Show a popup to visitors specifically using smartphones.
Device Is Tablet #
Show a popup to visitors using a tablet.
Screen Width #
Settings #
You can enter More Than (min value), Less Than (max value), or both (range).
- More Than (optional): Enter a minimum pixel width. This will make your popup show for screen widths (strictly) higher than the number you enter.
- Less Than (optional): Enter a maximum pixel width. This will make your popup show for screen widths (strictly) lower than the number you enter.
Examples #
More Than #
- Good: 1024
- Bad: 8000 (too wide, so your popup will never display)
Less Than #
- Good: 768 (small tablets and handphones)
- Bad: 100 (too narrow, so your popup will never display)
Screen Height #
Settings #
You can enter More Than (min value), Less Than (max value), or both (range).
- More Than (optional): Enter a minimum pixel height. This will make your popup show for screen heights (strictly) higher than the number you enter.
- Less Than (optional): Enter a maximum pixel height. This will make your popup show for screen heights (strictly) lower than the number you enter.
Examples #
More Than #
- Good: 756
- Bad: 2000 (too high, so your popup will never display)
Less Than #
- Good: 525
- Bad: 100 (too short, so your popup will never display)
Device Is Brand #
Show popups for specific device manufacturers and brands.
Settings #
- Select Brands: Choose from iPhone, BlackBerry, HTC, Nexus, Motorola, Dell, Samsung, and LG.
Examples #
- Good: iPhone
- Bad: iPhone, HTC, Nexus, Motorola, Dell, Samsung, LG (to include all but one brand, such as BlackBerry, it’s easier to click the exclamation icon
and choose BlackBerry)
Cookie Conditions #
Cookie conditions let you show popups to people based on what cookies they have in their browser.
Cookie Exists #
Check if a specific cookie is in the visitor’s browser before showing your popup. Use this condition if you’re creating cookies on your site to keep track of what your visitors do or take advantage of cookies set by WordPress or other plugins.
Settings #
- Cookie Name: Enter the name of the cookie to check.
Examples #
- Good: pdf-downloaded (name of a cookie that you might set to keep track of when your visitors download a free PDF)
- Bad: wordpress_logged_in (incomplete because it’s missing the long “random” number that’s different for everybody)
Cookie Value Is #
Target based on specific cookie values.
Settings #
- Cookie Name: Enter the cookie name.
- Cookie Value: Enter the value you want to check for that cookie name.
Examples #
Cookie Name #
- Good: subscription-level
- Bad: subscription-level=premium (only enter the name of the cookie that you need to check the value of)
Cookie Value #
- Good: premium
- Bad: subscription-level=premium (only enter the value of the cookie that you need to check)
HTML Conditions #
HTML conditions allow you to trigger popups based on specific elements present on your page.
HTML Element Exists #
Show your popup when specific HTML elements are present on the page. Examples of HTML elements are <h2>
, <div>
, <p>
, and <img>
tags.
Settings #
- Element Selector (jQuery/CSS): Enter the jQuery/CSS selector that will check for an element. You must use valid CSS selector syntax.
Examples #
- Good:
.product-price
(show a popup on a page if there’s an element with the CSS class name “product-price”) - Good:
#product-sale-245
(show a popup on a page if there’s an element with the CSS ID “product-sale-245”) - Good:
img[alt^='ladies shoes']
(show a popup on a page if there’s an image with alt text that starts with “ladies shoes”, e.g., “ladies shoes spring” or “ladies shoes fall”) - Bad:
!world-hello
(invalid syntax because you cannot start a selector with an exclamation mark)
HTML Element Has Class #
Show your popup when specific HTML elements with a specific class are present on the page. Examples of HTML elements are <h2>
, <div>
, <p>
, and <img>
tags.
Use this when you need to target elements only by class name. In the example below, we want to display a popup only when there’s a figure (image) on a post or page that has the “product-image” class name.
Here’s the condition.
Here’s a page in the block editor where we set the product-image class to an image (figure).
Here’s what the HTML looks like when we bring up that page in the browser and our popup displays.
Settings #
- Element Selector (jQuery/CSS): Enter the jQuery/CSS selector that will check for an element. You must use valid CSS selector syntax. Don’t enter a class selector since you’ll enter the class name in the next field.
- Class to test for: Enter the class name only with no leading period (.).
Examples #
Element Selector (jQuery/CSS) #
- Good: figure
- Good: div
- Bad: my-cool-class (this is wrong because this is a class name, not a valid HTML element)
Class to test for #
- Good: product-image
- Bad: .product-image (this won’t work because there’s a leading period (.))
HTML Element On Screen #
This works like the HTML Element Exists condition, except the element must be partially visible (by default) when you load the post or page for your popup to show.
Click Only if element is completely visible on screen to display the popup only when the element is fully visible when you load your post or page. Uncheck (turn off) this setting to display the popup when the element is partially visible on load.
Keyboard Conditions #
Display a popup when someone does the following when a post or page loads:
- Holding Ctrl (Control on Windows and Mac)
- Holding Shift
- Holding ALt (Alt on Windows and Option on Mac)
Referrer Conditions #
Referrer conditions let you show popups to visitors based on where they came from. This is perfect for creating customized experiences based on traffic sources such as search engines and external websites.
You can specify exact URLs or wildcards (contains, begins, ends) as well as write your own regular expression (regex).
Referrer URL Is #
Show your popup when visitors come from URLs that you specify. This is an exact match.
Settings #
- URL: Enter the exact referrer URL, including the protocol (
http://
orhttps://
).
Examples #
- Good: https://wppopupmaker.com
- Bad: wppopupmaker.com (missing protocol)
Referrer URL Contains #
Show your popup when visitors come from URLs that match what you enter in any part of the URL.
Settings #
- Contains: Enter the text that can be anywhere in the referrer URL.
Examples #
- Good: docs (matches https://docs.wppopupmaker.com and https://wppopupmaker.com/docs)
- Bad: ? (this will launch a popup any time the referrer URL has a query parameter—you probably don’t want that)
Referrer URL Begins With #
Display your popup when people come from a URL that starts with the text you enter.
Settings #
- Begins With: Enter what the referrer URL must begin with, including the protocol.
Examples #
- Good: https://wppopupmaker.com
- Bad: wppopupmaker.com (missing protocol)
Referrer URL Ends With #
If the referrer URL ends with the text you enter, the popup displays.
Settings #
- Ends With: Enter what the URL must end with, including the protocol.
Examples #
- Good: -case-study (matches URL that ends with “-case-study”)
- Bad: https://wppopupmaker (this is how URLs begin, not end)
Referrer Is Search Engine #
Open a popup for people coming from specific search engine results page (SERP).
Settings #
- Select Search Engines: Choose one or more from Google, Bing, and Yahoo.
Referrer Is External URL #
Open a popup for people coming from another website.
User Conditions #
User Conditions help you focus on people based on their WordPress user status and behavior.
Is Logged In #
Show your popup only to logged-in WordPress users.
Has Role #
Show popups to logged-in users based on specific WordPress roles you choose.
Has Commented #
Display popups to people based on their comment activity on your site. Perfect for engaging active community members or encouraging more participation.
Settings #
You can enter More Than (min value), Less Than (max value), or both (range).
- More Than (optional): Enter a minimum number of comments. This will make your popup show when someone comments (strictly) higher than the number you enter.
- Less Than (optional): Enter a maximum number of comments. This will make your popup show when someone comments (strictly) lower than the number you enter. This works better as part of a range instead of by itself.
Examples #
More Than (optional) #
- Good: 2 (make sure you use a cookie; otherwise, the popup will keep displaying on every comment after their second (2nd) comment)
- Bad: 100 (your popup may never show)
More Than and Less Than (as range) #
- Good: 2 and 4 (the popup displays exactly after someone posts a third (3rd) comment only)
- Bad: 2 and 10 (the popup will keep displaying on every comment after their second (2nd) comment until their 10th comment unless you use a cookie)
Has Viewed Popup #
Display a popup to a visitor based on a prerequisite popup they saw before.
Note: You’ll need to use a cookie for the prerequisite popup to stop it from “clashing” with your target popup.
Settings #
- Select a popup: Choose a (only 1) popup from the dropdown. This is the prerequisite popup. Make sure it’s published and active.
- More Than (optional): At the time of writing, you must enter at least 1. That means people need to view the prerequisite popup at least 2 times before this target popup displays. Use a cookie to stop the target popup displaying over and over.
- Less Than (optional): At the time of writing, you should use this only in combination with More Than (optional) as a range. Otherwise, this target popup will show even though you didn’t view the prerequisite popup.
Examples #
More Than (optional) #
- Good: 1 (people will see the target popup after they see the prerequisite popup 2 times)
- Bad: 0 (the popup will never display)
More Than and Less Than (as range) #
- Good: 1 and 3 (people will see the target popup only after they have seen the prerequisite popup 2 times)
- Bad: 0 and 2 (people will see the target popup even if they don’t see the prerequisite popup)
Has Viewed X Pages #
Show your popup to visitors after they view a number of pages (and posts) that you specify. The number of viewed pages includes “duplicate” page views (i.e., non-unique views).
Settings #
You can enter More Than (min value), Less Than (max value), or both (range).
- More Than (optional): Enter a minimum number of pages. This will make your popup show when the number of pages is (strictly) higher than the number you enter. Use a cookie to stop the popup from displaying on every page after the minimum number of pages.
- Less Than (optional): Enter a maximum number of pages. This will make your popup show when the number of pages is (strictly) lower than the number you enter.
Examples #
More Than #
- Good: 3 (the popup displays after the visitor views 4 or more pages)
- Bad: 0 (the popup will display immediately, which defeats the purpose of this condition)
Less Than #
- Good: 5 (the popup displays if the visitor views fewer than 5 pages)
- Bad: 1 (the popup will never display)
More Than and Less Than (as range) #
- Good: 2 and 5 (the popup displays only on the 3rd or 4th page views)
- Bad: 0 and 1 (the popup will never display)
Has Viewed Selected Pages #
Display a popup after a visitor views 1 or more posts you select.
Note: At the time of writing, this feature only works for posts *not* pages. Stay tuned for updates.
Settings #
- Comma list of IDs: Enter a post ID. To add more than 1 post ID, separate the IDs with a comma (,). If you enter more than 1 ID, your visitor must view all post IDs (in any order) before your popup displays.
Examples #
- Good: 1,335 (the popup displays only after you view both post 1 and 335 in any order)
- Bad: (leaving this setting blank makes the popup display no matter what page you view)
- Bad: 1-335 (use a comma between post IDs)
Time On Site #
At the time of writing, this feature does *not* work. Stay tuned for updates.
Note: If you’re a developer or have a dev on your team, have a look at our sample custom code workaround on GitHub.
Custom Conditions #
And for the last set of conditions, yet by no means the least—write your own targeting condition using PHP or JavaScript (JS)!
Popup Maker will run your custom function first before deciding whether to display your popup. If your function returns true
, your popup will display. If your function returns false
, your popup will *not* display.
Here are a couple of scenarios:
- Write a PHP function that checks for a custom field in the post or page. Then display a popup based on that custom field.
- Write a JS function that customizes the contents of a popup depending on the viewer’s time of day.
Custom PHP Function #
If you didn’t see the targeting rule you need, you can write your own using a PHP function.
Settings #
- Function Name: Enter your custom PHP function name only, without any parentheses. The function must return
true
orfalse
. If the function returnstrue
, the popup displays.
Examples #
- Good: custom_php_targeting_acf
- Bad: my_awesome_function()
Custom PHP Function Video Tutorial #
In this video, I walk you through the steps for using the Custom PHP Function targeting condition.
For this example, my PHP function checks if a specific Advanced Custom Fields (ACF) field value, which matches “Show the popup”, is on a post or page. If that ACF value exists, my function adds custom content to the popup using the pum_popup_content
filter and returns true
so Popup Maker knows to display the popup..
Tutorial Transcript #
- 0:00 The first thing to do is make sure you’ve got a custom field set up, this is mine, for this example, and it could show up in posts and pages.
- 0:25 So this is what my function name is, that I’m copying right now. And then, in the page that I have, I have down here, the custom field.
- 0:51 And lastly, to the popup, under targeting, we want to use custom PHP function and paste in the name of the function, that’s it.
- 1:06 Just the name, nothing else.
End Result #
Sample PHP Code From the Tutorial #
If you’re new to using custom PHP on a WordPress site, read our Getting Started With Custom PHP guide first.
/**
* Custom PHP targeting function using Popup Maker ATC
*
* This function checks if a specific ACF field value matches 'Show the popup'
* and if so, adds custom content to the popup using the pum_popup_content filter.
*
* @return bool Returns true if the popup should be shown, false otherwise
*/
function custom_php_targeting_acf() {
// Check if the ACF field 'my-custom-field-1' equals 'Show the popup'
if ( get_field( 'my-custom-field-1' ) == 'Show the popup' ) {
// Add a filter to modify the popup content
add_filter( 'pum_popup_content', function ( $content ) {
// Append a heading and paragraph to the existing popup content
$content .= '<h3>' . get_field( 'my-custom-field-1' ) . '</h3>'
. '<p>' . 'Did you see what I did there?' . '</p>';
return $content;
} );
return true; // Return true to indicate popup should be shown
}
return false; // Return false if conditions aren't met
}
Custom JS Function #
If you didn’t see the targeting rule you need and you’d rather write a JavaScript function, this targeting rule is the way to go.
Settings #
- Function Name: Enter your custom JavaScript function name only, without any parentheses. The function must return
true
orfalse
. If the function returnstrue
, the popup displays.
Examples #
- Good: showDailyTip
- Bad: myAwesomeFunction()
Custom JS Function Demo #
In this demo, we use a JavaScript function that dynamically adds a time-sensitive “tip” message into our popup content. Then, the JS function returns true
so our Custom JS Function targeting rule displays our popup.
Video #
We recorded this demo around 7:30 at night. So we should see the evening screen time tip 🤓
Sample JS Code From the Video Tutorial #
If you’re new to using custom JS on a WordPress site, read our Getting Started With Custom JavaScript guide first.
/**
* Adds a time-based daily tip to a specific Popup Maker popup
*
* This action hook injects JavaScript into the footer that displays different
* wellness tips based on the time of day. The tips appear in popup ID 258.
*
* Morning (6am-12pm): Water reminder
* Afternoon (12pm-6pm): Break reminder
* Evening (6pm-6am): Screen time tip
*
* @uses wp_footer Action hook to add scripts to the footer
*/
add_action( 'wp_footer', function() {
?>
<script type="text/javascript">
/**
* Displays a time-sensitive wellness tip in a Popup Maker popup
*
* @returns {boolean} True after the tip is added to the popup
*/
function showDailyTip() {
// Get current time to determine which tip to show
const now = new Date();
const hour = now.getHours();
let tip = "";
// Select appropriate tip based on time of day
if (hour >= 6 && hour < 12) {
tip = "Good morning! Did you know starting your day with a glass of water can boost your energy?";
} else if (hour >= 12 && hour < 18) {
tip = "Hello! Taking a short break in the afternoon can improve focus. Maybe step away for 5 minutes?";
} else {
tip = "Good evening! Wind down before bed by avoiding screen time for at least an hour.";
}
// Create and append the tip message to the popup
const message = document.createElement('p');
message.textContent = tip;
const popupContainer = document.querySelector('#popmake-258.pum-container');
popupContainer.appendChild(message);
return true;
}
</script>
<?php
} );