How to Detect Popups on Any Webpage via API (With Code)

Vitalii Holben Published Reading12 min

Page Analysis returns every element on a rendered page as structured JSON (headings, buttons, forms, images), each with a bounding rectangle in pixels. To detect popups, you look for elements that sit on top of the page content: high z-index, fixed or absolute positioning, covering a large chunk of the viewport. One API call, and you get a map of everything overlaying the actual page.

But detecting popups on the real web is messier than checking a CSS property. Cookie banners use OneTrust's iframe-based architecture. Newsletter modals fire on a 5-second timer, so they're invisible if you snapshot the DOM too early. Age gates on alcohol and gambling sites replace the entire page content until the user clicks through. Exit-intent overlays only appear when the cursor heads for the browser chrome, and headless browsers don't have cursors. The new Popover API and dialog.showModal() push elements into the browser's top layer, which sits above all z-index stacking entirely.

This post walks through how to detect popups on any URL, classify them by type, figure out their selectors, and decide what to do with them, all using ScreenshotRun's Page Analysis endpoint.

Why detect popups instead of just blocking them?

Blocking is the default approach. Set block_cookies=true, add a few selectors to hide_selectors[], take a clean screenshot. Done. But that workflow assumes you already know what popups a page has. When you're auditing an unfamiliar site or scanning hundreds of pages across a client portfolio, you don't know what's there until you look.

Google measures two internal metrics for ranking: violatesMobileInterstitialPolicy and adsDensityInterstitialViolationStrength. Sites that fail these checks on mobile lose ranking positions. SEO agencies need to flag which client pages trigger these signals, and that means finding the popup first, measuring how much of the viewport it covers, documenting the finding, then reporting it before anyone talks about removal.

Security teams have a different reason. Overlay phishing works by layering a transparent or deceptive interface on top of legitimate content (a fake login form hovering over a real page). Clickjacking uses the same mechanism: a hidden iframe positioned over a button the user thinks they're clicking. Finding fixed-position elements with suspicious z-index values and large viewport coverage is how you catch these attacks programmatically.

QA teams hit the same wall from another direction. Visual regression suites compare screenshots between builds. A cookie banner that fires on one run but not another (because the consent was cached) produces a false-positive diff. Knowing which popups exist on a page, and what selectors target them, lets you write stable hide_selectors rules instead of debugging phantom diffs.

What counts as a popup?

"Popup" covers at least eight distinct UI patterns. They differ in trigger mechanism, DOM positioning, viewport coverage, and purpose.

Center modals (the classic lightbox) use position:fixed with a semi-transparent backdrop. They sit in the middle of the viewport, typically covering 40-60% of the screen. Newsletter signups, discount offers, login prompts. The HTML <dialog> element with .showModal() creates these natively now, pushing them into the browser's top layer where they render above everything regardless of z-index.

Full-screen overlays block the entire page. Age gates on LEGO.com, alcohol brand sites, gambling platforms, and some pharmaceutical pages use these. Cookie consent managers like OneTrust sometimes deploy full-screen mode too, especially on first visit in the EU. These cover 90%+ of the viewport area.

Slide-ins attach to a screen edge. Bottom-right is the most common position for chat widgets (Intercom, Drift, Zendesk), but newsletter captures and promotion announcements use bottom slide-ins too. They typically cover 10-25% of the viewport.

Floating bars span the full width of the viewport at the top or bottom, with small height. Cookie consent bars (the non-modal kind), promotional banners, "download our app" strips, and GDPR-mandated data processing notices use this format. Coverage: 5-15% of viewport, but they still obscure content and affect layout.

Then there are inline expanded sections that appear in the normal document flow without any special CSS positioning. Harder to detect because they look like regular content that just wasn't there a moment ago. And exit-intent overlays that require a specific mouse movement to trigger, which means headless browsers won't see them without simulating that gesture.

The detection approach: DOM analysis via API

Send a URL to the Page Analysis endpoint. The response includes every interactive element, every form, every text block, each with a bounding rectangle ([x, y, width, height]). From that data, you can identify overlapping elements, calculate viewport coverage percentages, and classify what you find based on text content and attributes.

curl -X POST https://api.screenshotrun.com/v1/analyze \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example-shop.com",
    "include": ["interactive", "forms", "text"],
    "stealth": true
  }'

Stealth mode matters here. Some popup libraries check for headless browsers and suppress their popups during bot visits (they want real users to see the signup form, not crawlers). Stealth makes the browser look like a regular Chrome session, so the popups fire normally.

A Python script that processes the response and flags potential overlays:

import requests

API_KEY = "YOUR_API_KEY"
VIEWPORT = {"width": 1280, "height": 800}

def detect_popups(url):
    """Scan a URL for popups and overlays via Page Analysis."""
    resp = requests.post(
        "https://api.screenshotrun.com/v1/analyze",
        headers={"Authorization": f"Bearer {API_KEY}"},
        json={
            "url": url,
            "include": ["interactive", "forms", "text"],
            "stealth": True,
            "width": VIEWPORT["width"],
            "height": VIEWPORT["height"],
        },
        timeout=60,
    )
    data = resp.json()["result"]
    vp_area = VIEWPORT["width"] * VIEWPORT["height"]
    popups = []

    # Scan all element categories for overlay-like elements
    for category in ["interactive", "forms", "text"]:
        for el in data.get(category, []):
            rect = el.get("rect")
            if not rect or len(rect) < 4:
                continue

            x, y, w, h = rect
            el_area = w * h
            coverage = el_area / vp_area

            # Heuristic: element covers >30% of viewport
            # and sits within the visible area
            if coverage > 0.3 and y < VIEWPORT["height"]:
                popups.append({
                    "text": el.get("text", "")[:120],
                    "tag": el.get("tag", "unknown"),
                    "rect": rect,
                    "coverage": round(coverage * 100, 1),
                    "category": category,
                    "type": classify_popup(el),
                })

    return popups


def classify_popup(el):
    """Guess popup type from element text and attributes."""
    text = (el.get("text", "") or "").lower()
    href = (el.get("href", "") or "").lower()
    combined = f"{text} {href}"

    if any(kw in combined for kw in [
        "cookie", "consent", "gdpr", "privacy", "accept all"
    ]):
        return "cookie_consent"
    if any(kw in combined for kw in [
        "subscribe", "newsletter", "email", "sign up", "get updates"
    ]):
        return "newsletter"
    if any(kw in combined for kw in [
        "age", "over 18", "over 21", "verify", "are you old enough"
    ]):
        return "age_gate"
    if any(kw in combined for kw in [
        "chat", "help", "support", "message us"
    ]):
        return "chat_widget"
    if any(kw in combined for kw in [
        "discount", "off", "% off", "coupon", "deal", "offer"
    ]):
        return "promo"
    if any(kw in combined for kw in [
        "log in", "sign in", "create account", "register"
    ]):
        return "login_wall"
    return "unknown"


results = detect_popups("https://example-shop.com")
for p in results:
    print(f"[{p['type']}] {p['coverage']}% viewport — {p['text'][:80]}")

That 30% coverage threshold catches most modal popups while ignoring navigation bars and footers. You can tune it lower (15-20%) to catch slide-ins and floating bars, or higher (50%) to focus on full-screen blockers only.

Common popup selectors you'll encounter

When the analysis flags a potential overlay, you often need the CSS selector to target it for removal in future screenshots. The major popup platforms use recognizable class names and IDs:

  • OneTrust (cookie consent): #onetrust-banner-sdk, .onetrust-pc-dark-filter, #onetrust-consent-sdk
  • Cookiebot: #CybotCookiebotDialog, #CybotCookiebotDialogBodyUnderlay
  • Osano: .osano-cm-window, .osano-cm-dialog
  • Klaviyo (newsletter): .klaviyo-form, .klaviyo-popup, [data-testid="klaviyo-form"]
  • OptinMonster: #om-popup, .om-holder, [class*="optinmonster"]
  • Intercom (chat): #intercom-container, .intercom-lightweight-app
  • Drift: #drift-widget, #drift-frame-controller
  • HubSpot (lead flow): .leadinModal, .leadin-main-wrapper
  • Popup Maker (WordPress): .pum-overlay, .pum-container
  • Sumo/SumoMe: .sumome-react-wysiwyg-popup, #sumome-smartbar

These selectors feed directly into hide_selectors[] when you want clean screenshots later. The ad blocking parameter handles many of these automatically, but knowing the specific selectors gives you finer control, especially when a site uses a less common platform or custom-built popups.

Handling popups that appear on a timer

A popup that fires 5 seconds after page load won't appear in a snapshot taken at 2 seconds. Use the delay parameter to control how long the browser waits after the page finishes loading before analyzing the DOM. For popup detection, I'd recommend at least 8-10 seconds to catch most timed overlays:

resp = requests.post(
    "https://api.screenshotrun.com/v1/analyze",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={
        "url": url,
        "include": ["interactive", "forms", "text"],
        "stealth": True,
        "delay": 10000,  # 10 seconds — catches most timed popups
    },
    timeout=90,
)

Some newsletter popups use scroll triggers instead of timers. They fire when the user scrolls past 30-50% of the page. For those, you'd combine delay with a JavaScript injection that simulates scrolling:

resp = requests.post(
    "https://api.screenshotrun.com/v1/analyze",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={
        "url": url,
        "include": ["interactive", "forms", "text"],
        "stealth": True,
        "js": "window.scrollTo(0, document.body.scrollHeight * 0.6);",
        "delay": 8000,
    },
    timeout=90,
)

Exit-intent popups are the hardest. They watch mouseout events on the document, specifically when the cursor crosses the top edge of the viewport (heading toward the address bar or tab strip). A headless browser can simulate this with JavaScript, but the popup library needs to see a realistic mouse trajectory. The JS injection for it:

// Simulate exit-intent: move mouse from center to top of viewport
const center = { x: window.innerWidth / 2, y: window.innerHeight / 2 };
document.dispatchEvent(new MouseEvent('mousemove', { clientX: center.x, clientY: center.y }));
setTimeout(() => {
    document.dispatchEvent(new MouseEvent('mouseout', { clientX: center.x, clientY: 0, relatedTarget: null }));
}, 500);

That triggers most exit-intent libraries (OptinMonster, Wisepops, Sleeknote). Not all of them. Some check for actual pointer events from the browser, not synthesized ones. But it covers the majority.

Comparing pages with and without popups

Once you've detected what popups exist, the natural next step is capturing a clean version. Take two screenshots: one raw (all popups visible), one cleaned. The diff shows what your users actually see versus the underlying content.

# Raw screenshot — popups included
raw = requests.get(
    "https://api.screenshotrun.com/v1/screenshots/capture",
    headers={"Authorization": f"Bearer {API_KEY}"},
    params={
        "url": url,
        "format": "png",
        "stealth": "true",
        "delay": "10000",
    },
)

# Clean screenshot — popups removed
clean = requests.get(
    "https://api.screenshotrun.com/v1/screenshots/capture",
    headers={"Authorization": f"Bearer {API_KEY}"},
    params={
        "url": url,
        "format": "png",
        "block_cookies": "true",
        "block_ads": "true",
        "block_chats": "true",
        "hide_selectors[]": "#newsletter-modal,.promo-popup,.age-gate",
    },
)

with open("raw.png", "wb") as f:
    f.write(raw.content)
with open("clean.png", "wb") as f:
    f.write(clean.content)

For SEO audits, the raw screenshot is what Google sees on first visit (Googlebot doesn't have cookies set). The clean version is what returning users see. If those two are drastically different (a full-screen interstitial on first visit that's absent on return), you've found the ranking penalty trigger.

Scanning at scale: batch popup detection

The real payoff comes when you scan an entire sitemap or URL list. Which pages have consent banners? Which ones deploy exit-intent modals? Are any serving popups only on mobile viewports?

import csv

urls = [
    "https://example.com",
    "https://example.com/pricing",
    "https://example.com/blog",
    "https://shop.example.com",
    "https://support.example.com",
]

results = []
for url in urls:
    try:
        popups = detect_popups(url)
        for p in popups:
            results.append({
                "url": url,
                "type": p["type"],
                "coverage": p["coverage"],
                "text": p["text"][:80],
            })
        if not popups:
            results.append({"url": url, "type": "none", "coverage": 0, "text": ""})
    except Exception as e:
        results.append({"url": url, "type": "error", "coverage": 0, "text": str(e)})

# Write CSV report
with open("popup-audit.csv", "w", newline="") as f:
    writer = csv.DictWriter(f, fieldnames=["url", "type", "coverage", "text"])
    writer.writeheader()
    writer.writerows(results)

print(f"Scanned {len(urls)} URLs, found {sum(1 for r in results if r['type'] not in ('none', 'error'))} popups")

Run this across a client's 500-page site and you get a CSV that answers: how many pages have popups, what kind, how intrusive. That's a deliverable for an SEO audit, a compliance report, a QA baseline document, or a competitive intelligence deck. Minutes instead of manual spot-checks over days.

Mobile vs. desktop popup differences

Google's intrusive interstitials penalty specifically targets mobile pages. A popup that's fine on desktop (covers 30% of a 1920px viewport) might be devastating on mobile (covers 80% of a 375px screen). Run the same detection at both viewport sizes:

viewports = [
    {"name": "desktop", "width": 1280, "height": 800},
    {"name": "mobile", "width": 375, "height": 812, "device": "mobile"},
]

for vp in viewports:
    resp = requests.post(
        "https://api.screenshotrun.com/v1/analyze",
        headers={"Authorization": f"Bearer {API_KEY}"},
        json={
            "url": url,
            "include": ["interactive", "forms", "text"],
            "stealth": True,
            "delay": 10000,
            "width": vp["width"],
            "height": vp["height"],
            "device": vp.get("device", "desktop"),
        },
    )
    # Analyze with viewport-appropriate coverage thresholds
    popups = process_response(resp.json(), vp["width"], vp["height"])
    print(f"\n{vp['name']}: {len(popups)} popup(s) detected")
    for p in popups:
        print(f"  [{p['type']}] {p['coverage']}% coverage")

Sites that show a subtle bottom bar on desktop often deploy a full-screen interstitial on mobile for the same purpose (cookie consent, app install prompt). Page Analysis catches this discrepancy automatically.

From detection to remediation

What you do with detected popups depends on who's consuming the data.

For clean screenshots, take the selectors you discovered and pass them to hide_selectors[] in your capture request. Or use the built-in parameters: block_cookies handles consent banners, block_ads strips ad interstitials, block_chats removes live chat widgets. For anything custom (a homepage promo modal, an age gate, a newsletter form), CSS injection with display:none on the detected selectors does it.

For SEO reports and compliance monitoring, flag pages where mobile popup coverage exceeds 30% of the viewport. That's the threshold where Google's interstitial signals start firing. Include the popup type (legally mandated cookie consent is exempt from the penalty, promotional interstitials are not) along with the selector to fix it. A before/after screenshot pair rounds out the evidence.

For security scanning, look for fixed-position elements with no visible content or near-zero opacity. Possible clickjacking frames. Cross-reference with iframe sources: if a transparent overlay sits on top of the page and contains an iframe pointing to an external domain, that's a red flag worth escalating.

FAQ#

Yes. Use the delay parameter to wait 8-10 seconds after page load, which catches most timer-based popups. For scroll-triggered popups, combine delay with the js parameter to inject a scrollTo() call that simulates scrolling to 50-60% of the page height before analysis.

Enable stealth mode in the API request. Stealth makes the headless browser appear as a regular Chrome session, which bypasses most basic bot detection. Some popup libraries suppress their overlays for bots, so stealth ensures the popups fire as they would for a real visitor.

Inject JavaScript that dispatches a mouseout event at the top edge of the viewport. This mimics the cursor leaving the page, which triggers most exit-intent libraries like OptinMonster, Wisepops, and Sleeknote. Not all libraries respond to synthesized events, but the majority do.

A 30% viewport coverage threshold catches most modal popups while ignoring navigation bars and footers. Lower it to 15-20% if you need to detect slide-ins and floating bars. Raise it to 50% if you only care about full-screen blockers like age gates and login walls.

No. Google exempts legally mandated popups like cookie consent banners and age verification gates from the intrusive interstitials penalty. The penalty targets promotional interstitials, newsletter signup modals, and app install prompts that block content on mobile pages.

Yes. Pass the CSS selectors you discover to the hide_selectors parameter in your screenshot capture request. The API also has built-in parameters: block_cookies for consent banners, block_ads for ad interstitials, and block_chats for live chat widgets.

Written by

Vitalii Holben

Co-founder and CEO of ScreenshotRun. Full-stack developer building screenshot API tools that help developers capture, automate, and monitor web pages at scale. Based in Europe, shipping code since 201...

Screenshot API in a few clicks

Free plan includes 200 screenshots every month. No credit card required.

Sign up → copy your key → make your first call