Popup - Troubleshooting Guide

Popup - Troubleshooting Guide

Problem: Popup not appearing on public pages

Solution:

• Verify "Enable Popup" toggle is ON (gradient orange)
• Check that you clicked "Save Settings" and saw success message
• Clear browser cookies (popup may have been shown already based on frequency)
• Test in incognito/private browsing mode for fresh session
• Verify trigger conditions are met:
  • Time Delay: Wait for configured seconds
  • Exit Intent: Move cursor to top of browser
  • Scroll: Scroll to configured percentage
• Check browser console for JavaScript errors
• Ensure <x-popup-modal /> component is included in layout
• Verify you're viewing a public page (not admin area)
• Clear application cache: php artisan cache:clear

Problem: Popup appears too frequently or not respecting frequency setting

Solution:

• Check "Show Frequency" setting is configured correctly
• Clear browser cookies to reset tracking
• Verify cookie name popup_shown is being set
• Check browser's cookie settings allow cookies
• Test in different browser to isolate cookie issues
• Ensure JavaScript is enabled in browser
• Check for browser extensions blocking cookies
• Verify cookie expiration times are correct (365 days for "Once", 1 day for "Daily")
• Review browser developer tools > Application > Cookies

Problem: Exit intent trigger not working

Solution:

• Desktop: Move cursor quickly to very top of browser window (within 50px)
• Mobile: Scroll to top of page and pull down (refresh gesture)
• Verify trigger type is set to "Exit Intent"
• Test in different browsers (some may handle mouse events differently)
• Check browser console for JavaScript errors
• Ensure page has enough content to scroll on mobile
• Try testing on actual mobile device instead of browser emulation
• Verify event listeners are properly attached
• Check that popup hasn't already been shown (clear cookies)

Problem: Scroll trigger not activating

Solution:

• Ensure page is long enough to scroll to configured percentage
• Try lowering scroll percentage to 25% for testing
• Verify trigger type is set to "Scroll Percentage"
• Check that popup hasn't already been shown (clear cookies)
• Test on page with substantial content
• Verify scroll event listeners are working (check console)
• Try scrolling slowly and deliberately
• Check browser console for JavaScript errors
• Ensure page height calculation is correct

Problem: Popup image not displaying or broken

Solution:

• Verify image uploaded successfully (check for success message)
• Ensure image file size is within server limits
• Check file format is supported (JPG, PNG, WebP, GIF)
• Verify image path in database settings table
• Check file permissions on uploads directory
• Ensure uploads_url() helper function is working
• Try uploading a different image to isolate file-specific issues
• Check browser console for 404 errors on image URL
• Verify storage symlink is created: php artisan storage:link
• Check that image wasn't deleted from storage directory

Problem: Button link not working or going to wrong page

Solution:

• Verify "Button URL" field has correct URL
• Check URL format includes protocol (http:// or https://) for external links
• Test with relative URLs (e.g., "/about") for internal pages
• Ensure URL is valid and page exists
• Check for typos in URL
• Test button in preview mode first
• Verify JavaScript isn't preventing link navigation
• Check browser console for errors when clicking button
• Try opening URL directly in browser to verify it works

Problem: Close button (X) not visible or not working

Solution:

• Verify "Show Close (X) Button" toggle is ON
• Check that X button isn't hidden by CSS or z-index issues
• Ensure button styling is loading correctly
• Test ESC key as alternative (always works)
• Check browser console for JavaScript errors
• Verify click event handler is attached
• Try different popup sizes (X button position may vary)
• Check dark mode styling (button may blend with background)
• Clear browser cache and reload page

Problem: Popup appears but content is missing or incorrect

Solution:

• Verify all content fields are filled in settings
• Check that settings were saved successfully
• Clear application cache: php artisan cache:clear
• Verify get_setting() helper is retrieving correct values
• Check database settings table for popup settings
• Ensure settings group is 'popup'
• Review popup component blade file for correct variable names
• Check for HTML escaping issues with special characters
• Verify content isn't being truncated by CSS
• Test with simple text first, then add complexity

Problem: Popup styling looks broken or misaligned

Solution:

• Clear browser cache and hard refresh (Ctrl+F5 or Cmd+Shift+R)
• Verify Tailwind CSS is compiled: npm run build
• Check that all CSS files are loading (no 404 errors)
• Test in different browsers to isolate browser-specific issues
• Verify dark mode classes are working correctly
• Check for CSS conflicts with other styles
• Ensure popup component uses correct Tailwind classes
• Try different size and position settings
• Check browser console for CSS errors
• Verify viewport meta tag is present in layout

Problem: Popup not responsive on mobile devices

Solution:

• Test on actual mobile device, not just browser emulation
• Verify viewport meta tag: <meta name="viewport" content="width=device-width, initial-scale=1.0">
• Check that popup size adapts to screen width
• Try using "Small" or "Medium" size for mobile
• Ensure images are responsive (max-width: 100%)
• Test in both portrait and landscape orientations
• Verify touch events work for closing popup
• Check that text is readable at mobile sizes
• Ensure buttons are large enough to tap (minimum 44x44px)
• Test with different mobile browsers (Safari, Chrome, Firefox)

Problem: Popup appears behind other elements

Solution:

• Check z-index values in CSS (popup should have high z-index)
• Verify background overlay is enabled for better layering
• Look for other elements with very high z-index values
• Check for CSS positioning conflicts
• Ensure popup container has proper stacking context
• Try disabling other overlays or modals temporarily
• Review CSS for position: fixed or position: sticky conflicts
• Check browser developer tools for z-index values
• Verify popup component is rendered at end of body

Problem: Animation not smooth or janky

Solution:

• Try different animation types (Fade is smoothest)
• Check browser performance (close other tabs/applications)
• Verify CSS transitions are hardware accelerated
• Ensure images are optimized and compressed
• Test on different devices (older devices may struggle)
• Check for JavaScript blocking main thread
• Verify no heavy operations during animation
• Try disabling browser extensions that may interfere
• Check browser console for performance warnings
• Consider using simpler animation for better performance

Problem: Permission denied when accessing Popup Settings

Solution:

• Contact administrator to request landing-page.view permission
• Verify your user role has necessary permissions assigned
• Check that you're logged in with correct account
• Review roles and permissions module for your access level
• Ensure your account is active and not suspended
• Check if permission middleware is correctly applied to route
• Verify route exists: php artisan route:list | grep popup
• Check for any custom permission logic that may be blocking access

Related Modules

• Landing Page: Customize homepage content and sections
• About Us Page: Manage about page content and team information
• Contact Us Page: Configure contact page and form settings
• Loader Settings: Customize page loading animation
• Cookie Consent: Manage cookie consent banner (similar modal pattern)
• General Settings: Configure site-wide settings