Theme integration troubleshooting
Integrating ShopGuide with a theme goes smoothly most of the time, but when it doesn't, the cause is usually one of a handful of predictable things. Here's how to work through them.
The chat block isn't showing up
Whether it's missing from the theme editor's Apps category, or just not appearing on live pages, work through this in order:
- Confirm ShopGuide is installed and your subscription or trial is active (ShopGuide admin → Settings/Billing)
- Confirm your theme is Online Store 2.0 — older themes don't support app blocks at all; see Shopify theme editor basics
- Confirm the ShopGuide Chat block is actually added to the page or template you're looking at — a block only renders where it's been placed
- Confirm the Global Kill Switch isn't active (ShopGuide admin → Settings). If it is, Settings shows the banner "Storefront loading is currently disabled. The theme will not load chat or A/B test logic on any page." and the button reads "Enable Chat & A/B Test Loading"; click it to turn the chat back on. (When the chat is live, the button reads "Disable Chat & A/B Test Loading".)
- Clear your browser cache and hard-refresh (Ctrl+F5 / Cmd+Shift+R)
- If the block is on the page more than once, only the copy highest up on the page is shown. Check that the one you want is the higher one; in the theme editor the other displays "ShopGuide Chat is already placed higher up on this page, so this copy is hidden."
If it's genuinely missing from the template, re-add it: Add Section → Apps → ShopGuide Chat. If the block's there but nothing renders, check the browser console for JavaScript errors, and try a different browser or an incognito window to rule out an extension.
Styling problems
Colors not matching your brand, weak contrast, or the bubble overlapping another fixed element on the page (a cart drawer, sticky add-to-cart bar, cookie banner, mobile nav) all trace back to the same few fixes: adjust colors and the style template on the Appearance page (see Chat appearance & branding), try the opposite corner or enable "Store has mobile navigation bar" (see Chat positioning & layout), or reach for Custom CSS with the widget's real selectors for anything the settings don't cover (see Advanced chat styling).
Chat opens but doesn't respond
Check your plan's visitor limit hasn't been hit (ShopGuide admin → Billing), check your own connection, then open the browser console (F12) and look for JavaScript or network errors. Testing in a different browser, and with other storefront apps or ad blockers temporarily disabled, rules out a conflict. Also worth a quick check: the Global Kill Switch in Settings.
A few browser-specific quirks
Ad blockers and privacy extensions occasionally block the chat's script or its network requests — incognito mode with extensions off is the fastest way to rule this out. Safari and Firefox tracking protection can interfere with anything that depends on analytics consent, like proactive messages, which only load once consent is granted — that's expected behavior tied to Shopify's Customer Privacy API, not a bug. And it's worth confirming you're on a reasonably current browser version before escalating anything further.
On mobile specifically
A bubble that's too small to comfortably tap, or one that overlaps a bottom navigation bar, usually just needs a bigger Bubble size (px) setting (Settings → Bubble) or "Store has mobile navigation bar" turned on. Also note that on phones the chat opens full screen when tapped. If a cart drawer or pop-up from your theme or another app seems to be missing after an add to cart, close the chat: a theme cart drawer with an ordinary stacking order opens behind the full-screen chat. Cookie banners and consent pop-ups stay on top. Slower response on older or low-end devices is worth testing on a couple of real phones rather than relying only on the theme editor's mobile preview.
Theme compatibility
Online Store 2.0 is required — app blocks don't exist on older theme architectures. Dawn and other current Theme Store themes work out of the box. A heavily customized or legacy theme may need an upgrade before the block can be added at all; see Shopify theme editor basics.
After any theme update, it's worth confirming three things: the block's still attached where you expect, the bubble still appears and opens correctly, and styling still matches — theme updates occasionally reset custom CSS injected elsewhere.
Digging deeper
In the browser console (F12 on Chrome/Firefox, Develop → Show JavaScript Console on Safari), look for errors from ShopGuide's own scripts — secure-chat-core.js, chat-styles.css, ab-test-engine-bundle.js. In the Network tab, filter for requests to your store's /apps/proxy/... or /apps/ai-agent-proxy/... paths; a failed or slow request there usually points to a subscription, rate-limit, or connectivity issue rather than anything theme-related.
If none of this resolves it, reach out to ShopGuide support with your store's .myshopify.com domain, your theme name and whether it's Online Store 2.0, your browser and version, any console error messages or screenshots, and the steps to reproduce it.