Skip to main content

Troubleshooting Integration Issues

When integrating ShopGuide with your Shopify theme, you might encounter various issues. This comprehensive troubleshooting guide helps you identify and resolve common problems quickly.

Common Integration Issues​

Chat Block Not Appearing​

Symptoms

  • Chat block missing from theme editor
  • Block appears in editor but not on live site
  • Chat widget doesn't show on store pages
  • Error messages in theme editor

Diagnostic Steps

  1. Check app installation: Verify ShopGuide is properly installed
  2. Confirm subscription: Ensure active subscription or trial period
  3. Browser cache: Clear cache and hard refresh (Ctrl+F5)
  4. Theme compatibility: Verify theme supports app blocks

Solutions

  • Reinstall app: Uninstall and reinstall ShopGuide
  • Update theme: Ensure theme is up to date
  • Contact support: If issue persists after basic troubleshooting
  • Try different browser: Test in incognito/private mode

Chat Block Issues

Styling and Appearance Problems​

Common Styling Issues

  • Chat colors don't match theme
  • Text is unreadable due to poor contrast
  • Chat appears too large or too small
  • Layout conflicts with theme elements
  • Mobile display problems

Color and Contrast Issues

  • Check color settings: Verify colors in block configuration
  • Test contrast ratios: Ensure text is readable
  • Brand consistency: Match theme's color palette
  • Accessibility compliance: Meet WCAG guidelines

Size and Layout Issues

  • Responsive testing: Check on different screen sizes
  • CSS conflicts: Look for conflicting theme styles
  • Z-index problems: Ensure chat appears above other elements
  • Positioning conflicts: Adjust chat placement

Functionality Problems​

Chat Not Responding

  • Messages send but no AI response
  • Error messages in chat interface
  • Chat opens but appears broken
  • Infinite loading states

Troubleshooting Steps

  1. Check subscription status: Verify active ShopGuide plan
  2. Test internet connection: Ensure stable connectivity
  3. Browser compatibility: Test in different browsers
  4. JavaScript errors: Check browser console for errors
  5. Third-party conflicts: Disable other apps temporarily

Functionality Issues

Browser-Specific Issues​

Chrome Issues​

Common Problems

  • Chat not loading due to ad blockers
  • Performance issues with extensions
  • Cache-related display problems

Solutions

  • Disable ad blockers: Temporarily disable for testing
  • Clear Chrome cache: Settings > Privacy > Clear browsing data
  • Disable extensions: Test in incognito mode
  • Update Chrome: Ensure latest browser version

Safari Issues​

Common Problems

  • Cross-origin request blocks
  • WebKit rendering differences
  • Mobile Safari specific issues

Solutions

  • Check security settings: Adjust cross-site tracking prevention
  • Test on different iOS versions: Verify compatibility
  • Clear Safari cache: Settings > Safari > Clear History and Website Data
  • Update Safari: Ensure latest version

Firefox Issues​

Common Problems

  • Enhanced tracking protection interference
  • Different CSS rendering
  • JavaScript compatibility issues

Solutions

  • Adjust tracking protection: Lower protection level for testing
  • Clear Firefox cache: Options > Privacy & Security > Clear Data
  • Test in private mode: Verify without extensions
  • Update Firefox: Ensure latest version

Mobile-Specific Troubleshooting​

iOS Issues​

Common Problems

  • Chat not appearing on iPhone/iPad
  • Touch interactions not working
  • Keyboard covering chat interface
  • Performance issues on older devices

Diagnostic Steps

  1. Test on multiple iOS devices: Different models and versions
  2. Check Safari settings: Verify JavaScript is enabled
  3. Test in different orientations: Portrait and landscape
  4. Monitor performance: Check for memory issues

Solutions

  • Update iOS: Ensure latest operating system
  • Clear Safari cache: Settings > Safari > Clear History
  • Restart device: Simple restart can resolve issues
  • Test on newer devices: Verify if issue is device-specific

Android Issues​

Common Problems

  • Inconsistent behavior across Android browsers
  • Performance issues on budget devices
  • Touch target sizing problems
  • Keyboard interaction issues

Solutions

  • Test multiple browsers: Chrome, Firefox, Samsung Internet
  • Optimize performance: Reduce animations and effects
  • Increase touch targets: Ensure minimum 44px size
  • Test on various devices: Different manufacturers and Android versions

Mobile Troubleshooting

Theme-Specific Issues​

Dawn Theme (Shopify Default)

  • Generally excellent compatibility
  • Rare issues with custom modifications
  • Check for theme updates regularly

Debut Theme

  • Older theme may need positioning adjustments
  • CSS conflicts with legacy styles
  • Consider theme upgrade if issues persist

Custom Themes

  • Unique CSS may conflict with chat styles
  • Developer consultation may be needed
  • Document custom modifications

Theme Compatibility Testing​

Testing Checklist

  1. Visual integration: Chat matches theme design
  2. Responsive behavior: Works on all screen sizes
  3. Performance impact: No significant slowdown
  4. Functionality: All chat features work correctly
  5. Cross-browser: Consistent across browsers

Performance Issues​

Slow Loading​

Symptoms

  • Chat takes long time to appear
  • Page loading slowed after adding chat
  • Timeout errors in chat interface

Optimization Steps

  1. Image optimization: Compress chat-related images
  2. Script optimization: Minimize JavaScript conflicts
  3. Caching: Implement proper caching strategies
  4. CDN usage: Leverage content delivery networks

Performance Monitoring

  • Google PageSpeed Insights: Test page speed impact
  • GTmetrix: Detailed performance analysis
  • Browser dev tools: Monitor network and performance
  • Real user monitoring: Track actual user experience

Memory Issues​

Symptoms

  • Browser crashes or freezes
  • Chat becomes unresponsive
  • Mobile devices running slowly

Solutions

  • Reduce animations: Minimize CPU-intensive effects
  • Optimize images: Use appropriate file sizes
  • Clean up code: Remove unnecessary scripts
  • Test on low-end devices: Ensure broad compatibility

Performance Monitoring

Advanced Troubleshooting​

JavaScript Console Debugging​

Accessing Console

  • Chrome: F12 > Console tab
  • Firefox: F12 > Console tab
  • Safari: Develop > Show JavaScript Console
  • Mobile: Use remote debugging tools

Common Error Messages

  • CORS errors: Cross-origin request issues
  • 404 errors: Missing resources or files
  • JavaScript errors: Code execution problems
  • Network errors: Connectivity issues

Network Analysis​

Monitoring Network Requests

  1. Open browser dev tools: F12 > Network tab
  2. Reload page: Monitor all network requests
  3. Filter by domain: Look for ShopGuide-related requests
  4. Check response codes: Identify failed requests

Common Network Issues

  • Blocked requests: Firewall or security software
  • Slow responses: Server or connectivity issues
  • Failed requests: Service unavailability
  • CORS blocks: Cross-origin policy restrictions

CSS Debugging​

Inspecting Styles

  1. Right-click chat element: Select "Inspect Element"
  2. Review applied styles: Check CSS rules
  3. Identify conflicts: Look for overridden styles
  4. Test modifications: Make temporary changes

Common CSS Issues

  • Specificity conflicts: Theme styles overriding chat styles
  • Z-index problems: Elements appearing behind others
  • Responsive issues: Styles not adapting to screen size
  • Font loading: Custom fonts not loading properly

Getting Help​

Self-Service Resources​

Documentation

  • ShopGuide help center: Comprehensive guides and tutorials
  • Shopify documentation: Theme development resources
  • Community forums: User discussions and solutions
  • Video tutorials: Visual troubleshooting guides

Diagnostic Tools

  • Browser dev tools: Built-in debugging capabilities
  • Online validators: CSS and HTML validation
  • Performance tools: Speed and optimization testing
  • Compatibility checkers: Cross-browser testing tools

Professional Support​

When to Contact Support

  • Persistent issues: Problems that don't resolve with basic troubleshooting
  • Complex integrations: Custom theme modifications needed
  • Performance problems: Significant impact on store performance
  • Urgent issues: Critical problems affecting customer experience

Support Channels

  • Live chat: Real-time assistance through ShopGuide dashboard
  • Email support: Detailed technical support
  • Screen sharing: Visual troubleshooting sessions
  • Phone support: Available for Enterprise customers

Escalation Process​

Information to Provide

  • Store URL: Your Shopify store address
  • Theme name: Current theme and version
  • Browser details: Browser type and version
  • Error messages: Exact error text and screenshots
  • Steps to reproduce: Detailed reproduction steps

Prevention Strategies​

Best Practices​

Regular Maintenance

  • Keep themes updated: Install theme updates promptly
  • Monitor performance: Regular speed and functionality checks
  • Test after changes: Verify chat works after any modifications
  • Backup configurations: Save working configurations

Proactive Monitoring

  • Set up alerts: Monitor for chat functionality issues
  • Regular testing: Periodic cross-browser and device testing
  • User feedback: Collect customer reports of issues
  • Analytics monitoring: Watch for drops in chat usage

Next Steps​

Maintain optimal integration:

Most integration issues can be resolved with systematic troubleshooting. When in doubt, start with the basics: clear cache, test in different browsers, and verify your subscription status.