@digia-engage/core 2.3.1 → 2.4.0

package/src/DigiaProvider.tsx

@@ -3,17 +3,27 @@ import {
     Animated,
     Dimensions,
     Modal,
+    Platform,
     Pressable,
     StyleSheet,
     Text,
     View,
+    requireNativeComponent,
     useWindowDimensions,
 } from 'react-native';
+
+// Native view that hosts Digia's Compose overlay (dialogs / bottom sheets).
+// pointerEvents="none" ensures it never intercepts touches.
+const NativeDigiaHostView =
+    Platform.OS === 'android' || Platform.OS === 'ios'
+        ? requireNativeComponent<{ style?: object; pointerEvents?: string }>('DigiaHostView')
+        : null;
 import { computePosition, flip, offset, shift } from '@floating-ui/core';
 import Svg, { Path } from 'react-native-svg';
 import { Digia } from './Digia';
 import { digiaGuideController, type DigiaGuideRequest } from './DigiaGuideController';
 import { digiaAnchorRegistry, type AnchorLayout } from './digiaAnchorRegistry';
+import { digiaHealthReporter, HealthEventType } from './DigiaHealthReporter';
 import { digiaActionHandler, type ActionCallbacks } from './actionHandler';
 import type { DismissReason } from './types';
 import type { Action, SpotlightConfig, SpotlightStep, TooltipConfig, TooltipStep } from './templateTypes';
@@ -247,9 +257,25 @@ function TooltipOverlay({
         setLayout(null);
         setFloatPos(null);
         if (!ready) return;
+        if (!digiaAnchorRegistry.isRegistered(step.anchorKey)) {
+            // eslint-disable-next-line no-console
+            console.warn(`[Digia] campaign dropped — anchor_key "${step.anchorKey}" is not registered on this screen (campaign_key=${request.campaignKey}, step=${stepIndex})`);
+            digiaHealthReporter.report(HealthEventType.anchor_not_on_screen, {
+                campaign_key: request.campaignKey,
+                reason: 'anchor_key_not_registered',
+                anchor_key: step.anchorKey,
+                step_index: stepIndex,
+            });
+            digiaGuideController.cancel(request.payloadId);
+            return;
+        }
         let skipCached = false;
         const unsub = digiaAnchorRegistry.subscribe(step.anchorKey, (l) => {
             if (!skipCached) return;
+            if (l.width === 0 || l.height === 0) {
+                digiaGuideController.cancel(request.payloadId);
+                return;
+            }
             const { width: screenW, height: screenH } = Dimensions.get('window');
             if (l.pageY + l.height <= 0 || l.pageY >= screenH || l.pageX + l.width <= 0 || l.pageX >= screenW) {
                 digiaGuideController.cancel(request.payloadId);
@@ -632,9 +658,25 @@ function SpotlightOverlay({
     useEffect(() => {
         setLayout(null);
         if (!ready) return; // hold off measuring/showing until the delay has elapsed
+        if (!digiaAnchorRegistry.isRegistered(step.anchorKey)) {
+            // eslint-disable-next-line no-console
+            console.warn(`[Digia] campaign dropped — anchor_key "${step.anchorKey}" is not registered on this screen (campaign_key=${request.campaignKey}, step=${stepIndex})`);
+            digiaHealthReporter.report(HealthEventType.anchor_not_on_screen, {
+                campaign_key: request.campaignKey,
+                reason: 'anchor_key_not_registered',
+                anchor_key: step.anchorKey,
+                step_index: stepIndex,
+            });
+            digiaGuideController.cancel(request.payloadId);
+            return;
+        }
         let skipCached = false;
         const unsub = digiaAnchorRegistry.subscribe(step.anchorKey, (l) => {
             if (!skipCached) return;
+            if (l.width === 0 || l.height === 0) {
+                digiaGuideController.cancel(request.payloadId);
+                return;
+            }
             const { width: screenW, height: screenH } = Dimensions.get('window');
             if (l.pageY + l.height <= 0 || l.pageY >= screenH || l.pageX + l.width <= 0 || l.pageX >= screenW) {
                 digiaGuideController.cancel(request.payloadId);
@@ -811,9 +853,41 @@ function DigiaGuideRuntime() {
 }
 
 // ─── DigiaHost ────────────────────────────────────────────────────────────────
+//
+// Place once at the app root. Accepts optional children (wrap mode) or can be
+// used standalone (<DigiaHost />) as a sibling alongside other root elements.
+//
+// Renders two overlays, both non-interactive (pointerEvents="none"):
+//   1. JS guide / tooltip / spotlight renderer (DigiaGuideRuntime)
+//   2. Native Compose overlay for dialogs / bottom sheets (DigiaHostView)
+
+export function DigiaHost({ children }: { children?: React.ReactNode }) {
+    const overlay = (
+        <>
+            <DigiaGuideRuntime />
+            {NativeDigiaHostView && (
+                // The outer View with pointerEvents="none" is critical: RN's touch
+                // dispatch respects pointerEvents on plain Views even in bridgeless
+                // mode. Applying it directly on requireNativeComponent views is
+                // unreliable in New Architecture. The Compose dialogs/sheets inside
+                // render in their own Android PhoneWindow so they stay interactive.
+                <View style={StyleSheet.absoluteFillObject} pointerEvents="none">
+                    <NativeDigiaHostView style={StyleSheet.absoluteFillObject} />
+                </View>
+            )}
+        </>
+    );
+
+    if (children != null) {
+        return (
+            <>
+                {children}
+                {overlay}
+            </>
+        );
+    }
 
-export function DigiaHost() {
-    return <DigiaGuideRuntime />;
+    return overlay;
 }
 
 // ─── Styles ───────────────────────────────────────────────────────────────────

package/src/NativeDigiaEngage.ts

@@ -55,6 +55,22 @@ export interface Spec extends TurboModule {
 
     /** Return all registered components (anchors/slots) for health reporting. */
     getRegisteredComponents(): Promise<Array<{ component_key: string; component_type: 'anchor' | 'slot'; screen_name: string | null }>>;
+
+    /** Set the authenticated user ID for analytics identity stitching. */
+    setUserId(userId: string): void;
+    /** Clear the user ID (e.g. on logout); rotates the analytics session. */
+    clearUserId(): void;
+    /**
+     * Record an analytics event from a JS-rendered campaign (guide/tooltip/spotlight).
+     * Native campaigns (nudge, inline, survey) are tracked automatically by the SDK.
+     */
+    trackEvent(
+        eventType: string,
+        campaignId: string,
+        campaignKey: string,
+        campaignType: string,
+        elementId?: string | null,
+    ): void;
 }
 
 let _resolved: Spec | null = null;
@@ -89,5 +105,9 @@ export const nativeDigiaModule: Spec = {
     registerAnchor: (key, x, y, width, height) => getModule()?.registerAnchor(key, x, y, width, height),
     unregisterAnchor: (key) => getModule()?.unregisterAnchor(key),
     getRegisteredComponents: () => getModule()?.getRegisteredComponents() ?? Promise.resolve([]),
+    setUserId: (userId) => getModule()?.setUserId(userId),
+    clearUserId: () => getModule()?.clearUserId(),
+    trackEvent: (eventType, campaignId, campaignKey, campaignType, elementId) =>
+        getModule()?.trackEvent(eventType, campaignId, campaignKey, campaignType, elementId),
     getConstants: () => getModule()?.getConstants?.() ?? {},
 };

package/src/digiaAnchorRegistry.ts

@@ -38,5 +38,7 @@ const remeasure = (key: string) => {
     _measureCallbacks.get(key)?.()
 }
 
+const isRegistered = (key: string): boolean => _measureCallbacks.has(key)
+
 export type { AnchorLayout }
-export const digiaAnchorRegistry = { setLayout, getLayout, subscribe, remove, registerMeasure, unregisterMeasure, remeasure }
+export const digiaAnchorRegistry = { setLayout, getLayout, subscribe, remove, registerMeasure, unregisterMeasure, remeasure, isRegistered }

package/src/frequencyStore.ts

@@ -36,18 +36,18 @@ const _sessionStore = new Map<string, FrequencyState>();
 const storeKey = (campaignKey: string) => `digia:freq:${campaignKey}`;
 
 export const frequencyStore = {
-    async checkProjectId(projectId: string): Promise<void> {
+    async checkApiKey(apiKey: string): Promise<void> {
         const storage = getStorage();
         if (!storage) return;
         try {
             const stored = await storage.getItem(STORE_META_KEY);
-            const meta = stored ? (JSON.parse(stored) as { projectId: string }) : null;
-            if (meta && meta.projectId !== projectId) {
+            const meta = stored ? (JSON.parse(stored) as { apiKey: string }) : null;
+            if (meta && meta.apiKey !== apiKey) {
                 const keys = await storage.getAllKeys();
                 const digiaKeys = keys.filter((k) => k.startsWith('digia:freq:'));
                 if (digiaKeys.length > 0) await storage.multiRemove([...digiaKeys]);
             }
-            await storage.setItem(STORE_META_KEY, JSON.stringify({ projectId }));
+            await storage.setItem(STORE_META_KEY, JSON.stringify({ apiKey }));
         } catch {
             // non-fatal
         }

package/src/index.ts

@@ -4,18 +4,18 @@
  * React Native bridge for the Digia Engage SDK.
  *
  * The SDK surfaces Digia Compose UI inside React Native via:
- *   • `Digia`          – SDK lifecycle (initialize, setCurrentScreen)
- *   • `DigiaHostView`  – Transparent native overlay view that hosts Compose dialogs/
- *                        bottom-sheets managed by the Digia CEP engine.
+ *   • `Digia`      – SDK lifecycle (initialize, setCurrentScreen)
+ *   • `DigiaHost`  – Place once at the app root. Hosts JS guide/tooltip overlays
+ *                    and the native Compose overlay for dialogs/bottom-sheets.
+ *                    Use as <DigiaHost /> standalone or <DigiaHost>{children}</DigiaHost>.
  */
 
 export { Digia } from './Digia';
-export { DigiaHostView } from './DigiaHostView';
 export { DigiaHost } from './DigiaProvider';
 export { DigiaSlotView } from './DigiaSlotView';
 export { DigiaAnchorView } from './DigiaAnchorView';
 export type { DigiaAnchorViewRef } from './DigiaAnchorView';
-export type { ActionContext, ActionResult, CampaignType, DigiaAction, DigiaConfig, DigiaDelegate, DigiaExperienceEvent, DigiaPlugin, InAppBrowserAdapter, InAppPayload, OnAction } from './types';
+export type { ActionContext, ActionResult, CEPTriggerPayload, CampaignType, DigiaAction, DigiaConfig, DigiaDelegate, DigiaExperienceEvent, DigiaPlugin, InAppBrowserAdapter, OnAction } from './types';
 export { defaultInAppBrowser } from './defaultInAppBrowser';
 export { DigiaHealthReporter, HealthEventType, digiaHealthReporter } from './DigiaHealthReporter';
 export type {

package/src/templateTypes.ts

@@ -120,4 +120,34 @@ export type SurveyTemplateConfig = {
     rootNodeId: string
 }
 
-export type TemplateConfig = TooltipConfig | SpotlightConfig | CarouselConfig | SurveyTemplateConfig
+export type NudgeContainerConfig = {
+    bgColor?: string
+    cornerRadius?: number
+    padding?: number
+    dismissOnOutsideTap?: boolean
+    scrimColor?: string
+    /** Bottom-sheet only: max height as a fraction of screen height. */
+    maxHeightRatio?: number
+    /** Bottom-sheet only: show the drag handle + enable drag-to-dismiss. */
+    dragHandle?: boolean
+    /** Dialog only: width in dp. */
+    width?: number
+}
+
+/**
+ * BottomSheet / dialog nudge. `layout` is the native DUI VWData tree (root
+ * `digia/column`), parsed and rendered entirely by the native SDK — JS does not
+ * render nudges; they are forwarded to the native bridge via triggerCampaign.
+ */
+export type NudgeConfig = {
+    templateType: 'bottomSheet' | 'dialog'
+    container: NudgeContainerConfig
+    layout: Record<string, unknown>
+}
+
+export type TemplateConfig =
+    | TooltipConfig
+    | SpotlightConfig
+    | CarouselConfig
+    | SurveyTemplateConfig
+    | NudgeConfig

package/src/types.ts

@@ -1,15 +1,19 @@
 /**
- * Payload delivered to the Digia rendering engine for a CEP campaign.
+ * The translation contract between a CEP plugin and Digia's rendering engine.
  *
- * Mirrors InAppPayload on Android / Flutter.
+ * Plugin authors map their CEP's native callback into this struct.
+ * Mirrors CEPTriggerPayload on Android / Flutter — Digia core never imports
+ * CleverTap, MoEngage, or WebEngage types directly.
  */
-export interface InAppPayload {
-    /** Unique campaign ID from the CEP platform. */
-    id: string;
-    /** Marketer-authored content map (JSON-serialisable). */
-    content: Record<string, unknown>;
-    /** CEP-platform metadata, e.g. { campaignId, campaignName }. */
-    cepContext: Record<string, unknown>;
+export interface CEPTriggerPayload {
+    /** The CEP's own identifier for this campaign instance. Opaque to Digia — passed through for analytics correlation. */
+    cepCampaignId: string;
+    /** Additional metadata the CEP passes through (UTM params, user segment, CEP-specific tracking fields). Forwarded as-is in ExperienceEvents. */
+    cepMetadata: Record<string, unknown>;
+    /** The coupling key linking this CEP campaign to a Digia campaign. Used to look up the matching campaign in the store. */
+    campaignKey: string;
+    /** Optional runtime variables to interpolate into the campaign config. Keys must match variable placeholders in the Digia dashboard. */
+    variables?: Record<string, string>;
 }
 
 export type CampaignType = 'nudge' | 'guide' | 'inline' | 'survey';
@@ -70,7 +74,7 @@ export type GuideLifecycleEvent =
  */
 export interface DigiaDelegate {
     /** Deliver a campaign payload into the Digia rendering engine. */
-    onCampaignTriggered(payload: InAppPayload): void | Promise<void>;
+    onCampaignTriggered(payload: CEPTriggerPayload): void | Promise<void>;
     /** Invalidate / dismiss a campaign by its ID. */
     onCampaignInvalidated(campaignId: string): void;
 }
@@ -90,7 +94,7 @@ export interface DigiaPlugin {
      * (impressed / clicked / dismissed). Plugins use this to report
      * analytics back to their CEP platform.
      */
-    notifyEvent(event: DigiaExperienceEvent, payload: InAppPayload): void;
+    notifyEvent(event: DigiaExperienceEvent, payload: CEPTriggerPayload): void;
     /**
      * Called by the Digia SDK to record a named analytics event with properties.
      * Implement this to forward Digia lifecycle events (e.g. "Digia Experience Viewed")
@@ -170,8 +174,8 @@ export interface FrequencyEvalResult {
  * Configuration for initialising the Digia Engage SDK.
  */
 export interface DigiaConfig {
-    /** The Engage project ID — sent as x-digia-project-id on all SDK requests. */
-    projectId: string;
+    /** The Engage API key — sent as x-digia-project-id on all SDK requests. */
+    apiKey: string;
     /**
      * Base URL for the Digia API.
      * Defaults to the production API root, or the Engage sandbox root when