Merge pull request #146 from GleapSDK/v18-regions

feat: v18.0.0 data regions via Gleap.setRegion

Author: boehlerlukas

CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+## 18.0.0
+No breaking changes: major version aligned across all Gleap SDKs for the data-region release. Without `Gleap.setRegion` the SDK behaves exactly as 17.x (EU hosts).
+
+Added data regions: `Gleap.setRegion("eu" | "us")` (case-insensitive, call before `Gleap.initialize`) sets the API url, the SDK streaming (WS) url and the messenger realtime host for the region at once; `Gleap.getRegion()` returns the active region. The default region stays `eu`. An unknown region logs a console warning and changes nothing.
+(eu: `https://api.gleap.io`, `wss://ws.gleap.io`, `sockets.gleap.io`; us: `https://api.us.gleap.ai`, `wss://ws.us.gleap.ai`, `sockets.us.gleap.ai`)
+Manual host setters are unchanged and keep working: `setApiUrl`, `setWSApiUrl`, `setRealtimeHost`, `setFrameUrl`, `setBannerUrl`, `setModalUrl`. The last call wins: a manual setter called after `setRegion` overrides that single host, `setRegion` called after manual setters overrides the three region hosts.
+The static widget hosts stay global for every region (`messenger-app.gleap.io`, `outboundmedia.gleap.io`, `sdk.gleap.io`, `js.gleap.io`); `setRegion` never changes the frame, banner or modal url.
+Added `Gleap.setAgentConversationUrl` to override the `<gleap-agent-conversation>` iframe url (same as `setBannerUrl` / `setModalUrl`).
+Added `gleap.ai` to the default network-log blacklist, so the SDK does not record its own US traffic.
+Added the `GleapRegion` type to the TypeScript definitions.
+Fixed the consentmanager allowlist (`window.cmp_block_ignoredomains`): `messenger-app.gleap.io` was never actually added because the result of `concat` was discarded.

README.md

@@ -34,6 +34,15 @@ Add the following code to initialize the Gleap JavaScript SDK. Replace "SDK-TOKE
 Gleap.initialize("SDK-TOKEN");
 ```
 
+### Data region (optional)
+
+Projects hosted in the US data region select it before initializing. The default region is `eu`. See [docs/custom-widget-domains.md](docs/custom-widget-domains.md) for the host table and custom domains.
+
+```
+Gleap.setRegion("us");
+Gleap.initialize("SDK-TOKEN");
+```
+
 Congrats, you are now all set! Report your first bug by using the feedback button.
 
 ## 🤝 Need help?

docs/custom-widget-domains.md

@@ -22,6 +22,62 @@ Deploy the updated Messenger-App before releasing the updated SDK. An older
 messenger ignores `realtimeHost` and continues using its default realtime domain.
 The agent dashboard requires no changes.
 
+## Data regions
+
+Gleap projects live in a data region. Select it with `Gleap.setRegion` before
+`Gleap.initialize()`. The default region is `eu`, so existing integrations need
+no change.
+
+```js
+import Gleap from 'gleap';
+
+Gleap.setRegion('us'); // "eu" | "us", case-insensitive
+Gleap.initialize('YOUR_PROJECT_SDK_KEY');
+```
+
+`setRegion` sets three hosts at once:
+
+| Region | API (`setApiUrl`) | SDK streaming (`setWSApiUrl`) | Messenger realtime (`setRealtimeHost`) |
+|--------|-------------------|-------------------------------|----------------------------------------|
+| `eu` (default) | `https://api.gleap.io` | `wss://ws.gleap.io` | `sockets.gleap.io` |
+| `us` | `https://api.us.gleap.ai` | `wss://ws.us.gleap.ai` | `sockets.us.gleap.ai` |
+
+An unknown region logs a console warning and changes nothing.
+`Gleap.getRegion()` returns the active region. Without a `setRegion` call the
+realtime host is not sent to the messenger, which then uses its own default
+(`sockets.gleap.io`), exactly as before.
+
+### Order rule
+
+The last call wins:
+
+- A manual setter (`setApiUrl`, `setWSApiUrl`, `setRealtimeHost`) called AFTER
+  `setRegion` overrides that single host; the other two keep the region's value.
+- `setRegion` called after manual setters overrides all three region hosts.
+
+```js
+Gleap.setRegion('us');
+Gleap.setApiUrl('https://api.support.example.com'); // only the API host is custom
+Gleap.initialize('YOUR_PROJECT_SDK_KEY');
+```
+
+### Static widget hosts are global
+
+The static widget hosts are the same for every region: `messenger-app.gleap.io`
+(widget frame), `outboundmedia.gleap.io` (banners, modals, agent conversation),
+`sdk.gleap.io` and `js.gleap.io` (SDK script and assets). `setRegion` never
+changes `setFrameUrl`, `setBannerUrl`, `setModalUrl` or
+`setAgentConversationUrl`; those setters keep working independently.
+
+If you use a Content-Security-Policy or a network allowlist, US projects must
+additionally allow `https://api.us.gleap.ai`, `wss://ws.us.gleap.ai` and
+`wss://sockets.us.gleap.ai` (`connect-src`) next to the global `*.gleap.io`
+widget hosts.
+
+The region table lives in one place in the SDK: `src/GleapRegions.js`.
+
+> The EU region is also reachable on `api.eu.gleap.ai`, `ws.eu.gleap.ai` and `sockets.eu.gleap.ai`. The JavaScript SDK keeps the `*.gleap.io` hosts as its EU default for now, because sites with a Content-Security-Policy allow-list `*.gleap.io`; add `*.gleap.ai` to your CSP today so a later SDK release can switch the default without any change on your side. To use the new hosts already, set them with `setApiUrl`, `setWSApiUrl` and `setRealtimeHost`.
+
 ## Hosting requirements
 
 Provision DNS, valid TLS certificates and reverse proxy routing for each custom
@@ -36,7 +92,9 @@ Bundle the SDK with the customer's app or proxy its script delivery separately.
 Test with Gleap domains blocked, including files/uploads, avatars, help content,
 banners/modals and any enabled voice integrations. Proxy/configure remaining
 required resources before promising that no Gleap domains need allowlisting.
-Banner and modal frame URLs already have `setBannerUrl` and `setModalUrl` setters.
+Banner and modal frame URLs already have `setBannerUrl` and `setModalUrl` setters;
+the `<gleap-agent-conversation>` frame has `setAgentConversationUrl` (call it
+before the element is attached to the DOM).
 
 References:
 - https://developers.cloudflare.com/cloudflare-for-platforms/cloudflare-for-saas/start/advanced-settings/worker-as-origin/

index.d.ts

@@ -1,3 +1,6 @@
+/** Gleap data region. */
+export type GleapRegion = "eu" | "us";
+
 export namespace Gleap {
   function initialize(sdkKey: string, disablePing?: boolean): void;
   function sendSilentCrashReport(
@@ -54,6 +57,23 @@ export namespace Gleap {
     options?: { context?: any; initialQuestion?: string; initialMessage?: string }
   ): void;
   function isOpened(): boolean;
+  /**
+   * Sets the data region your Gleap project lives in. Call before initialize.
+   * Defaults to "eu". The value is case-insensitive; an unknown value logs a
+   * console warning and changes nothing.
+   *
+   * Sets three hosts at once:
+   * - eu: apiUrl `https://api.gleap.io`, wsApiUrl `wss://ws.gleap.io`, realtimeHost `sockets.gleap.io`
+   * - us: apiUrl `https://api.us.gleap.ai`, wsApiUrl `wss://ws.us.gleap.ai`, realtimeHost `sockets.us.gleap.ai`
+   *
+   * Order rule (last call wins): setApiUrl / setWSApiUrl / setRealtimeHost
+   * called AFTER setRegion override that single host; setRegion called after
+   * them overrides all three region hosts. The static widget hosts
+   * (setFrameUrl, setBannerUrl, setModalUrl) are global and never changed by setRegion.
+   */
+  function setRegion(region: GleapRegion): void;
+  /** Returns the current data region ("eu" unless setRegion was called). */
+  function getRegion(): GleapRegion;
   function setApiUrl(apiUrl: string): void;
   function setWSApiUrl(wsApiUrl: string): void;
   /** Messenger realtime hostname, without protocol or path. Set before initialize. */
@@ -63,6 +83,11 @@ export namespace Gleap {
   function closeModal(): void;
   function setBannerUrl(bannerUrl: string): void;
   function setModalUrl(modalUrl: string): void;
+  /**
+   * Custom url for the `<gleap-agent-conversation>` iframe. Applies to elements
+   * attached to the DOM after this call.
+   */
+  function setAgentConversationUrl(agentConversationUrl: string): void;
   function setMaxNetworkRequests(maxRequests: number): void;
   function startNetworkLogger(): void;
   function setNetworkLogsBlacklist(networkLogBlacklist: string[]): void;

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "gleap",
-  "version": "17.0.3",
+  "version": "18.0.0",
   "main": "build/cjs/index.js",
   "module": "build/esm/index.mjs",
   "exports": {

package.json

@@ -2,7 +2,7 @@ import AgentNetworkManager from './AgentNetworkManager';
 import ChecklistNetworkManager from './ChecklistNetworkManager';
 import GleapAdminManager from './GleapAdminManager';
 import GleapAgentChat from './GleapAgentChat';
-import { registerGleapAgentComponents } from './GleapAgentConversation';
+import { registerGleapAgentComponents, setGleapAgentConversationUrl } from './GleapAgentConversation';
 import GleapAgentToolManager from './GleapAgentToolManager';
 import GleapAiChatbarManager from './GleapAiChatbarManager';
 import GleapAudioManager from './GleapAudioManager';
@@ -619,6 +619,29 @@ class Gleap {
     GleapMetaDataManager.setAppBuildNumber(appBuildNumber);
   }
 
+  /**
+   * Sets the data region. Call before initialize.
+   * Applies the region's apiUrl, wsApiUrl and realtimeHost at once. The static
+   * widget hosts (frameUrl, bannerUrl, modalUrl) are global and stay untouched.
+   *
+   * Order rule: the last call wins. A manual setter (setApiUrl, setWSApiUrl,
+   * setRealtimeHost) called AFTER setRegion overrides that single host;
+   * setRegion called after manual setters overrides all three region hosts.
+   * Unknown regions log a warning and change nothing.
+   * @param {"eu"|"us"} region The data region (case-insensitive). Defaults to "eu".
+   */
+  static setRegion(region) {
+    GleapSession.getInstance().setRegion(region);
+  }
+
+  /**
+   * Returns the current data region.
+   * @returns {"eu"|"us"}
+   */
+  static getRegion() {
+    return GleapSession.getInstance().getRegion();
+  }
+
   /**
    * Set a custom ws api url.
    * @param {string} wsApiUrl
@@ -660,6 +683,15 @@ class Gleap {
     GleapModalManager.getInstance().setModalUrl(modalUrl);
   }
 
+  /**
+   * Set a custom agent conversation url (<gleap-agent-conversation>).
+   * Applies to elements attached to the DOM after this call.
+   * @param {string} agentConversationUrl
+   */
+  static setAgentConversationUrl(agentConversationUrl) {
+    setGleapAgentConversationUrl(agentConversationUrl);
+  }
+
   /**
    * Set a custom frame api url.
    * @param {string} frameUrl

src/Gleap.js

@@ -1,13 +1,25 @@
 import { GleapSession } from './Gleap';
 import { bootstrapGleapFrame } from './GleapHelper';
+import { GLEAP_DEFAULT_REGION, GLEAP_REGIONS } from './GleapRegions';
+
+let agentConversationUrl = 'https://outboundmedia.gleap.io/agent-conversation';
+
+/**
+ * Set a custom agent conversation url. Applies to <gleap-agent-conversation>
+ * elements attached to the DOM after this call.
+ * @param {string} url
+ */
+export const setGleapAgentConversationUrl = (url) => {
+  agentConversationUrl = url;
+};
 
 export const registerGleapAgentComponents = () => {
   if (typeof customElements === 'undefined' || typeof HTMLElement === 'undefined' || typeof window === 'undefined') return;
 
   if (!customElements.get('gleap-agent-conversation')) {
     class GleapAgentConversation extends HTMLElement {
       _iframe = null;
-      _agentConvUrl = 'https://outboundmedia.gleap.io/agent-conversation';
+      _agentConvUrl = agentConversationUrl;
       _messageListener = null;
       _config = {};
 
@@ -35,6 +47,7 @@ export const registerGleapAgentComponents = () => {
 
       _injectIframe() {
         if (this._iframe) return;
+        this._agentConvUrl = agentConversationUrl;
         this.style.display = 'block';
         this.style.width = '100%';
         this.style.height = '100%';
@@ -97,7 +110,7 @@ export const registerGleapAgentComponents = () => {
       _sendConfig() {
         if (!this._iframe?.contentWindow) return;
 
-        let apiUrl = 'https://api.gleap.io';
+        let apiUrl = GLEAP_REGIONS[GLEAP_DEFAULT_REGION].apiUrl;
         let sdkKey = '';
         let gleapId = '';
         let gleapHash = '';

src/GleapAgentConversation.js

@@ -8,6 +8,7 @@ import {
 } from './Gleap';
 import GleapAgentToolManager from './GleapAgentToolManager';
 import { applyGleapCSPNonce, bootstrapGleapFrame, runFunctionWhenDomIsReady } from './GleapHelper';
+import { GLEAP_DEFAULT_REGION, GLEAP_REGIONS } from './GleapRegions';
 
 export default class GleapAiChatbarManager {
   get chatbarUrl() {
@@ -377,7 +378,7 @@ export default class GleapAiChatbarManager {
   async _validateAgent(agentId) {
     try {
       const session = GleapSession.getInstance();
-      const apiUrl = session.apiUrl || 'https://api.gleap.io';
+      const apiUrl = session.apiUrl || GLEAP_REGIONS[GLEAP_DEFAULT_REGION].apiUrl;
 
       const headers = {};
       if (session.sdkKey) headers['Api-Token'] = session.sdkKey;

src/GleapAiChatbarManager.js

@@ -139,8 +139,11 @@ export default class GleapFrameManager {
   }
 
   autoWhiteListCookieManager = () => {
-    if (window && window.cmp_block_ignoredomains) {
-      window.cmp_block_ignoredomains.concat(['messenger-app.gleap.io']);
+    // Push in place: concat returns a new array and would leave the allowlist untouched.
+    if (window && Array.isArray(window.cmp_block_ignoredomains)) {
+      if (window.cmp_block_ignoredomains.indexOf('messenger-app.gleap.io') === -1) {
+        window.cmp_block_ignoredomains.push('messenger-app.gleap.io');
+      }
     }
   };