Handle Experience Builder and preview environments gracefully

README.md

@@ -329,6 +329,14 @@ The component inherits colors and fonts from your site theme automatically via S
 
 ## Troubleshooting
 
+### Component shows an error in Experience Builder or preview
+
+This is expected behaviour. The component displays an informational message — _"Chat is not available in the Experience Builder or preview environments. To test this component, publish the site and visit the published URL."_ — in all Experience Builder and preview environments. No "Try again" button is shown because retrying will not help.
+
+This is a Salesforce platform limitation: the Embedded Service bootstrap script and the SCRT configuration API are both served from the published site's domain (`*.my.site.com`), and Salesforce's own CORS and CSP policies block requests originating from the preview domains (`*.salesforce-experience.com`). There is no workaround at the component level.
+
+To test the component, publish your Experience Cloud site and visit the published URL.
+
 - **Chat not loading** — Verify Org ID, Deployment API Name, and Site URL match the Code Snippet exactly. Check that the deployment is published and the messaging channel is active.
 - **Timeout error** — Enable debug logs and check the browser console for which lifecycle event didn't fire. Common causes: deployment not published, site URL mismatch, or messaging channel not activated.
 - **CORS / frame-ancestors errors** (third-party embed) — Add your hosting domain to the deployment's Trusted Domains in Setup.

force-app/main/default/lwc/haaInlineEnhancedChat/haaInlineEnhancedChat.html

@@ -46,11 +46,13 @@ <h1 class="loading-heading">{labels.HAA_heading}</h1>
             <template lwc:if={isError}>
                 <div class="chat-error slds-text-color_error">
                     <p>{errorMessage}</p>
-                    <lightning-button variant="base" label={labels.HAA_retry_label} onclick={handleRetry}
-                        class="slds-m-top_small"></lightning-button>
+                    <template lwc:if={showRetryButton}>
+                        <lightning-button variant="base" label={labels.HAA_retry_label} onclick={handleRetry}
+                            class="slds-m-top_small"></lightning-button>
+                    </template>
                 </div>
             </template>
             <div lwc:ref="chatContainer" class="chat-container"></div>
         </div>
     </div>
-</template>
+</template>

force-app/main/default/lwc/haaInlineEnhancedChat/haaInlineEnhancedChat.js

@@ -107,6 +107,8 @@ const IFRAME_MAX_WAIT_MS = 6000;
 const DEFAULT_CHAT_HEIGHT = "550px";
 const MIN_CHAT_HEIGHT_PX = 400;
 const VERSION = "v1.03";
+const PREVIEW_ERROR_MSG =
+  "Chat is not available in the Experience Builder or preview environments. To test this component, publish the site and visit the published URL.";
 
 export default class HaaInlineEnhancedChat extends LightningElement {
   @api orgId;
@@ -135,6 +137,7 @@ export default class HaaInlineEnhancedChat extends LightningElement {
   _launchFallbackId = null;
   _sendFallbackId = null;
   _chatRevealed = false;
+  _isPreviewError = false;
   _boundListeners = {};
 
   // --- Computed properties ---
@@ -162,6 +165,10 @@ export default class HaaInlineEnhancedChat extends LightningElement {
     return this._state === STATE.ERROR;
   }
 
+  get showRetryButton() {
+    return !this._isPreviewError;
+  }
+
   _isMultiline = false;
 
   get inputRowClass() {
@@ -277,6 +284,11 @@ export default class HaaInlineEnhancedChat extends LightningElement {
 
   connectedCallback() {
     this._debug("version", VERSION);
+    if (this._isSitePreview()) {
+      this._isPreviewError = true;
+      this._dispatch(EVT.INIT_ERROR, { message: PREVIEW_ERROR_MSG });
+      return;
+    }
     if (this._hasValidConfig()) {
       this._loadBootstrapScript();
     }
@@ -388,6 +400,7 @@ export default class HaaInlineEnhancedChat extends LightningElement {
         this._pendingQuery = "";
         this.errorMessage = "";
         this._chatRevealed = false;
+        this._isPreviewError = false;
         break;
 
       default:
@@ -476,6 +489,12 @@ export default class HaaInlineEnhancedChat extends LightningElement {
     const query = (this.searchQuery || "").trim();
     if (!query) return;
 
+    if (this._isSitePreview()) {
+      this._isPreviewError = true;
+      this._dispatch(EVT.INIT_ERROR, { message: PREVIEW_ERROR_MSG });
+      return;
+    }
+
     if (!this._hasValidConfig()) {
       this._dispatch(EVT.INIT_ERROR, {
         message: this.labels.HAA_error_invalidConfig
@@ -519,10 +538,10 @@ export default class HaaInlineEnhancedChat extends LightningElement {
       this._initChat();
     };
     script.onerror = () => {
+      const isPreview = this._isSitePreview();
+      if (isPreview) this._isPreviewError = true;
       this._dispatch(EVT.INIT_ERROR, {
-        message: this._isSitePreview()
-          ? "Chat is not available in Experience Builder preview. Publish the site to test."
-          : this.labels.HAA_error_scriptLoadFailed
+        message: isPreview ? PREVIEW_ERROR_MSG : this.labels.HAA_error_scriptLoadFailed
       });
     };
     document.body.appendChild(script);
@@ -909,12 +928,15 @@ export default class HaaInlineEnhancedChat extends LightningElement {
   }
 
   _isSitePreview() {
+    // Match known Salesforce Experience Cloud builder/preview domains.
+    // Anchoring to salesforce-experience.com avoids false positives on
+    // customer-owned domains that might contain words like "preview" or "live".
     return [
-      "sitepreview",
-      "livepreview",
-      "live-preview",
-      "live.",
-      ".builder."
+      ".builder.salesforce-experience.com",
+      ".preview.salesforce-experience.com",
+      ".live-preview.salesforce-experience.com",
+      ".livepreview.salesforce-experience.com",
+      ".sitepreview.salesforce-experience.com"
     ].some((s) => document.URL.includes(s));
   }
 

force-app/main/default/lwc/haaSkeletonLoader/haaSkeletonLoader.js-meta.xml

@@ -1,9 +1,5 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <LightningComponentBundle xmlns="http://soap.sforce.com/2006/04/metadata">
     <apiVersion>65.0</apiVersion>
-    <isExposed>true</isExposed>
-    <targets>
-        <target>lightningCommunity__Page</target>
-        <target>lightningCommunity__Default</target>
-    </targets>
-</LightningComponentBundle>
+    <isExposed>false</isExposed>
+</LightningComponentBundle>