Route Targeting

Route targeting allows you to show popups only on specific pages or routes in your application. The SDK uses the segments.path field to match the current URL against your targeting rules.

How Route Targeting Works

When a popup definition includes segments.path, the SDK evaluates the current route before showing the popup:

User navigates to a page
SDK checks if the current URL matches any path in segments.path
Popup shows only if there’s a match and conditions are met

segments.path is the only segment currently evaluated by the SDK runtime. Other segment fields may be used for organization but won’t affect popup display.

Basic Path Matching

Homepage

Target the root path:

segments: {
  path: ['/']
}

Matches:

✅ https://example.com/
✅ https://example.com (trailing slash optional)
❌ https://example.com/about

Specific Pages

Target named routes:

segments: {
  path: ['/pricing', '/features', '/contact']
}

Matches:

✅ https://example.com/pricing
✅ https://example.com/features
✅ https://example.com/contact
❌ https://example.com/about

Hash Routes

Support single-page applications with hash routing:

segments: {
  path: ['/#/home', '/#/dashboard', '/#/settings']
}

Matches:

✅ https://example.com/#/home
✅ https://example.com/#/dashboard
❌ https://example.com/#/profile

Path Matching Rules

The SDK normalizes and compares URLs using these rules:

Full URL Matching

If the path starts with http:// or https://, it’s matched as a complete URL:

segments: {
  path: ['https://example.com/pricing']
}

✅ Exact match required
❌ Won’t match http://example.com/pricing (protocol must match)
❌ Won’t match https://other.com/pricing (domain must match)

Path Fragment Matching

If the path starts with /, it’s matched as a path fragment:

segments: {
  path: ['/pricing']
}

✅ Matches if the current URL contains the path
✅ Works with any domain
✅ Example: https://example.com/pricing

Relative Path Matching

If the path doesn’t start with http://, https://, or /, it’s matched against the pathname:

segments: {
  path: ['pricing']
}

✅ Matches the pathname exactly
✅ Example: If pathname is pricing, it matches
❌ Won’t match /pricing or /pages/pricing

URL Normalization

The SDK normalizes URLs before comparison:

Trailing Slashes

Removed from the end of URLs:

// These are equivalent:
'https://example.com/pricing/'
'https://example.com/pricing'

index.html

Removed from URLs:

// These are equivalent:
'https://example.com/index.html'
'https://example.com/'

'https://example.com/pricing/index.html'
'https://example.com/pricing'

You don’t need to worry about trailing slashes or index.html in your path definitions. The SDK handles normalization automatically.

Advanced Examples

Multiple Pages

Target several related pages:

const popupDefinition = {
  id: 'popup-product-pages',
  title: 'Product feedback',
  message: '<p>Help us improve our product pages.</p>',
  triggers: {
    type: 'time_on_page',
    value: 10,
  },
  surveyId: 'survey-product',
  productId: 'product-main',
  segments: {
    path: [
      '/products',
      '/features',
      '/pricing',
      '/demo',
    ]
  },
};

Hash Route Application

Target specific views in a single-page app:

const popupDefinition = {
  id: 'popup-dashboard',
  title: 'Dashboard feedback',
  message: '<p>How can we improve your dashboard?</p>',
  triggers: {
    type: 'scroll',
    value: 50,
  },
  surveyId: 'survey-dashboard',
  productId: 'product-main',
  segments: {
    path: [
      '/#/dashboard',
      '/#/analytics',
      '/#/reports',
    ]
  },
};

Combining Full URLs and Paths

Mix different path types:

segments: {
  path: [
    'https://example.com/special',  // Exact URL
    '/general',                      // Path fragment
    '/#/app',                        // Hash route
  ]
}

No Path = All Routes

If you don’t specify segments.path, the popup can appear on any route:

const popupDefinition = {
  id: 'popup-global',
  title: 'General feedback',
  message: '<p>How is your experience?</p>',
  triggers: {
    type: 'time_on_page',
    value: 30,
  },
  surveyId: 'survey-general',
  productId: 'product-main',
  // No segments.path → shows on all routes
};

Use global popups sparingly. Targeting specific routes leads to better, more contextual feedback.

Exit Popups and Route Targeting

For exit triggers, segments.path specifies the source routes to watch:

const exitPopup = {
  id: 'popup-pricing-exit',
  title: 'Pricing feedback',
  message: '<p>What made you leave?</p>',
  triggers: {
    type: 'exit',
    value: 3,
  },
  surveyId: 'survey-exit',
  productId: 'product-main',
  segments: {
    path: ['/pricing'] // Show when user LEAVES /pricing
  },
};

Learn more in the Exit Popups guide.

Source Code Reference

Path matching logic is in src/core/deepdots-popups.ts:247-283:

private matchesSegmentsPath(def: PopupDefinition, pathUrl?: string): boolean {
  const paths = def.segments?.path;
  if (!paths || paths.length === 0) return true;
  
  const normalizedHref = this.normalizeUrl(pathUrl || window.location.href || '');
  const currentUrl = this.safeParseUrl(normalizedHref);
  const normalizedPath = this.normalizeUrl(currentUrl?.pathname || window.location.pathname || '');

  const matches = paths.some(rawCandidate => {
    const candidate = this.normalizeUrl(rawCandidate);
    let match = false;
    if (candidate.startsWith('http://') || candidate.startsWith('https://')) {
      match = normalizedHref === candidate;
    } else if (candidate.startsWith('/')) {
      match = normalizedHref.includes(candidate);
    } else {
      match = normalizedPath === candidate;
    }
    return match;
  });

  return matches;
}

Debugging Path Matching

Enable debug mode to see path matching logs:

popups.init({
  mode: 'client',
  debug: true,
  popups: definitions,
});

Logs include:

Current pathname and href
Candidate paths being evaluated
Whether each path matched
Why popups were blocked

Common Patterns

Onboarding flows

Target welcome and setup pages:

segments: {
  path: ['/welcome', '/setup', '/onboarding']
}

E-commerce checkout

Target conversion funnel pages:

segments: {
  path: ['/cart', '/checkout', '/payment']
}

Content pages

Target blog or documentation:

segments: {
  path: ['/blog', '/docs', '/help']
}

Dashboard sections

Target specific app features:

segments: {
  path: ['/#/dashboard', '/#/analytics', '/#/settings']
}

Limitations

No wildcard support: The SDK doesn’t support glob patterns like /products/* or regex matching. You must list specific paths.

To target multiple related pages, list them explicitly:

// Instead of: '/products/*'
segments: {
  path: [
    '/products/widget-a',
    '/products/widget-b',
    '/products/widget-c',
  ]
}

Best Practices

Be specific

Target pages where feedback is most valuable:

// Good: Specific high-value pages
segments: { path: ['/pricing', '/demo'] }

// Avoid: Too broad
segments: { path: ['/'] } // Every page

Group related routes

Test hash routes carefully

Ensure hash routes include the #:

// Correct
segments: { path: ['/#/dashboard'] }

// Won't work
segments: { path: ['/dashboard'] } // Missing #

Use debug mode

Verify path matching during development:

popups.init({
  mode: 'client',
  debug: true, // See matching logs
  popups: definitions,
});

Next Steps

Exit Popups

Use route targeting with exit triggers

Event Triggers

Combine routes with business events

Server Mode

Manage route targeting remotely

Client Mode

Define route targeting inline

Get Started

Core Concepts

Guides

Examples

How Route Targeting Works

Basic Path Matching

Homepage

Specific Pages

Hash Routes

Path Matching Rules

Full URL Matching

Path Fragment Matching

Relative Path Matching

URL Normalization

Trailing Slashes

index.html

Advanced Examples

Multiple Pages

Hash Route Application

Combining Full URLs and Paths

No Path = All Routes

Exit Popups and Route Targeting

Source Code Reference

Debugging Path Matching

Common Patterns

Limitations

Best Practices

Next Steps

Exit Popups

Event Triggers

Server Mode

Client Mode

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

Examples

Documentation Index

​How Route Targeting Works

​Basic Path Matching

​Homepage

​Specific Pages

​Hash Routes

​Path Matching Rules

​Full URL Matching

​Path Fragment Matching

​Relative Path Matching

​URL Normalization

​Trailing Slashes

​index.html

​Advanced Examples

​Multiple Pages

​Hash Route Application

​Combining Full URLs and Paths

​No Path = All Routes

​Exit Popups and Route Targeting

​Source Code Reference

​Debugging Path Matching

​Common Patterns

​Limitations

​Best Practices

​Next Steps

Exit Popups

Event Triggers

Server Mode

Client Mode

Build docs developers (and LLMs) love

How Route Targeting Works

Basic Path Matching

Homepage

Specific Pages

Hash Routes

Path Matching Rules

Full URL Matching

Path Fragment Matching

Relative Path Matching

URL Normalization

Trailing Slashes

index.html

Advanced Examples

Multiple Pages

Hash Route Application

Combining Full URLs and Paths

No Path = All Routes

Exit Popups and Route Targeting

Source Code Reference

Debugging Path Matching

Common Patterns

Limitations

Best Practices

Next Steps