@digia-engage/core 1.1.1 → 2.0.0-rc.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@digia-engage/core",
-  "version": "1.1.1",
+  "version": "2.0.0-rc.1",
   "description": "React Native bridge for Digia Engage – renders native Android Compose UI inside React Native apps",
   "main": "src/index.ts",
   "module": "src/index.ts",
@@ -44,8 +44,14 @@
   },
   "author": "Digia Technology Private Limited",
   "license": "MIT",
-  "peerDependencies": {},
+  "peerDependencies": {
+    "@floating-ui/core": "^1.0.0",
+    "react-native-reanimated": ">=3.0.0",
+    "react-native-svg": ">=13.0.0"
+  },
   "devDependencies": {
+    "@edwardloopez/react-native-coachmark": "^0.5.3",
+    "@floating-ui/core": "^1.7.5",
     "@react-native/eslint-config": "^0.73.0",
     "@types/react": "^18.2.0",
     "@types/react-native": "^0.73.0",
@@ -53,6 +59,8 @@
     "react": "18.2.0",
     "react-native": "0.73.0",
     "react-native-builder-bob": "^0.23.0",
+    "react-native-reanimated": "^3.19.3",
+    "react-native-svg": "^15.15.1",
     "typescript": "^5.2.0"
   },
   "react-native-builder-bob": {
@@ -77,4 +85,4 @@
       "javaPackageName": "com.digia.engage.rn"
     }
   }
-}
+}

package/src/Digia.ts

@@ -7,7 +7,7 @@
  * import { Digia } from '@digia/engage-react-native';
  *
  * // In your App entry point (e.g. App.tsx):
- * await Digia.initialize({ apiKey: 'YOUR_API_KEY' });
+ * await Digia.initialize({ projectId: 'YOUR_PROJECT_ID' });
  *
  * // Whenever your navigation screen changes:
  * Digia.setCurrentScreen('Home');
@@ -17,13 +17,31 @@
 
 import { DeviceEventEmitter } from 'react-native';
 import { nativeDigiaModule } from './NativeDigiaEngage';
+import { digiaHealthReporter, HealthEventType } from './DigiaHealthReporter';
+import { digiaGuideController } from './DigiaGuideController';
+import { digiaActionHandler } from './actionHandler';
 import type {
+    CampaignType,
     DigiaConfig,
     DigiaDelegate,
     DigiaExperienceEvent,
     DigiaPlugin,
+    GuideLifecycleEvent,
     InAppPayload,
 } from './types';
+import type { TemplateConfig } from './templateTypes';
+
+const PRODUCTION_API_ROOT = 'https://app.digia.tech';
+const SANDBOX_API_ROOT = 'https://dev.digia.tech';
+const DIGIA_SDK_VERSION = '1.0.0';
+
+interface SdkCampaign {
+    id?: string;
+    _id?: string;
+    campaign_key: string;
+    campaign_type: CampaignType;
+    templateConfig?: Record<string, unknown>;
+}
 
 class DigiaClass implements DigiaDelegate {
     private readonly _plugins = new Map<string, DigiaPlugin>();
@@ -34,6 +52,13 @@ class DigiaClass implements DigiaDelegate {
     // the full InAppPayload when overlay lifecycle events arrive from native.
     private readonly _activePayloads = new Map<string, InAppPayload>();
     private _engageSubscription: { remove(): void } | null = null;
+    private _projectId = '';
+    private _apiBaseUrl = '';
+    private _logLevel: DigiaConfig['logLevel'] = 'error';
+    private _fontFamily: string | undefined;
+    private _currentScreen: string | null = null;
+    private readonly _campaignsByKey = new Map<string, SdkCampaign>();
+    private readonly _registeredAnchorKeys = new Set<string>();
 
     /**
      * Initialise the Digia Engage SDK.
@@ -44,7 +69,27 @@ class DigiaClass implements DigiaDelegate {
     async initialize(config: DigiaConfig): Promise<void> {
         const environment = config.environment ?? 'production';
         const logLevel = config.logLevel ?? 'error';
-        await nativeDigiaModule.initialize(config.apiKey, environment, logLevel);
+        this._projectId = config.projectId;
+        this._apiBaseUrl = this._resolveApiBaseUrl(config);
+        this._logLevel = logLevel;
+        this._fontFamily = config.fontFamily?.trim() || undefined;
+        digiaHealthReporter.init(config.projectId, this._apiBaseUrl);
+
+        digiaActionHandler.configure({
+            onAction: config.onAction,
+            routeViaSystemLinking: config.linking?.routeViaSystemLinking ?? true,
+            inAppBrowser: config.linking?.inAppBrowser,
+        });
+
+        try {
+            await nativeDigiaModule.initialize(config.projectId, environment, logLevel, config.baseUrl, config.fontFamily);
+        } catch (e) {
+            // TODO: TO BE PICKED LATER @aditya-digia — health event reporting being removed
+            // digiaHealthReporter.report(HealthEventType.fetch_failed, { error_code: 0, platform: 'react_native' });
+            throw e;
+        }
+
+        await this._refreshCampaignStore();
     }
 
     /**
@@ -58,7 +103,7 @@ class DigiaClass implements DigiaDelegate {
      * ```ts
      * import { DigiaMoEngagePlugin } from '@digia/moengage-plugin';
      *
-     * await Digia.initialize({ apiKey: 'YOUR_KEY' });
+     * await Digia.initialize({ projectId: 'YOUR_PROJECT_ID' });
      * Digia.register(new DigiaMoEngagePlugin({ moEngage: MoEngage }));
      * ```
      */
@@ -74,6 +119,7 @@ class DigiaClass implements DigiaDelegate {
             this._nativeBridgeWired = true;
         }
         plugin.setup(this);
+        (plugin as any).reportHealth?.(digiaHealthReporter);
         this._plugins.set(plugin.identifier, plugin);
     }
 
@@ -95,22 +141,107 @@ class DigiaClass implements DigiaDelegate {
      * All registered plugins will have forwardScreen() called automatically.
      */
     setCurrentScreen(name: string): void {
+        this._currentScreen = name;
         nativeDigiaModule.setCurrentScreen(name);
         this._plugins.forEach((plugin) => plugin.forwardScreen(name));
     }
 
+    registerAnchor(anchorKey: string, _screenName?: string | null): void {
+        const cleanAnchorKey = anchorKey.trim();
+        if (!cleanAnchorKey) return;
+        this._registeredAnchorKeys.add(cleanAnchorKey);
+    }
+
+    unregisterAnchor(anchorKey: string): void {
+        this._registeredAnchorKeys.delete(anchorKey);
+    }
+
+    /**
+     * Global font family configured via {@link initialize}, or `undefined` when
+     * none was set. Used by the JS-rendered guide overlays (tooltip/spotlight)
+     * so their text matches native-rendered campaigns.
+     */
+    get fontFamily(): string | undefined {
+        return this._fontFamily;
+    }
+
 
     // ── DigiaDelegate ────────────────────────────────────────────────────────
     // Mirrors DigiaCEPDelegate on Android.
     // Forwards to the native DigiaCEPDelegate via the bridge.
 
     onCampaignTriggered(payload: InAppPayload): void {
+        if (!this._nativeBridgeWired) {
+            digiaHealthReporter.report(HealthEventType.plugin_not_registered, { campaign_key: payload.id });
+        }
+
+        const campaignKey = this._extractCampaignKey(payload);
+        this._log(`onCampaignTriggered payloadId=${payload.id} extractedKey=${campaignKey} knownKeys=[${[...this._campaignsByKey.keys()].join(', ')}]`);
+
+        if (campaignKey) {
+            const campaign = this._campaignsByKey.get(campaignKey);
+            if (campaign?.campaign_type === 'inline' || campaign?.campaign_type === 'survey') {
+                this._log(`${campaign.campaign_type} campaign triggered campaign_key=${campaignKey}, forwarding to native`);
+                this._activePayloads.set(payload.id, payload);
+                if (campaign.campaign_type === 'inline') {
+                    this._emitSlotWidth(campaign);
+                }
+                nativeDigiaModule.triggerCampaign(payload.id, payload.content, payload.cepContext);
+                return;
+            }
+
+            if (campaign?.campaign_type === 'guide') {
+                const config = this._parseTemplateConfig(campaign);
+                if (
+                    !config ||
+                    (config.templateType !== 'tooltip' && config.templateType !== 'spotlight') ||
+                    config.steps.length === 0
+                ) {
+                    digiaHealthReporter.report(HealthEventType.anchor_not_on_screen, {
+                        campaign_key: campaignKey,
+                        reason: 'guide_campaign_has_no_steps',
+                    });
+                    return;
+                }
+
+                this._activePayloads.set(payload.id, payload);
+                const digiaId = campaign._id ?? campaign.id ?? campaignKey;
+                const mounted = digiaGuideController.start({
+                    payloadId: payload.id,
+                    campaignKey,
+                    campaignId: digiaId,
+                    config,
+                    onExperienceEvent: (event) => this._onGuideLifecycleEvent(event, payload.id, campaignKey, digiaId),
+                });
+
+                this._log(`guide trigger campaign_key=${campaignKey} mounted=${mounted}`);
+                if (!mounted) {
+                    digiaHealthReporter.report(HealthEventType.host_not_mounted, {
+                        campaign_key: campaignKey,
+                        payload_id: payload.id,
+                    });
+                }
+                return;
+            }
+
+            if (!campaign) {
+                this._log(`campaign_key_mismatch: no campaign found for key="${campaignKey}"`);
+                digiaHealthReporter.report(HealthEventType.campaign_key_mismatch, {
+                    campaign_key: campaignKey,
+                    payload_id: payload.id,
+                    available_campaign_keys: [...this._campaignsByKey.keys()],
+                });
+                return;
+            }
+        }
+
         this._activePayloads.set(payload.id, payload);
         nativeDigiaModule.triggerCampaign(payload.id, payload.content, payload.cepContext);
     }
 
     onCampaignInvalidated(campaignId: string): void {
         this._activePayloads.delete(campaignId);
+        digiaGuideController.cancel(campaignId);
         nativeDigiaModule.invalidateCampaign(campaignId);
     }
 
@@ -158,6 +289,212 @@ class DigiaClass implements DigiaDelegate {
         this._plugins.forEach((plugin) => plugin.notifyEvent(event, payload));
     }
 
+    private _onGuideLifecycleEvent(
+        event: GuideLifecycleEvent,
+        payloadId: string,
+        campaignKey: string,
+        campaignId: string,
+    ): void {
+        const eventName = this._guideEventName(event.type);
+        const properties = this._buildGuideProperties(event, campaignId, campaignKey);
+        this._plugins.forEach((p) => p.track?.(eventName, properties));
+
+        // Notify plugins of CEP lifecycle termination (template cleanup) on exit events.
+        if (event.type === 'dismissed' || event.type === 'completed') {
+            const storedPayload = this._activePayloads.get(payloadId);
+            if (storedPayload) {
+                this._plugins.forEach((p) => p.notifyEvent({ type: 'dismissed' }, storedPayload));
+                this._activePayloads.delete(payloadId);
+            }
+        }
+    }
+
+    private _guideEventName(type: GuideLifecycleEvent['type']): string {
+        switch (type) {
+            case 'viewed': return 'Digia Experience Viewed';
+            case 'step_viewed': return 'Digia Step Viewed';
+            case 'clicked': return 'Digia Experience Clicked';
+            case 'step_clicked': return 'Digia Step Clicked';
+            case 'dismissed': return 'Digia Experience Dismissed';
+            case 'step_dismissed': return 'Digia Step Dismissed';
+            case 'completed': return 'Digia Experience Completed';
+        }
+    }
+
+    private _buildGuideProperties(
+        event: GuideLifecycleEvent,
+        campaignId: string,
+        campaignKey: string,
+    ): Record<string, unknown> {
+        const base: Record<string, unknown> = {
+            campaign_id: campaignId,
+            campaign_key: campaignKey,
+            campaign_type: 'guide',
+            display_style: event.displayStyle,
+            step_index: event.stepIndex + 1,
+            step_total: event.stepTotal,
+            anchor_key: event.anchorKey,
+            slot_key: null,
+            element_id: null,
+            cta_label: null,
+            action_type: null,
+            action_url: null,
+            dismiss_reason: null,
+            abandoned_at_step: null,
+            digia_sdk_version: DIGIA_SDK_VERSION,
+            digia_platform: 'react_native',
+        };
+
+        if (event.type === 'clicked' || event.type === 'step_clicked') {
+            base.element_id = event.elementId ?? null;
+            base.cta_label = event.ctaLabel;
+            base.action_type = event.actionType;
+            base.action_url = event.actionUrl ?? null;
+        } else if (event.type === 'dismissed' || event.type === 'step_dismissed') {
+            base.dismiss_reason = event.dismissReason;
+            base.abandoned_at_step = event.stepIndex + 1;
+        }
+
+        return base;
+    }
+
+    private _resolveApiBaseUrl(config: DigiaConfig): string {
+        const root = (config.baseUrl ??
+            (config.environment === 'sandbox' ? SANDBOX_API_ROOT : PRODUCTION_API_ROOT)).trim();
+        const cleanRoot = root.replace(/\/+$/, '');
+        return cleanRoot.endsWith('/api/v1') ? cleanRoot : `${cleanRoot}/api/v1`;
+    }
+
+    private async _refreshCampaignStore(): Promise<void> {
+        try {
+            this._log(`fetching campaigns from ${this._apiBaseUrl}/engage/sdk/getCampaigns`);
+            const campaigns = await this._sdkPost<SdkCampaign[]>('getCampaigns');
+            this._campaignsByKey.clear();
+            if (campaigns.length > 0) {
+                this._log(`campaign[0] raw keys: ${JSON.stringify(Object.keys(campaigns[0] as object))}`);
+            }
+            campaigns.forEach((campaign) => {
+                const raw = campaign as unknown as Record<string, unknown>;
+                const key = (typeof raw.campaign_key === 'string' && raw.campaign_key)
+                    || (typeof raw.campaignKey === 'string' && raw.campaignKey)
+                    || null;
+                const type = (typeof raw.campaign_type === 'string' && raw.campaign_type)
+                    || (typeof raw.campaignType === 'string' && raw.campaignType)
+                    || '';
+                if (key) {
+                    this._campaignsByKey.set(key, { ...campaign, campaign_key: key, campaign_type: type as SdkCampaign['campaign_type'] });
+                }
+            });
+            this._log(`loaded ${campaigns.length} campaign(s): [${[...this._campaignsByKey.keys()].join(', ')}]`);
+        } catch (e) {
+            const reason = e instanceof Error ? e.message : String(e);
+            this._log(`getCampaigns FAILED: ${reason}`);
+            digiaHealthReporter.report(HealthEventType.fetch_failed, {
+                error_code: 0,
+                platform: 'react_native',
+                reason,
+            });
+        }
+    }
+
+    private async _sdkPost<T>(path: string, body: Record<string, unknown> = {}): Promise<T> {
+        const res = await fetch(`${this._apiBaseUrl}/engage/sdk/${path}`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'x-digia-project-id': this._projectId,
+            },
+            body: JSON.stringify(body),
+        });
+
+        if (!res.ok) {
+            throw new Error(`${path} failed: HTTP ${res.status}`);
+        }
+
+        const json = await res.json();
+        return this._extractApiResponse<T>(json);
+    }
+
+    private _extractApiResponse<T>(json: unknown): T {
+        if (Array.isArray(json)) return json as T;
+        if (json && typeof json === 'object') {
+            const obj = json as Record<string, unknown>;
+            const data = obj.data;
+            if (data && typeof data === 'object' && 'response' in data) {
+                const value = (data as Record<string, unknown>).response;
+                if (value == null) throw new Error('SDK response.data.response is null');
+                return value as T;
+            }
+            if ('response' in obj) {
+                const value = obj.response;
+                if (value == null) throw new Error('SDK response.response is null');
+                return value as T;
+            }
+        }
+        throw new Error('SDK response missing data.response');
+    }
+
+    private _emitSlotWidth(campaign: SdkCampaign): void {
+        const raw = campaign as unknown as Record<string, unknown>;
+        const config = raw.templateConfig as Record<string, unknown> | undefined;
+        if (!config) {
+            this._log(`_emitSlotWidth: no templateConfig for campaign ${campaign.campaign_key}`);
+            return;
+        }
+        const slotKey = typeof config.slotKey === 'string' ? config.slotKey : null;
+        const width = typeof config.width === 'number' && config.width > 0 ? config.width : null;
+        this._log(`_emitSlotWidth slotKey=${slotKey} width=${width} campaign=${campaign.campaign_key}`);
+        if (slotKey) {
+            DeviceEventEmitter.emit('digiaSlotWidth', { slotKey, width });
+        } else {
+            this._log(`_emitSlotWidth: no slotKey in templateConfig ${JSON.stringify(config)}`);
+        }
+    }
+
+    private _extractCampaignKey(payload: InAppPayload): string | null {
+        const fromContent = this._extractString(payload.content, 'digiaKey', 'campaign_key', 'campaignKey');
+        if (fromContent) return fromContent;
+
+        const args = payload.content.args;
+        if (args && typeof args === 'object' && !Array.isArray(args)) {
+            const fromArgs = this._extractString(args as Record<string, unknown>, 'digiaKey', 'campaign_key', 'campaignKey');
+            if (fromArgs) return fromArgs;
+        }
+
+        if (this._campaignsByKey.has(payload.id)) return payload.id;
+        return null;
+    }
+
+    private _extractString(data: Record<string, unknown>, ...keys: string[]): string | null {
+        for (const key of keys) {
+            const value = data[key];
+            if (typeof value === 'string' && value.trim()) return value.trim();
+        }
+        return null;
+    }
+
+    private _parseTemplateConfig(campaign: SdkCampaign): TemplateConfig | null {
+        const c = campaign as unknown as Record<string, unknown>;
+        const raw = c.templateConfig as Record<string, unknown> | undefined;
+        if (!raw || typeof raw !== 'object') return null;
+        const type = raw.templateType;
+        if (type !== 'tooltip' && type !== 'spotlight' && type !== 'carousel') {
+            this._log(`unknown templateType="${type}" for campaign_key=${campaign.campaign_key}`);
+            return null;
+        }
+        if (type === 'carousel') {
+            return raw as TemplateConfig;
+        }
+        const steps = Array.isArray(raw.steps) ? raw.steps : [];
+        return { ...raw, templateType: type, steps } as TemplateConfig;
+    }
+
+    private _log(message: string): void {
+        if (this._logLevel !== 'verbose') return;
+        // eslint-disable-next-line no-console
+        console.log(`[Digia] ${message}`);
+    }
+
 }
 
 export const Digia = new DigiaClass();

package/src/DigiaGuideController.ts

@@ -0,0 +1,61 @@
+import type { GuideLifecycleEvent } from './types';
+import type { TemplateConfig } from './templateTypes';
+
+export interface DigiaGuideRequest {
+    payloadId: string;
+    campaignKey: string;
+    /** Digia backend UUID for this campaign (from the campaign store _id field). */
+    campaignId: string;
+    config: TemplateConfig;
+    onExperienceEvent: (event: GuideLifecycleEvent) => void;
+}
+
+type DigiaGuideControllerEvent =
+    | { type: 'start'; request: DigiaGuideRequest }
+    | { type: 'cancel'; payloadId: string };
+
+type DigiaGuideListener = (event: DigiaGuideControllerEvent) => void;
+
+class DigiaGuideController {
+    private _listener: DigiaGuideListener | null = null;
+    private _queue: DigiaGuideRequest[] = [];
+    private _activeRequest: DigiaGuideRequest | null = null;
+
+    subscribe(listener: DigiaGuideListener): () => void {
+        this._listener = listener;
+        if (this._queue.length > 0) {
+            const request = this._queue.shift()!;
+            this._activeRequest = request;
+            listener({ type: 'start', request });
+        }
+        return () => { if (this._listener === listener) this._listener = null; };
+    }
+
+    start(request: DigiaGuideRequest): boolean {
+        if (!this._listener) {
+            this._queue.push(request);
+            return false;
+        }
+        this._activeRequest = request;
+        this._listener({ type: 'start', request });
+        return true;
+    }
+
+    cancel(payloadId: string): void {
+        this._queue = this._queue.filter(r => r.payloadId !== payloadId);
+        if (this._activeRequest?.payloadId === payloadId) {
+            this._listener?.({ type: 'cancel', payloadId });
+            this._activeRequest = null;
+            this._dispatchNext();
+        }
+    }
+
+    private _dispatchNext(): void {
+        if (this._queue.length === 0 || !this._listener) return;
+        const request = this._queue.shift()!;
+        this._activeRequest = request;
+        this._listener({ type: 'start', request });
+    }
+}
+
+export const digiaGuideController = new DigiaGuideController();

package/src/DigiaHealthReporter.ts

@@ -0,0 +1,43 @@
+export const HealthEventType = {
+  campaign_key_mismatch: 'campaign_key_mismatch',
+  component_orphaned: 'component_orphaned',
+  anchor_not_on_screen: 'anchor_not_on_screen',
+  host_not_mounted: 'host_not_mounted',
+  plugin_not_registered: 'plugin_not_registered',
+  fetch_failed: 'fetch_failed',
+  action_handler_threw: 'action_handler_threw',
+  action_handler_timeout: 'action_handler_timeout',
+  deep_link_no_handler: 'deep_link_no_handler',
+  invalid_action_url: 'invalid_action_url',
+  inapp_browser_unavailable: 'inapp_browser_unavailable',
+  invalid_action_context: 'invalid_action_context',
+  cold_start_queue_overflow: 'cold_start_queue_overflow',
+} as const;
+
+export type HealthEventType = (typeof HealthEventType)[keyof typeof HealthEventType];
+
+export class DigiaHealthReporter {
+    private _projectId = '';
+    private _baseUrl = '';
+
+    init(projectId: string, baseUrl: string): void {
+        this._projectId = projectId;
+        this._baseUrl = baseUrl;
+    }
+
+    report(eventType: HealthEventType, detail: Record<string, unknown>): void {
+        if (!this._projectId) return;
+        // TODO: TO BE PICKED LATER @aditya-digia — health event backend endpoint being removed
+        // fetch(`${this._baseUrl}/engage/sdk/recordHealthEvent`, {
+        //     method: 'POST',
+        //     headers: {
+        //         'Content-Type': 'application/json',
+        //         'x-digia-project-id': this._projectId,
+        //     },
+        //     body: JSON.stringify({ event_type: eventType, detail }),
+        // }).catch(() => { /* swallow */ });
+        if (__DEV__) console.log('[DigiaHealth]', eventType, detail);
+    }
+}
+
+export const digiaHealthReporter = new DigiaHealthReporter();