[SURF-1836] feat(tag): support custom-domain script attribute

README.md

@@ -31,6 +31,26 @@ cd test && ./serve.sh
 
 Open `http://localhost:8000/test/index.html` to test all embed types.
 
+## Custom Domains
+
+Add `data-custom-domain` to the Surface tag when an environment uses a verified
+custom domain:
+
+```html
+<script
+  src="https://cdn.jsdelivr.net/.../surface_tag.min.js"
+  site-id="your-environment-id"
+  data-custom-domain="demo.example.com">
+</script>
+```
+
+The tag sends lead identification, journey tracking, external-form events, and
+open-trigger requests to `https://demo.example.com/api/v1`. It also trusts form
+iframe messages from `https://demo.example.com`. The value must be an HTTPS
+hostname or origin without a path, query string, credentials, or fragment. If
+the attribute is absent or invalid, the tag continues to use
+`https://forms.withsurface.com`.
+
 ## Embedding Types
 
 - **Popup** -- modal overlay triggered by button click

src/conversions/conversion-listener.ts

@@ -35,7 +35,7 @@ const isConversionMessage = (data: any): data is ConversionMessage =>
 // Handles a `surface:conversion` message from a Surface form iframe: fires the
 // pixel in this (parent) page, then acks so the iframe knows not to fall back to
 // in-frame firing. The caller guarantees the origin is already trusted (checked
-// in the shared message listener against SURFACE_DOMAINS).
+// in the shared message listener against the runtime Surface-domain allowlist).
 export const handleConversionMessage = (event: MessageEvent, log: Logger): void => {
   const data = event.data;
   if (!isConversionMessage(data)) return;

src/external-form/external-form.ts

@@ -1,9 +1,9 @@
-import { EXTERNAL_FORM_API } from "../constants";
 import { isDebugMode } from "../utils/debug";
 import { sendBeacon } from "../utils/beacon";
 import { getSiteIdFromScript } from "../lead/site-id";
 import { attachFormHandlers } from "./form-handlers";
 import type { ExternalFormProps } from "../types";
+import { getSurfaceRuntimeConfig } from "../runtime-config";
 
 export class SurfaceExternalForm {
   initialRenderTime: Date;
@@ -27,7 +27,7 @@ export class SurfaceExternalForm {
     this.formStarted = {};
 
     this.config = {
-      serverBaseUrl: props?.serverBaseUrl || EXTERNAL_FORM_API,
+      serverBaseUrl: props?.serverBaseUrl || getSurfaceRuntimeConfig().apiBaseUrl,
       debugMode: isDebugMode(),
     };
 

src/index.ts

@@ -10,13 +10,15 @@ import { SurfaceExternalForm } from "./external-form/external-form";
 import { SurfaceEmbed } from "./embed/embed";
 import { resolveOpenTriggersOnLoad } from "./open-triggers/open-triggers";
 import { initReview } from "./review/review";
+import { initializeSurfaceRuntimeConfig } from "./runtime-config";
 
 const scriptTag = document.currentScript as HTMLScriptElement;
+const runtimeConfig = initializeSurfaceRuntimeConfig(scriptTag);
 const environmentId = getSiteIdFromScript(scriptTag);
 setEnvironmentId(environmentId);
 
 // Create singleton store
-const SurfaceTagStore = new SurfaceStore(environmentId);
+const SurfaceTagStore = new SurfaceStore(environmentId, runtimeConfig);
 
 // Expose public API on window (backwards compatible)
 const w = window as unknown as Record<string, unknown>;
@@ -30,7 +32,7 @@ w.SurfaceGetSiteIdFromScript = getSiteIdFromScript;
 
 // Auto-open a form when the host URL carries a configured `?<slug>=true` param.
 // Fire-and-forget; only touches the network when params are present.
-void resolveOpenTriggersOnLoad(environmentId);
+void resolveOpenTriggersOnLoad(environmentId, runtimeConfig);
 
 // Surface CMS review bridge. Inert unless the page is loaded inside the CMS
 // review iframe (?surface_review= token) — adds no listeners otherwise.

src/lead/identify.ts

@@ -1,6 +1,10 @@
-import { LEAD_DATA_TTL, LEAD_IDENTIFY_API } from "../constants";
+import { LEAD_DATA_TTL } from "../constants";
 import { getBrowserFingerprint } from "./fingerprint";
 import type { LeadData } from "../types";
+import {
+  getSurfaceRuntimeConfig,
+  type SurfaceRuntimeConfig,
+} from "../runtime-config";
 
 let environmentId: string | null = null;
 let identifyInProgress = false;
@@ -49,7 +53,8 @@ export function getLeadDataWithTTL(): LeadData | null {
 }
 
 export async function identifyLead(
-  envId: string
+  envId: string,
+  config: SurfaceRuntimeConfig = getSurfaceRuntimeConfig()
 ): Promise<LeadData | null> {
   if (identifyInProgress) {
     return waitForCachedData();
@@ -66,7 +71,7 @@ export async function identifyLead(
     const fingerprint = await getBrowserFingerprint(envId);
     const parentUrl = new URL(window.location.href);
 
-    const response = await fetch(LEAD_IDENTIFY_API, {
+    const response = await fetch(config.leadIdentifyApi, {
       method: "POST",
       headers: { "Content-Type": "application/json" },
       body: JSON.stringify({

src/open-triggers/open-triggers.ts

@@ -1,7 +1,10 @@
-import { EXTERNAL_FORM_API } from "../constants";
 import { SurfaceEmbed } from "../embed/embed";
 import { openTriggerOverlay } from "./open-trigger-overlay";
 import { OpenTriggerEntry, OpenTriggersMap, pickOpenTrigger } from "./resolve";
+import {
+  getSurfaceRuntimeConfig,
+  type SurfaceRuntimeConfig,
+} from "../runtime-config";
 
 const SESSION_PREFIX = "surface_open_triggers:";
 // Self-healing cache: re-fetch the map after this long so a slug retargeted/disabled
@@ -30,12 +33,15 @@ interface OverridableWindow {
  * present as `?<slug>=true`. Opens a form even if it isn't already embedded on the
  * page. No params → zero network. Always fails safe (never breaks the host page).
  */
-export async function resolveOpenTriggersOnLoad(environmentId: string | null): Promise<void> {
+export async function resolveOpenTriggersOnLoad(
+  environmentId: string | null,
+  config: SurfaceRuntimeConfig = getSurfaceRuntimeConfig()
+): Promise<void> {
   try {
     if (!environmentId) return;
     if (!window.location.search) return;
 
-    const map = await fetchOpenTriggersMap(environmentId);
+    const map = await fetchOpenTriggersMap(environmentId, config);
     const entry = pickOpenTrigger(window.location.search, map);
     if (!entry) return;
 
@@ -45,13 +51,16 @@ export async function resolveOpenTriggersOnLoad(environmentId: string | null): P
   }
 }
 
-async function fetchOpenTriggersMap(environmentId: string): Promise<OpenTriggersMap | null> {
+async function fetchOpenTriggersMap(
+  environmentId: string,
+  config: SurfaceRuntimeConfig
+): Promise<OpenTriggersMap | null> {
   const w = window as unknown as OverridableWindow;
 
   // Test/escape hatch: a directly-injected map bypasses the network entirely.
   if (w.__SURFACE_OPEN_TRIGGERS_MAP) return w.__SURFACE_OPEN_TRIGGERS_MAP;
 
-  const sessionKey = SESSION_PREFIX + environmentId;
+  const sessionKey = `${SESSION_PREFIX}${config.apiBaseUrl}:${environmentId}`;
   try {
     const cached = sessionStorage.getItem(sessionKey);
     if (cached) {
@@ -64,7 +73,7 @@ async function fetchOpenTriggersMap(environmentId: string): Promise<OpenTriggers
     // sessionStorage unavailable / malformed (e.g. privacy mode) — fall through to a live fetch.
   }
 
-  const base = w.__SURFACE_OPEN_TRIGGERS_BASE || EXTERNAL_FORM_API;
+  const base = w.__SURFACE_OPEN_TRIGGERS_BASE || config.apiBaseUrl;
   const response = await fetch(`${base}/environments/${encodeURIComponent(environmentId)}/open-triggers`);
   if (!response.ok) return null;
 

src/runtime-config.ts

@@ -0,0 +1,78 @@
+import {
+  EXTERNAL_FORM_API,
+  LEAD_IDENTIFY_API,
+  SURFACE_DOMAINS,
+  USER_JOURNEY_TRACKING_API,
+} from "./constants";
+
+export const CUSTOM_DOMAIN_ATTRIBUTE = "data-custom-domain";
+
+export interface SurfaceRuntimeConfig {
+  apiBaseUrl: string;
+  leadIdentifyApi: string;
+  userJourneyTrackingApi: string;
+  surfaceDomains: readonly string[];
+  customOrigin: string | null;
+}
+
+export const DEFAULT_SURFACE_RUNTIME_CONFIG: SurfaceRuntimeConfig = {
+  apiBaseUrl: EXTERNAL_FORM_API,
+  leadIdentifyApi: LEAD_IDENTIFY_API,
+  userJourneyTrackingApi: USER_JOURNEY_TRACKING_API,
+  surfaceDomains: SURFACE_DOMAINS,
+  customOrigin: null,
+};
+
+let runtimeConfig = DEFAULT_SURFACE_RUNTIME_CONFIG;
+
+function normalizeCustomOrigin(value: string): string | null {
+  const trimmed = value.trim();
+  if (!trimmed) return null;
+
+  try {
+    const url = new URL(trimmed.includes("://") ? trimmed : `https://${trimmed}`);
+    if (
+      url.protocol !== "https:" ||
+      url.username ||
+      url.password ||
+      url.pathname !== "/" ||
+      url.search ||
+      url.hash
+    ) {
+      return null;
+    }
+
+    return url.origin;
+  } catch {
+    return null;
+  }
+}
+
+export function resolveSurfaceRuntimeConfig(
+  scriptElement: HTMLScriptElement | null
+): SurfaceRuntimeConfig {
+  const customOrigin = normalizeCustomOrigin(
+    scriptElement?.getAttribute(CUSTOM_DOMAIN_ATTRIBUTE) ?? ""
+  );
+  if (!customOrigin) return DEFAULT_SURFACE_RUNTIME_CONFIG;
+
+  const apiBaseUrl = `${customOrigin}/api/v1`;
+  return {
+    apiBaseUrl,
+    leadIdentifyApi: `${apiBaseUrl}/lead/identify`,
+    userJourneyTrackingApi: `${apiBaseUrl}/lead/track`,
+    surfaceDomains: Array.from(new Set([...SURFACE_DOMAINS, customOrigin])),
+    customOrigin,
+  };
+}
+
+export function initializeSurfaceRuntimeConfig(
+  scriptElement: HTMLScriptElement | null
+): SurfaceRuntimeConfig {
+  runtimeConfig = resolveSurfaceRuntimeConfig(scriptElement);
+  return runtimeConfig;
+}
+
+export function getSurfaceRuntimeConfig(): SurfaceRuntimeConfig {
+  return runtimeConfig;
+}

src/store/message-listener.ts

@@ -1,11 +1,12 @@
-import { SURFACE_DOMAINS } from "../constants";
 import { handleConversionMessage } from "../conversions/conversion-listener";
+import { SURFACE_DOMAINS } from "../constants";
 import { identifyLead, getEnvironmentId } from "../lead/identify";
 import type { SurfaceStore } from "./store";
 
 export function initializeMessageListener(store: SurfaceStore): void {
   const handleMessage = (event: MessageEvent) => {
-    if (!event.origin || !(SURFACE_DOMAINS as readonly string[]).includes(event.origin)) {
+    const surfaceDomains = store.surfaceDomains ?? SURFACE_DOMAINS;
+    if (!event.origin || !surfaceDomains.includes(event.origin)) {
       return;
     }
 
@@ -19,7 +20,10 @@ export function initializeMessageListener(store: SurfaceStore): void {
 
       const envId = getEnvironmentId();
       if (envId) {
-        identifyLead(envId)
+        const identify = store.config?.customOrigin
+          ? identifyLead(envId, store.config)
+          : identifyLead(envId);
+        identify
           .then(() => store.sendPayloadToIframes("LEAD_DATA_UPDATE"))
           .catch((e) => console.log("Failed identify", e));
       } else {