Troubleshooting & Frequently Asked Questions (FAQ)

Welcome to the Visperity & EnSightX™ Troubleshooting and Knowledge Base. This comprehensive guide provides step-by-step diagnostic workflows, solutions to common setup questions, and best practices for optimizing both your AI search/assistant widgets and your EnSightX™ speed & business intelligence audits.

1. Troubleshooting Guide

Issue 1: The widget or search dropdown is not appearing on my website

1. Check Script Placement:
   • Verify that you copied the exact <script> tag from the Embed Code tab of your builder.
   • Ensure the script is placed before the closing </body> tag on your website template. It can be placed in the <head> section or inside the page body, but should never be placed after the closing </body> tag.
2. Verify Approved Domain Whitelist:
   • In Datasets & Knowledge, click ✏️ Edit on your active dataset.
   • Check the Approved Domains field. If you entered domain names (e.g. yourstore.com), ensure your live website domain is included. (Tip: If testing locally or on a staging domain like staging.yourstore.com, add both to the whitelist or leave the field blank to allow all domains).
3. Verify Target CSS Classes & Field Names:
   • For Live Search: Ensure your search input or form container has the exact class configured in search_container (e.g. class="sbpro-search-container").
   • For Embedded Search: Ensure your results page has a container element with the class configured in embedded_search_target_class (e.g. <div class="sbpro-embedded-container"></div>).

Issue 2: A search query is not returning the expected product

1. Check Knowledge Base Indexing:
   • Go to Datasets & Knowledge and use the search bar above the table to check if the product or article URL is indexed in your dataset.
   • If missing, use the Single Page Crawler or Manual Document Ingestion to index it.
2. Check Exact SKU / Keywords:
   • Click ✏️ Edit on the record and verify that your product SKUs or tags are listed under Product SKUs / Custom Keyword Tags (e.g. WH-1000, HEADPHONES).
3. Check Language Gating:
   • If searching on a localized store page (e.g. in Spanish), verify that you have translated the record into that language. Because Visperity enforces strict language gating, Spanish searches only return Spanish-indexed records.

Issue 3: How do I update prices or product descriptions?

• Option A (Manual Edit): Go to Datasets & Knowledge, find the product row, click ✏️ Edit, update the Price (e.g. $39.99) or Content, and click Save & Re-Vectorize Record.
• Option B (CSV Re-Upload): If you manage prices in a master CSV spreadsheet, simply upload an updated CSV via CSV Bulk Upload. Visperity will update the existing records and recalculate embeddings automatically.
• Option C (REST API): Update titles, content, and pricing data programmatically via the REST API.
• Option D (Workflow Automation): Update pricings via an automation setup through a provider such as Zapier or Make.
• Option E (Site Store Pro Direct Updates): If you are using Site Store Pro as your ecommerce platform, pricing and content updates will automatically (natively) update the indexed records on Visperity AI after setting up the API linkage in the Site Store Pro admin settings panel.

Issue 4: How do I remove a discontinued product or deleted page?

• Go to Datasets & Knowledge, find the record, and click the red Delete button. It will immediately be removed from the vector database and will no longer appear in search results or AI recommendations.
• Tip for E-Commerce Platforms: If you are using the REST API or Site Store Pro, product deletions, out-of-stock statuses, or CMS changes are automatically propagated into your Visperity AI vector index in real-time.

Issue 5: Understanding Failing Audits & Performance Diagnostics in EnSightX™

When you run an audit in EnSightX™, Google Lighthouse tests your webpage across dozens of speed, technical, and accessibility criteria. Here is how to diagnose and understand failing items:

1. Locating Failing Audits vs Opportunities:
   • In the Speed & Core Web Vitals audit tab, scroll down to the Optimization Opportunities & Diagnostics section.
   • Items flagged with 🔴 (Red - Critical) or 🟡 (Orange - Needs Improvement) indicate audits where your page lost points on Google's performance index.
2. Common Failing Audits & What They Mean:
   • Eliminate render-blocking resources: CSS stylesheets or JavaScript files in the <head> are stopping the browser from drawing the page until they finish downloading. Fix: Add defer or async to non-essential scripts and preload key CSS.
   • Properly size images & serve next-gen formats: Images are being sent at high desktop resolutions (e.g. 2400px wide) to mobile phone screens, or in legacy JPEG/PNG formats rather than compressed WebP/AVIF. Fix: Convert images to WebP and use responsive srcset attributes.
   • Reduce unused JavaScript / CSS: Bulky theme plugins or tracking scripts are loading hundreds of kilobytes of code that are never used on that specific page.
   • Avoid enormous network payloads: The total page weight exceeds 2.5 MB, leading to slow mobile load times and high mobile data costs for visitors.
   • Largest Contentful Paint element (LCP): The primary banner image or hero headline took longer than 2.5 seconds to become visible.
   • Cumulative Layout Shift (CLS): Images or ads lack explicit width and height attributes, causing the layout to jump around while loading.
3. Expanding Details: Click any failing audit row to view the exact asset URLs, file transfer sizes, and estimated time savings (e.g. "Potential savings: 1.42s • 480 KB").

Issue 6: How to Apply Recommended AI Code Fixes

EnSightX™ does not just identify speed bottlenecks—it generates complete, production-ready code snippets and instructions tailored to your specific website.

1. Opening the AI Code Fix Drawer:
   • In the Tri-Stream AI Recommendations tab, locate any Critical Action or Growth Opportunity card.
   • Click the ⚡ View Code Fix & Implementation button on the card. An interactive slide-over drawer will open on the right.
2. Exploring the 4 Fix Drawer Tabs:
   • 1. Ready-to-Use Code Snippet: Contains the exact HTML, CSS, JavaScript, or Apache/Nginx configuration code. Click the Copy Code button to copy it to your clipboard.
   • 2. Step-by-Step Implementation Instructions: Explains exactly which file or theme template to edit in your CMS (e.g. Shopify theme.liquid, WordPress header.php, or custom HTML).
   • 3. Commercial Impact & Revenue Rationale: Explains in clear commercial terms why this fix will improve conversion rates and Google SEO rankings.
   • 4. Verification & Testing Guide: Outlines the steps to verify that the code fix works as expected without breaking site functionality.
3. Safe Deployment Workflow:
   • Paste the code snippet into your staging environment or theme preview first.
   • Run a quick Dev vs. Live Comparative Audit (or audit the preview URL) in EnSightX™ to verify that speed scores increase before pushing the change live.

Issue 7: EnSightX™ Action Cards show "1-Stream (Speed Only)" instead of "Tri-Stream AI"

1. Check Google Cloud Credentials:
   • Go to Monitored Domains (`section=domains`), locate your website card, and click ✏️ Edit.
   • Check if you have uploaded your Google Service Account JSON Key and entered both your GA4 Property ID (e.g. 123456789) and Google Search Console Site URL (e.g. sc-domain:yourstore.com or https://yourstore.com/).
2. Verify Credentials Status Badge:
   • Look at the Credentials Status badge on your domain card. It will show 🟢 Google Analytics 4 & Search Console Connected when active.
   • If only the PageSpeed API key is set, EnSightX will run a 1-Stream speed audit. Once Google credentials are saved, all subsequent audits automatically upgrade to full Tri-Stream AI Multi-Signal Correlation.

Issue 8: Google Service Account Permission Errors (403 Forbidden / Not Found)

1. Verify Google Analytics 4 User Permissions:
   • Log into Google Analytics, go to Admin > Property Access Management.
   • Ensure you added your service account email address (e.g. [email protected]) as a Viewer (or Editor).
2. Verify Google Search Console User Permissions:
   • Log into Google Search Console, go to Settings > Users and Permissions.
   • Ensure the service account email is added with Full or Restricted viewer permissions.
3. Check Exact Search Console Site Format:
   • If your Search Console property is a Domain Property, enter sc-domain:yourstore.com.
   • If your Search Console property is a URL-Prefix Property, enter the exact URL with protocol and trailing slash (e.g. https://yourstore.com/).

Issue 9: Automated Weekly Background Scan Did Not Run

1. Verify Weekly Auto-Scan is Enabled:
   • Go to Monitored Domains, expand your domain's URL list, and ensure the Weekly Auto-Scan toggle is switched ON (🟢) for that specific URL.
2. Check Weekly Schedule Timing:
   • Background scans run automatically once every 7 days from the date the URL was added or last audited.
3. Verify Plan Auto-Scan Quotas:
   • Check your Weekly Auto-Scans quota meter at the top of the dashboard to ensure you have not exceeded your plan tier's scheduled URL limit.

2. Frequently Asked Questions (FAQ)

Q: How quickly do changes made in the dashboard go live on my website?

A: Whenever you click Save Settings, Visperity automatically updates and deploys your configuration to Amazon CloudFront CDN within seconds. However, if you changed widget styling or layout options, you must reinstall the newly generated embed script on your site to bypass browser caching.

NOTE: New data URL records, edits, or deletions in your dataset(s) are instantly live in real-time and do not require script reinstallation.

Q: Will Visperity slow down my website?

A: No. Visperity widgets and scripts are loaded asynchronously (async) and delivered through high-speed global CloudFront CDN servers. They never block page rendering, delay DOMContentLoaded, or negatively impact your Google Core Web Vitals.

Q: Does Visperity work with mobile devices?

A: Yes. All three widgets (AI Virtual Assistant, Live Search dropdown, and Embedded Search results) are 100% responsive and optimized for mobile screens, tablets, and desktops.

Q: What is the recommended format for thumbnail images?

A: Square (1:1) or 4:3 aspect ratio images in standard web formats (.jpg, .png, .webp) hosted on secure https:// URLs work best. You can also upload photos directly using the Upload to CDN button on any ingestion or edit form.

Q: How can I segment my datasets to use with specific areas on my site such as my online store products only or my knowledge base articles?

A: To segment a specific area of your site to use with any of the Visperity tools, simply create a new dataset and add that content only (URLs) to that dataset. If you install the script for that tool based on that dataset, it will limit the results only to the ingested URLs content.

You can also add the same content (URLs) to your main site dataset as well if you want to provide resource links from BOTH your primary site dataset and your secondary (segmented) site dataset.

[!NOTE] We provide a very generous number of quota URLs in every plan specifically to account for situations where the site requires duplication of some URLs in multiple datasets. We have not encountered any merchants who exceeded their content URL quota even when segmenting with different datasets. The primary reason most merchants will need to upgrade to a higher quota plan is due to the site usage (unique users) exceeding their plan’s sessions quota and not the available number of indexable URLs in their plan.

Q: What is the difference between Category Tags and Dataset Segmentation?

A:

• Category Tags (User Experience Labeling): Category tags are a visual labeling feature designed to enhance the customer browsing experience. When you tag a record with a category (e.g. PRODUCTS, SUPPORT FAQ, SHIPPING), that label appears in bold directly above the product/article title in Live Search dropdowns, Embedded Search results, and AI Virtual Assistant chat cards. Category tags do not restrict or filter search results—they provide clear visual context for visitors.
• Dataset Segmentation (Content Isolation): If you want a specific search box or chat widget to search only certain pages (for example, searching only documentation on /help and only products on /shop), create separate Datasets. Each dataset has its own unique embed script that strictly limits search results to its ingested URLs.

Q: How does Visperity protect customer privacy?

A: Visperity only references public product information and articles that you choose to index into your dataset. Customer search logs are stored securely in your private merchant account and are never shared or used to train public AI models.

Q: Why are my mobile performance scores lower than my desktop scores in EnSightX™?

A: Google audits mobile performance by simulating an average mid-tier smartphone (Moto G Power) on a throttled 4G cellular connection with restricted CPU processing power. Desktop audits run on a fast simulated broadband connection with full unthrottled desktop CPU performance.

Because the vast majority of e-commerce shoppers browse on mobile devices and cellular data, Google prioritizes mobile Core Web Vitals for mobile search rankings. Optimizing oversized images, deferring heavy JavaScript execution, and minifying CSS will quickly lift your mobile scores into the Green zone (90+).

Q: Why do my speed scores fluctuate slightly between consecutive audit runs?

A: Small fluctuations (e.g. ±2–4 points) are completely normal on any live website. They are caused by real-world web variability, including server response time fluctuations (TTFB), CDN cache warmth, third-party marketing tags loading in varying orders, and transient internet route congestion. For reliable benchmarking, focus on consistent performance trends over time and milestone baselines rather than single-digit micro-variations.

Q: How does EnSightX™ calculate estimated conversion rate and revenue uplift?

A: EnSightX™ calculates commercial impact by combining your site's actual monthly traffic (from GA4) with published e-commerce benchmark models (including research from Google, Deloitte, and Walmart showing that every 100ms improvement in mobile page speed increases conversion rates by +1.11% to +8.4%). By correlating your real Core Web Vitals lag with high-intent organic search keywords (from Search Console), EnSightX highlights high-value landing pages where speed fixes will yield immediate revenue growth.

Are my Google Cloud credentials and service account keys safe?

A: Yes, absolutely. All Google service account private keys and API credentials in EnSightX are firewalled and isolated strictly per-domain. They are encrypted before storage and used exclusively to authenticate secure REST calls to Google's official APIs on your behalf. They are never shared across domains, exposed in client-side code, or accessible to other users.

Can I run a Dev vs. Live comparison on a password-protected staging site?

A: Google PageSpeed Insights requires publicly accessible URLs to execute its Lighthouse audit engine. If your development or staging environment is behind basic HTTP authentication or an IP whitelist, temporarily allow Google's crawler IP ranges or place your staging site on a public staging subdomain (e.g. staging.yourstore.com) with a noindex robot meta tag while running the comparison.

How do daily audit quota resets work?

A: Your daily on-demand audit quota (e.g. 100 audits/day for Store Owner, 400/day for Developer, 2,000/day for Agency) resets automatically every 24 hours at midnight. Re-opening and reviewing past audits from Scan History or viewing saved reports does not consume any daily audit quota.