Quick solutions to frequently encountered problems with TrialClouds virtual try-on widget.
Installation & Setup Issues
Widget Not Appearing on Page
Symptoms: Try-on button doesn't show up on product page
Possible Causes & Solutions:
Script Not Installed
Check: View page source (Ctrl+U), search for widget.trialclouds.com
Solution: Install embed script before </body> tag
Check: Look for button with class trialclouds-trial-widget-trigger-button
Solution: Add button HTML with correct class
Copy < button
class = " trialclouds-trial-widget-trigger-button "
data-product-id = " shirt-123 "
data-product-name = " Blue Shirt "
data-images = " [...] "
data-link = " https://yourstore.com/products/shirt "
>
Try On
</ button > JavaScript Error
Check: Browser console (F12) for errors
Solution: Fix JavaScript errors on page (may be blocking widget)
Check: Inspect button element, look for display: none or visibility: hidden
Solution: Remove conflicting CSS or adjust your theme styles
Symptoms: Button clicks, overlay appears, but widget doesn't function properly
Domain Not Configured
Check: Browser console shows "Domain not allowed" or CORS error
Solution: Add your domain to site configuration in dashboard (Managing Sites )
Example: Add yourstore.com AND www.yourstore.com if you use both
Incorrect Site ID
Check: Widget script has correct Site ID
Solution: Copy Site ID from dashboard, update script src
Copy <!-- Replace YOUR_SITE_ID with actual ID -->
< script src = " https://widget.trialclouds.com/script/YOUR_SITE_ID " ></ script > Check: Button must have data-product-id, data-product-name, data-images, data-link
Solution: Add all required attributes
Upload & Try-On Issues
"No Face Detected" Error
Symptoms: Customer uploads photo but gets error about face not detected
Face Not Visible in Photo
Cause: Photo doesn't show face clearly (profile view, facing away, covered)
Solution: Provide guidance to customers:
"For best results: ✓ Face the camera directly ✓ Remove sunglasses/masks ✓ Ensure good lighting ✓ Hair not covering entire face"
Photo Quality Too Low
Cause: Very small, blurry, or pixelated photos
Solution: Request higher resolution photo
Minimum: 400×400px with clear facial features
Cause: Photo too dark, extreme backlight (silhouette)
Solution: Customers should use well-lit photos
Upload Fails or Times Out
Symptoms: Photo upload gets stuck or fails
Cause: Customer photo >10MB
Solution: Ask customer to compress image or use smaller file
Automatic: Widget should auto-compress, but very large files may time out
Slow Internet Connection
Cause: Customer on slow network
Solution: Be patient, retry, or try on faster connection
Tip: Mobile data may be faster than slow WiFi
Cause: Outdated browser, security settings blocking upload
Solution: Update browser, try different browser (Chrome, Firefox, Safari)
Check: Disable browser extensions (ad blockers, privacy tools) temporarily
Try-On Processing Fails
Symptoms: Upload succeeds but AI processing fails or gets stuck
Insufficient AI Credits
Cause: Your account has no credits remaining
Check: Dashboard → Credits & Billing → Current Balance
Impact: Customers see error, no try-on completes
Product Image Quality Issue
Cause: Product images don't meet requirements (no model face visible)
Check: Review product images in data-images array
Solution: Replace with high-quality model photos showing clear faces
Cause: Temporary backend issue
Check: Try again after a few minutes
Solution: If persistent, contact support with error details
Face Detection Fails on Product Image
Cause: Product image doesn't have visible model face
Solution: Use image with clear model face as first image in array
Result & Display Issues
Try-On Result Looks Poor/Unrealistic
Symptoms: AI completes but result looks bad, unnatural, distorted
Low-Quality Product Images
Most Common Cause: Product image is low-res, poorly lit, or wrong angle
Requirements:
Minimum 800×800px (prefer 1500px)
Front-facing or near-front angle
Customer Photo Quality
Cause: Customer uploaded very low quality, blurry, or poorly lit photo
Solution: Educate customers on uploading good photos
Cause: Model in product photo is angled differently than customer photo
Solution: Use front-facing model photos that match typical selfie angles
Symptoms: Customer clicks download but nothing happens
Browser Pop-Up Blocker
Cause: Browser blocks automatic download
Solution: Customer should allow pop-ups for your domain
Browser Security Settings
Cause: Strict security/privacy settings
Solution: Try different browser or adjust settings temporarily
JavaScript Error
Check: Browser console (F12) for errors
Shopify-Specific Issues
Symptoms: After installing app, button block doesn't appear in theme editor
App Embed Not Enabled
Fix: Theme Editor → App Embeds → Enable "TrialClouds Try-On Widget"
Theme Not Compatible
Cause: Very old or highly customized theme
Fix: Refresh theme editor (Ctrl+F5 hard reload), re-select template
Symptoms: Enter Site ID in app embed settings but it doesn't save
Cause: Typo, extra spaces, wrong ID copied
Solution: Re-copy Site ID from dashboard (click "Copy Site ID" button)
Format: Should be alphanumeric string like cmkozmnbi00012euxrl81rx69
Theme Editor Not Saving
Fix: Click "Save" button explicitly before leaving editor
Try: Re-enter ID, click in another field to trigger save, then Save
Fix: Clear browser cache, try different browser
Shopify: Customer Data Not Capturing
Symptoms: "Capture Customer Data" enabled but visitor names/emails not showing in dashboard
Cause & Solution:
Customer Not Logged In: TrialClouds only captures data for logged-in Shopify customers
Anonymous shoppers won't have name/email in dashboard (expected)
To test: Log in to your Shopify store as a customer, then try widget
Symptoms: Delay before widget appears or operates
Slow Internet Connection
Cause: Customer or your server has slow connection
Solution: Use CDN for product images, optimize page overall
Check: Test on fast WiFi to confirm
Large Product Images
Cause: Serving 5MB product images
Solution: Optimize images (compress, use JPG, WebP, appropriate sizes)
Many Third-Party Scripts
Cause: Page has 10+ external scripts competing for bandwidth
Solution: Lazy load non-essential scripts, prioritize critical resources
Try-On Processing Takes Too Long
Symptoms: "Processing..." shows for >20 seconds
Normal Processing: 2-15 seconds
Slow: 15-25 seconds
Too Slow: >25 seconds
High Server Load
Cause: Peak usage time, many concurrent requests
Solution: Retry in a few minutes, usually temporary
Large Image Files
Cause: Customer uploaded very large photo (>5MB)
Solution: Widget auto-compresses, but huge files take longer
Network Latency
Cause: Long distance to servers, slow connection
Check: Other websites also slow? ISP/connection issue
If Persistent: Contact [email protected] with visitor ID and timestamp
Analytics & Dashboard Issues
No Data Showing in Dashboard
Symptoms: Analytics, visitors, or products sections are empty
Cause: Widget installed but no customers have used it
Solution: Test yourself, promote feature, wait for organic usage
Incorrect Date Range
Cause: Date filter set to future or very narrow range with no events
Solution: Change date range to "Last 30 Days" or "All Time"
Site Not Active
Cause: Site status set to "Inactive" in dashboard
Solution: Edit site → Set status to "Active" → Save
Recent Installation
Cause: Data takes up to 24 hours to appear initially
Solution: Wait 24 hours after first widget usage
Analytics Numbers Don't Match Expectations
Symptoms: Metrics seem too high/low compared to traffic
Common Misunderstandings:
"Zero Widget Opens"
Check button is actually being clicked (test yourself)
Verify domain is correctly configured
Ensure button has proper class
"High Opens, Low Try-Ons"
Customers open widget but don't upload
Fix: Add upload instructions, address privacy concerns
"Many Try-Ons, Few Downloads"
Symptoms: Works on desktop but not mobile devices
Check: Button has display: none on mobile in your theme CSS
Solution: Adjust mobile styles to show button
Touch Event Not Triggering
Cause: Button too small (touch target <44px)
Mobile Browser Compatibility
Test: Try different mobile browser (Chrome, Safari, Firefox)
Update: Ensure browser is up-to-date
Screen Size Issue
Cause: Widget overlay doesn't fit small screen
Note: Widget is responsive and should work on all screens
If broken: Report device model and browser to support
Camera Upload Not Working on Mobile
Symptoms: Can't access camera to take photo on mobile
Permission Denied
Cause: Customer denied camera access
Solution: Instruct to re-enable in browser/device settings
iOS: Settings → Safari → Camera → Allow
Android: Settings → Apps → Browser → Permissions → Camera → Allow
Cause: Your site uses HTTP (not secure)
Solution: Enable HTTPS on your site (required for camera access)
Browser Doesn't Support Camera Access
Rare: Very old mobile browsers
Solution: Update browser or use photo upload instead
Browser Compatibility
Supported Browsers:
✅ Chrome 90+ (Windows, Mac, Android)
✅ Firefox 88+ (Windows, Mac, Android)
✅ Edge 90+ (Windows, Mac)
If Using Supported Browser:
Clear Cache & Cookies
Browser settings → Clear browsing data → Cached files
Disable Extensions
Ad blockers, privacy tools may interfere
Test in Incognito/Private mode (extensions disabled by default)
Ensure browser is latest version
Try Different Browser
If works in Chrome but not Firefox, Firefox-specific issue
CORS & Security Errors
"CORS policy" Error in Console
Symptoms: Browser console shows:
Cause: Domain not whitelisted in site configuration
Solution:
Go to Dashboard → Sites → Edit Site
Add your exact domain (check www vs non-www)
If using subdomain, add wildcard or specific subdomain
Save and refresh page after 1-2 minutes
Examples:
If error shows origin 'https://www.yourstore.com' → Add www.yourstore.com to domains
If error shows origin 'https://shop.yourstore.com' → Add shop.yourstore.com
Guide: Managing Sites - Domain Configuration
Contact [email protected] envelope
✅ Issue persists after trying solutions above
✅ Error messages you don't understand
✅ Server errors (500, 503 responses)
✅ Credits deducted but try-on failed
✅ Data discrepancies in analytics
Include in Your Email:
Browser and device (e.g., "Chrome 120 on Windows 11")
Screenshots of error messages
Console errors (F12 → Console tab → screenshot)
Response Time: Usually 24-48 hours
Quick Troubleshooting Checklist
Before contacting support, verify:
✅ Widget script installed (in page source)
✅ Button has correct class (trialclouds-trial-widget-trigger-button)
✅ All required data attributes present (product-id, name, images, link)
✅ Site ID is correct (matches dashboard)
✅ Domain is configured in site settings
✅ Site status is "Active"
✅ Sufficient AI credits in account
✅ Product images meet quality requirements (model face visible)
✅ Browser is supported and up-to-date
✅ No JavaScript console errors
✅ Tested in different browser (isolate browser-specific issues)
Related Guides:
Still stuck? Email [email protected] envelope
