Skip to main content

Theme integration troubleshooting

When integrating ShopGuide with your Shopify theme, you might run into a handful of predictable issues. This guide covers how to diagnose and resolve them.

Chat Block Not Appearing​

Symptoms: block missing from theme editor's Apps category, or the widget doesn't show on live pages.

Diagnostic steps

  1. Confirm ShopGuide is installed and your subscription/trial is active (ShopGuide admin app → Settings/Billing)
  2. Confirm your theme is Online Store 2.0 — older themes don't support app blocks at all (see Shopify theme editor basics)
  3. Confirm the "ShopGuide Chat" block is actually added to the page/template you're viewing — a block only renders on the page(s) it was added to
  4. Confirm the pause chat storefront-wide toggle (ShopGuide admin app → Settings) isn't enabled
  5. Clear browser cache and hard refresh (Ctrl+F5 / Cmd+Shift+R)

Solutions

  • Re-add the block via Add Section → Apps → ShopGuide Chat if it's missing from the template
  • If the block exists but nothing renders, check the browser console for JavaScript errors
  • Try a different browser or incognito/private mode to rule out extensions

Styling and Appearance Problems​

Common issues

  • Colors don't match your brand
  • Text contrast is poor
  • The bubble overlaps another fixed element on the page (cart drawer, sticky add-to-cart, cookie banner, mobile nav bar)

Fixes

  • Adjust colors and the style template in the ShopGuide admin app's Appearance page — see Chat appearance & branding
  • Switch the bubble to the opposite corner, or enable "Store has mobile navigation bar" — see Chat positioning & layout
  • For anything not covered by settings, use the Custom CSS field and the widget's real selectors — see Advanced chat styling

Functionality Problems​

Symptoms: chat opens but messages don't send, no AI response, or an error appears in the chat.

Troubleshooting steps

  1. Confirm your ShopGuide subscription/plan hasn't hit its visitor limit (ShopGuide admin app → Billing)
  2. Check your internet connection
  3. Open the browser console (F12) and look for JavaScript or network errors
  4. Test in a different browser, and with other storefront apps/ad blockers temporarily disabled, to rule out a conflict
  5. Confirm the storefront isn't paused via the store-wide pause toggle

Browser-Specific Notes​

  • Ad blockers and privacy extensions can occasionally block the chat's script or network requests — test in incognito/private mode with extensions disabled to rule this out
  • Safari and Firefox tracking protection can interfere with analytics/consent-dependent behavior (e.g. proactive messages, which only load after analytics consent is granted) — this is expected behavior tied to the Shopify Customer Privacy API, not a bug
  • Always confirm you're testing on an up-to-date browser version before escalating

Mobile-Specific Troubleshooting​

Common problems

  • Bubble too small or hard to tap on small screens
  • Bubble overlapping a bottom mobile navigation bar
  • Slower response on older/low-end devices

Solutions

  • Increase the Bubble size setting (Settings → Bubble)
  • Enable "Store has mobile navigation bar" if your theme has one
  • Test on a few real devices, not just the theme editor's mobile preview

Theme Compatibility​

ShopGuide requires an Online Store 2.0 theme (app blocks aren't supported on older theme architectures). Dawn and other current Shopify Theme Store themes are supported out of the box. If you're on a heavily customized or legacy (pre-2.0) theme, you may need a theme upgrade before the block can be added at all — see Shopify theme editor basics.

Testing checklist after any theme update

  1. Confirm the block is still attached to the pages you expect
  2. Confirm the bubble still appears and opens correctly
  3. Confirm styling still matches (theme updates occasionally reset custom CSS injected elsewhere in the theme)

Advanced Debugging​

Browser console

  • Chrome/Firefox: F12 → Console tab
  • Safari: Develop → Show JavaScript Console
  • Look for errors originating from ShopGuide's own scripts (secure-chat-core.js, chat-styles.css, ab-test-engine-bundle.js)

Network tab

  • F12 → Network tab, reload the page
  • Filter for requests to your store's /apps/proxy/... or /apps/ai-agent-proxy/... paths
  • A failed or slow request here usually points to a subscription, rate-limit, or connectivity issue rather than a theme problem

Getting Help​

If basic troubleshooting doesn't resolve the issue, contact ShopGuide support with:

  • Your store's .myshopify.com domain
  • Theme name and whether it's Online Store 2.0
  • Browser and version
  • Console error messages/screenshots
  • Steps to reproduce

Next Steps​

Most integration issues come down to one of three things: the block isn't on the page you're viewing, the subscription/pause state is blocking it, or a fixed-position element is overlapping the bubble. Check those first.