@frak-labs/core-sdk 1.0.0-beta.bd7d4823 → 1.0.0-beta.cb2a3a9a

package/src/clients/createIFrameFrakClient.ts

@@ -80,6 +80,10 @@ export function createIFrameFrakClient({
     // Resolved after first resolved-config is sent to iframe (prevents RPC before context exists)
     const contextSent = new Deferred<void>();
 
+    // Handshake timing: measured from client creation until the iframe
+    // lifecycle manager resolves the `isConnected` promise.
+    const handshakeStartedAt = Date.now();
+
     // Create our debug info gatherer
     const debugInfo = new DebugInfoGatherer(config, iframe);
 
@@ -180,6 +184,38 @@ export function createIFrameFrakClient({
             userAnonymousClientId: getClientId(),
         });
         openPanel.init();
+        openPanel.track("sdk_initialized", {
+            sdkVersion: process.env.SDK_VERSION,
+        });
+
+        // Race the connection against the heartbeat timeout so we can
+        // distinguish "connected" from "timeout" cleanly without touching
+        // the heartbeat plumbing. 30s matches `HEARTBEAT_TIMEOUT`.
+        let settled = false;
+        const timeoutHandle = setTimeout(() => {
+            if (settled) return;
+            settled = true;
+            openPanel?.track("sdk_iframe_handshake_failed", {
+                reason: "timeout",
+            });
+        }, 30_000);
+        lifecycleManager.isConnected
+            .then(() => {
+                if (settled) return;
+                settled = true;
+                clearTimeout(timeoutHandle);
+                openPanel?.track("sdk_iframe_connected", {
+                    handshake_duration_ms: Date.now() - handshakeStartedAt,
+                });
+            })
+            .catch(() => {
+                if (settled) return;
+                settled = true;
+                clearTimeout(timeoutHandle);
+                openPanel?.track("sdk_iframe_handshake_failed", {
+                    reason: "unknown",
+                });
+            });
     }
 
     // Perform the post connection setup
@@ -189,6 +225,7 @@ export function createIFrameFrakClient({
         lifecycleManager,
         configPromise,
         contextSent,
+        openPanel,
     })
         .then(() => debugInfo.updateSetupStatus(true))
         .catch((err) => {
@@ -273,12 +310,14 @@ async function postConnectionSetup({
     lifecycleManager,
     configPromise,
     contextSent,
+    openPanel,
 }: {
     config: FrakWalletSdkConfig;
     rpcClient: SdkRpcClient;
     lifecycleManager: IframeLifecycleManager;
     configPromise: Promise<MerchantConfigResult> | undefined;
     contextSent: Deferred<void>;
+    openPanel: OpenPanel | undefined;
 }): Promise<void> {
     await lifecycleManager.isConnected;
 
@@ -300,6 +339,12 @@ async function postConnectionSetup({
         const allowedDomains = merchantConfig?.allowedDomains ?? [];
         const raw = merchantConfig?.sdkConfig;
 
+        // Per-field merge: backend wins over SDK static config.
+        const mergedAttribution =
+            raw?.attribution || config.attribution
+                ? { ...config.attribution, ...raw?.attribution }
+                : undefined;
+
         sdkConfigStore.setConfig(
             raw
                 ? {
@@ -319,6 +364,7 @@ async function postConnectionSetup({
                       translations: raw.translations,
                       placements: raw.placements,
                       components: raw.components,
+                      attribution: mergedAttribution,
                   }
                 : {
                       isResolved: true,
@@ -330,11 +376,16 @@ async function postConnectionSetup({
                       homepageLink: config.metadata.homepageLink,
                       lang: config.metadata.lang,
                       currency: config.metadata.currency,
+                      attribution: mergedAttribution,
                   }
         );
     };
 
-    // Send the resolved-config lifecycle event to the iframe
+    // Send the resolved-config lifecycle event to the iframe.
+    // This is where we also update SDK-side OpenPanel global props with
+    // `merchantId` + `domain` (first time they are known) so every
+    // subsequent SDK event is merchant-attributed. We pass
+    // `sdkAnonymousId` through so the listener can join SDK funnels.
     let mergeTokenConsumed = false;
     const sendLifecycleConfig = (resolved: SdkResolvedConfig) => {
         const token = mergeTokenConsumed ? undefined : pendingMergeToken;
@@ -351,8 +402,22 @@ async function postConnectionSetup({
                   css: resolved.css,
                   translations: resolved.translations,
                   placements: resolved.placements,
+                  attribution: resolved.attribution,
               }
-            : undefined;
+            : resolved.attribution
+              ? { attribution: resolved.attribution }
+              : undefined;
+
+        const sdkAnonymousId = getClientId();
+
+        if (openPanel) {
+            const current = openPanel.global ?? {};
+            openPanel.setGlobalProperties({
+                ...current,
+                merchantId: resolved.merchantId,
+                domain: resolved.domain ?? "",
+            });
+        }
 
         rpcClient.sendLifecycle({
             clientLifecycle: "resolved-config",
@@ -361,6 +426,7 @@ async function postConnectionSetup({
                 domain: resolved.domain ?? "",
                 allowedDomains: resolved.allowedDomains ?? [],
                 sourceUrl: window.location.href,
+                ...(sdkAnonymousId && { sdkAnonymousId }),
                 ...(token && { pendingMergeToken: token }),
                 ...(sdkConfig && { sdkConfig }),
             },
@@ -412,5 +478,20 @@ async function postConnectionSetup({
         });
     }
 
-    await Promise.allSettled([pushCss(), pushI18n(), pushBackup()]);
+    // Inspect each setup result — a failed CSS/i18n/backup push leaves the
+    // partner UI in a broken-but-connected state (iframe reports
+    // `sdk_iframe_connected`, user sees no modal styles / wrong locale).
+    // Surface it as a distinct handshake reason so dashboards can
+    // distinguish timeout vs. asset-push failures.
+    const results = await Promise.allSettled([
+        pushCss(),
+        pushI18n(),
+        pushBackup(),
+    ]);
+    const hasFailedAssetPush = results.some((r) => r.status === "rejected");
+    if (hasFailedAssetPush) {
+        openPanel?.track("sdk_iframe_handshake_failed", {
+            reason: "asset_push",
+        });
+    }
 }

package/src/index.ts

@@ -12,6 +12,8 @@ export { type LocalesKey, locales } from "./constants/locales";
 
 // Types
 export type {
+    AttributionDefaults,
+    AttributionParams,
     ClientLifecycleEvent,
     CompressedData,
     Currency,
@@ -100,7 +102,6 @@ export {
     type DeepLinkFallbackOptions,
     decompressJsonFromB64,
     FrakContextManager,
-    type FrakEvent,
     type FullSsoParams,
     findIframeInOpener,
     formatAmount,
@@ -115,6 +116,8 @@ export {
     isFrakDeepLink,
     isInAppBrowser,
     isIOS,
+    type MergeAttributionInput,
+    mergeAttribution,
     redirectToExternalBrowser,
     sdkConfigStore,
     toAndroidIntentUrl,
@@ -122,4 +125,8 @@ export {
     triggerDeepLinkWithFallback,
     withCache,
 } from "./utils";
+export type {
+    SdkEventMap,
+    SdkHandshakeFailureReason,
+} from "./utils/analytics";
 export { computeLegacyProductId } from "./utils/computeLegacyProductId";

package/src/types/config.ts

@@ -1,3 +1,5 @@
+import type { AttributionDefaults } from "./tracking";
+
 /**
  * All the currencies available
  * @category Config
@@ -78,6 +80,13 @@ export type FrakWalletSdkConfig = {
      * @defaultValue true
      */
     waitForBackendConfig?: boolean;
+    /**
+     * Default attribution params (UTM / via / ref) appended to outbound
+     * sharing URLs. Per-call `displaySharingPage` overrides win, then backend
+     * config, then this SDK-level default. `utm_content` is intentionally
+     * excluded — it is per-content/per-product, never a merchant-wide default.
+     */
+    attribution?: AttributionDefaults;
 };
 
 /**

package/src/types/index.ts

@@ -80,6 +80,8 @@ export type { UserReferralStatusType } from "./rpc/userReferralStatus";
 export type { WalletStatusReturnType } from "./rpc/walletStatus";
 // Tracking
 export type {
+    AttributionDefaults,
+    AttributionParams,
     TrackArrivalParams,
     TrackArrivalResult,
     UtmParams,

package/src/types/lifecycle/client.ts

@@ -59,6 +59,13 @@ type ResolvedConfigEvent = {
          * When present, listener should execute identity merge in background.
          */
         pendingMergeToken?: string;
+        /**
+         * Persistent per-origin anonymous id generated on the partner site
+         * (SDK-side localStorage). Propagated here so the listener can
+         * set it as an OpenPanel global property and stitch SDK events
+         * with listener events in the same funnel.
+         */
+        sdkAnonymousId?: string;
         sdkConfig?: ResolvedSdkConfig;
     };
 };

package/src/types/resolvedConfig.ts

@@ -1,4 +1,5 @@
 import type { Currency, Language } from "./config";
+import type { AttributionDefaults } from "./tracking";
 
 /**
  * Response from the merchant resolve endpoint
@@ -80,6 +81,12 @@ export type ResolvedSdkConfig = {
     placements?: Record<string, ResolvedPlacement>;
     /** Global component defaults (used when no placement override exists) */
     components?: ResolvedPlacement["components"];
+    /**
+     * Default attribution params applied when building outbound sharing URLs.
+     * Per-call overrides win over these backend defaults; `utm_content` is
+     * intentionally excluded (per-content/per-product, never a merchant default).
+     */
+    attribution?: AttributionDefaults;
 };
 
 /**
@@ -125,4 +132,7 @@ export type SdkResolvedConfig = {
 
     /** Global component defaults (fallback for placement-level overrides) */
     components?: ResolvedPlacement["components"];
+
+    /** Merged attribution defaults: backend > SDK static config */
+    attribution?: AttributionDefaults;
 };

package/src/types/rpc/displaySharingPage.ts

@@ -1,5 +1,6 @@
 import type { InteractionTypeKey } from "../../constants/interactionTypes";
 import type { I18nConfig } from "../config";
+import type { AttributionParams } from "../tracking";
 
 /**
  * Product information to display on the sharing page
@@ -19,6 +20,11 @@ export type SharingPageProduct = {
      * When provided and the product is selected, this link is used instead of the default sharing link
      */
     link?: string;
+    /**
+     * Optional `utm_content` value to apply when this product is selected.
+     * Falls back to the page-level `attribution.utmContent` when omitted.
+     */
+    utmContent?: string;
 };
 
 /**
@@ -37,6 +43,18 @@ export type DisplaySharingPageParamsType = {
      * If not provided, the sharing link will be generated from the current page URL + merchant context
      */
     link?: string;
+    /**
+     * Optional attribution overrides for the outbound sharing URL.
+     *
+     * When provided (even as an empty object), Frak adds standard affiliation
+     * params (`utm_source=frak`, `utm_medium=referral`, `utm_campaign=<merchantId>`,
+     * `ref=<clientId>`, `via=frak`) alongside `fCtx`. Existing UTMs on the base
+     * URL are preserved (gap-fill). Set this to `null` to disable attribution
+     * params entirely (only `fCtx` is added).
+     *
+     * @default {} — defaults applied
+     */
+    attribution?: AttributionParams | null;
     /**
      * Optional metadata overrides for the sharing page
      */

package/src/types/tracking.ts

@@ -8,6 +8,42 @@ export type UtmParams = {
     content?: string;
 };
 
+/**
+ * Attribution parameters appended to outbound sharing URLs.
+ *
+ * Defaults are derived from the V2 Frak context when available:
+ * - `utmSource`: `"frak"`
+ * - `utmMedium`: `"referral"`
+ * - `utmCampaign`: merchantId (`context.m`)
+ * - `via`: `"frak"`
+ * - `ref`: clientId (`context.c`)
+ *
+ * Fields explicitly set here override the defaults. Existing params on the
+ * base URL are preserved (gap-fill policy) to respect merchant-provided UTMs.
+ */
+export type AttributionParams = {
+    utmSource?: string;
+    utmMedium?: string;
+    utmCampaign?: string;
+    utmContent?: string;
+    utmTerm?: string;
+    via?: string;
+    ref?: string;
+};
+
+/**
+ * Merchant-level attribution defaults.
+ *
+ * Same shape as {@link AttributionParams} minus `utmContent`, because
+ * `utm_content` describes the specific content/creative being shared and is
+ * inherently per-call or per-product (never a merchant-wide default).
+ *
+ * Used as the shape for both:
+ * - `FrakWalletSdkConfig.attribution` (SDK-side compile-time defaults)
+ * - Backend merchant-config attribution (dashboard-driven defaults)
+ */
+export type AttributionDefaults = Omit<AttributionParams, "utmContent">;
+
 export type TrackArrivalParams = {
     /** @deprecated V1 legacy — use referrerClientId for v2 contexts */
     referrerWallet?: Address;

package/src/utils/FrakContext.test.ts

@@ -121,6 +121,157 @@ describe("FrakContextManager", () => {
                 expect(result).toContain("baz=qux");
                 expect(result).toContain("fCtx=");
             });
+
+            describe("update with attribution", () => {
+                const url = "https://example.com/product";
+
+                it("should apply default attribution params when attribution is omitted", () => {
+                    const result = FrakContextManager.update({
+                        url,
+                        context: v2Context,
+                    });
+
+                    expect(result).toBeDefined();
+                    expect(result).toContain("fCtx=");
+                    const parsedUrl = new URL(result!);
+                    expect(parsedUrl.searchParams.get("utm_source")).toBe(
+                        "frak"
+                    );
+                    expect(parsedUrl.searchParams.get("utm_medium")).toBe(
+                        "referral"
+                    );
+                    expect(parsedUrl.searchParams.get("utm_campaign")).toBe(
+                        v2Context.m
+                    );
+                    expect(parsedUrl.searchParams.get("via")).toBe("frak");
+                    expect(parsedUrl.searchParams.get("ref")).toBe(v2Context.c);
+                });
+
+                it("should apply default attribution params when attribution is an empty object", () => {
+                    const result = FrakContextManager.update({
+                        url,
+                        context: v2Context,
+                        attribution: {},
+                    });
+
+                    expect(result).toBeDefined();
+                    const parsedUrl = new URL(result!);
+                    expect(parsedUrl.searchParams.get("utm_source")).toBe(
+                        "frak"
+                    );
+                    expect(parsedUrl.searchParams.get("utm_medium")).toBe(
+                        "referral"
+                    );
+                    expect(parsedUrl.searchParams.get("utm_campaign")).toBe(
+                        v2Context.m
+                    );
+                    expect(parsedUrl.searchParams.get("via")).toBe("frak");
+                    expect(parsedUrl.searchParams.get("ref")).toBe(v2Context.c);
+                    expect(
+                        parsedUrl.searchParams.get("utm_content")
+                    ).toBeNull();
+                    expect(parsedUrl.searchParams.get("utm_term")).toBeNull();
+                });
+
+                it("should honor overrides over defaults", () => {
+                    const result = FrakContextManager.update({
+                        url,
+                        context: v2Context,
+                        attribution: {
+                            utmSource: "newsletter",
+                            utmMedium: "email",
+                            utmCampaign: "spring-sale",
+                            utmContent: "hero-banner",
+                            utmTerm: "wallet",
+                            via: "partner",
+                            ref: "alice",
+                        },
+                    });
+
+                    const parsedUrl = new URL(result!);
+                    expect(parsedUrl.searchParams.get("utm_source")).toBe(
+                        "newsletter"
+                    );
+                    expect(parsedUrl.searchParams.get("utm_medium")).toBe(
+                        "email"
+                    );
+                    expect(parsedUrl.searchParams.get("utm_campaign")).toBe(
+                        "spring-sale"
+                    );
+                    expect(parsedUrl.searchParams.get("utm_content")).toBe(
+                        "hero-banner"
+                    );
+                    expect(parsedUrl.searchParams.get("utm_term")).toBe(
+                        "wallet"
+                    );
+                    expect(parsedUrl.searchParams.get("via")).toBe("partner");
+                    expect(parsedUrl.searchParams.get("ref")).toBe("alice");
+                });
+
+                it("should preserve merchant-provided UTMs on the base URL (gap-fill)", () => {
+                    const baseUrl =
+                        "https://example.com/product?utm_source=google&utm_campaign=merchant-spring";
+                    const result = FrakContextManager.update({
+                        url: baseUrl,
+                        context: v2Context,
+                        attribution: {},
+                    });
+
+                    const parsedUrl = new URL(result!);
+                    // Merchant-provided values preserved
+                    expect(parsedUrl.searchParams.get("utm_source")).toBe(
+                        "google"
+                    );
+                    expect(parsedUrl.searchParams.get("utm_campaign")).toBe(
+                        "merchant-spring"
+                    );
+                    // Missing ones filled by Frak defaults
+                    expect(parsedUrl.searchParams.get("utm_medium")).toBe(
+                        "referral"
+                    );
+                    expect(parsedUrl.searchParams.get("ref")).toBe(v2Context.c);
+                });
+
+                it("should skip fields with empty-string overrides", () => {
+                    const result = FrakContextManager.update({
+                        url,
+                        context: v2Context,
+                        attribution: { utmContent: "", utmTerm: "" },
+                    });
+
+                    const parsedUrl = new URL(result!);
+                    expect(parsedUrl.searchParams.has("utm_content")).toBe(
+                        false
+                    );
+                    expect(parsedUrl.searchParams.has("utm_term")).toBe(false);
+                });
+
+                it("should skip context-derived defaults for V1 (no merchantId/clientId)", () => {
+                    const v1Context: FrakContextV1 = {
+                        r: "0x1234567890123456789012345678901234567890" as Address,
+                    };
+                    const result = FrakContextManager.update({
+                        url,
+                        context: v1Context,
+                        attribution: {},
+                    });
+
+                    const parsedUrl = new URL(result!);
+                    // Static defaults still applied
+                    expect(parsedUrl.searchParams.get("utm_source")).toBe(
+                        "frak"
+                    );
+                    expect(parsedUrl.searchParams.get("utm_medium")).toBe(
+                        "referral"
+                    );
+                    expect(parsedUrl.searchParams.get("via")).toBe("frak");
+                    // No derivable values from V1
+                    expect(parsedUrl.searchParams.has("utm_campaign")).toBe(
+                        false
+                    );
+                    expect(parsedUrl.searchParams.has("ref")).toBe(false);
+                });
+            });
         });
     });
 

package/src/utils/FrakContext.ts

@@ -1,5 +1,10 @@
 import { type Address, bytesToHex, hexToBytes, isAddress } from "viem";
-import type { FrakContext, FrakContextV1, FrakContextV2 } from "../types";
+import type {
+    AttributionParams,
+    FrakContext,
+    FrakContextV1,
+    FrakContextV2,
+} from "../types";
 import { isV2Context } from "../types";
 import { base64urlDecode, base64urlEncode } from "./compression/b64";
 import { compressJsonToB64 } from "./compression/compress";
@@ -91,20 +96,80 @@ function parse({ url }: { url: string }): FrakContext | null | undefined {
     return decompress(frakContext);
 }
 
+/**
+ * Default UTM medium value when attribution is requested.
+ */
+const DEFAULT_UTM_MEDIUM = "referral";
+
+/**
+ * Default utm_source / via value when attribution is requested.
+ */
+const DEFAULT_ATTRIBUTION_SOURCE = "frak";
+
+/**
+ * Resolve attribution defaults from the provided context.
+ *
+ * V2 contexts expose the merchantId (`m`) and clientId (`c`), which feed
+ * `utm_campaign` and `ref` respectively. V1 contexts have no equivalent, so
+ * only the static defaults (`utm_source`, `utm_medium`, `via`) apply.
+ */
+function resolveAttributionValues(
+    context: FrakContextV1 | FrakContextV2,
+    overrides: AttributionParams
+): Record<string, string | undefined> {
+    const isV2 = isV2Context(context);
+    return {
+        utm_source: overrides.utmSource ?? DEFAULT_ATTRIBUTION_SOURCE,
+        utm_medium: overrides.utmMedium ?? DEFAULT_UTM_MEDIUM,
+        utm_campaign: overrides.utmCampaign ?? (isV2 ? context.m : undefined),
+        utm_content: overrides.utmContent,
+        utm_term: overrides.utmTerm,
+        via: overrides.via ?? DEFAULT_ATTRIBUTION_SOURCE,
+        ref: overrides.ref ?? (isV2 ? context.c : undefined),
+    };
+}
+
+/**
+ * Append attribution query params to a URL using gap-fill semantics.
+ *
+ * Existing params on the URL are preserved untouched (so merchant-provided
+ * UTMs take precedence). Only missing keys are populated.
+ */
+function applyAttributionParams(
+    urlObj: URL,
+    context: FrakContextV1 | FrakContextV2,
+    attribution?: AttributionParams
+): void {
+    const values = resolveAttributionValues(context, attribution ?? {});
+    for (const [key, value] of Object.entries(values)) {
+        if (value === undefined || value === "") continue;
+        if (urlObj.searchParams.has(key)) continue;
+        urlObj.searchParams.set(key, value);
+    }
+}
+
 /**
  * Add or replace the `fCtx` query parameter in a URL with the given context.
  *
+ * Standard affiliation params (`utm_source`, `utm_medium`, `utm_campaign`,
+ * `ref`, `via`, ...) are always appended using gap-fill semantics: pre-existing
+ * params on the URL are preserved, defaults are derived from the context when
+ * applicable, and `attribution` overrides take precedence when provided.
+ *
  * @param args
  * @param args.url - The URL to update
  * @param args.context - The context to embed (V1 or V2)
+ * @param args.attribution - Optional attribution overrides. Defaults are applied even when omitted.
  * @returns The updated URL string, or null on failure
  */
 function update({
     url,
     context,
+    attribution,
 }: {
     url?: string;
     context: FrakContextV1 | FrakContextV2;
+    attribution?: AttributionParams;
 }): string | null {
     if (!url) return null;
 
@@ -113,6 +178,7 @@ function update({
 
     const urlObj = new URL(url);
     urlObj.searchParams.set(contextKey, compressedContext);
+    applyAttributionParams(urlObj, context, attribution);
     return urlObj.toString();
 }
 

package/src/utils/analytics/events/component.ts

@@ -0,0 +1,58 @@
+type ButtonBaseProps = {
+    placement?: string;
+    target_interaction?: string;
+    has_reward?: boolean;
+};
+
+type BannerVariant = "referral" | "inapp";
+type BannerOutcome = "clicked" | "dismissed";
+type PostPurchaseVariant = "referrer" | "referee";
+type ShareClickAction = "share-modal" | "embedded-wallet" | "sharing-page";
+
+export type SdkComponentEventMap = {
+    // Share button — click carries the resolved action + reward presence so
+    // we can compare per-merchant configuration impact on conversion.
+    share_button_clicked: ButtonBaseProps & {
+        click_action: ShareClickAction;
+    };
+    share_modal_error: ButtonBaseProps & {
+        error?: string;
+    };
+
+    // Wallet button (floating) — NOT actively used in production. No tracking.
+
+    // Open in app — path lets us compare deep-link destinations once we add more.
+    open_in_app_clicked: {
+        placement?: string;
+        path: string;
+    };
+    app_not_installed: {
+        placement?: string;
+        path: string;
+    };
+
+    // Banner — referral vs in-app variants share the funnel shape.
+    banner_impression: {
+        placement?: string;
+        variant: BannerVariant;
+        has_reward?: boolean;
+    };
+    banner_resolved: {
+        placement?: string;
+        variant: BannerVariant;
+        outcome: BannerOutcome;
+    };
+
+    // Post-purchase — the card drives the highest-intent entry into the
+    // referral loop; variant tells us whether we upsold a new share or
+    // celebrated an existing referee.
+    post_purchase_impression: {
+        placement?: string;
+        variant: PostPurchaseVariant;
+        has_reward?: boolean;
+    };
+    post_purchase_clicked: {
+        placement?: string;
+        variant: PostPurchaseVariant;
+    };
+};

package/src/utils/analytics/events/index.ts

@@ -0,0 +1,20 @@
+import type { SdkComponentEventMap } from "./component";
+import type { SdkLifecycleEventMap } from "./lifecycle";
+import type { SdkReferralEventMap } from "./referral";
+
+export type { SdkComponentEventMap } from "./component";
+export type {
+    SdkHandshakeFailureReason,
+    SdkLifecycleEventMap,
+} from "./lifecycle";
+export type { SdkReferralEventMap } from "./referral";
+
+/**
+ * Merged SDK event map. Consumed by the SDK's typed `trackEvent`.
+ * Stays isolated from wallet-shared because the SDK ships in partner
+ * bundles (different OpenPanel client id, no wallet-shared dependency
+ * allowed — see `packages/wallet-shared/AGENTS.md`).
+ */
+export type SdkEventMap = SdkLifecycleEventMap &
+    SdkComponentEventMap &
+    SdkReferralEventMap;