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

package/README.md

@@ -6,11 +6,7 @@ React Native SDK for **Digia Engage** – renders native Android (Jetpack Compos
 > | Platform | Status |
 > |---|---|
 > | Android | ✅ Full support |
-> | iOS | ✅ Full support |
-
----
-
-## Installation
+> | iOS | ✅ Guide overlays (JS renderer); native bridge (surveys, inline) |
 
 ```sh
 npm install @digia-engage/core
@@ -30,7 +26,7 @@ Add the Digia Engage Android SDK to `android/app/build.gradle.kts`:
 
 ```kotlin
 dependencies {
-    implementation("tech.digia:engage:1.1.0")
+    implementation("tech.digia:engage:2.0.0-rc.1")
 }
 ```
 
@@ -38,57 +34,43 @@ dependencies {
 
 ## Usage
 
-### 1 – Initialise the SDK
+### 1 — Initialize the SDK
 
-Call `Digia.initialize()` once at app startup, before registering any CEP plugin:
+Call `Digia.initialize()` once, as early as possible (top of `App.tsx`):
 
 ```tsx
-import { useEffect } from 'react';
 import { Digia } from '@digia-engage/core';
 
-export function RootApp() {
-  useEffect(() => {
-    (async () => {
-      await Digia.initialize({ apiKey: 'YOUR_ACCESS_KEY' });
-      // Register your CEP plugin here (e.g. DigiaCleverTapPlugin)
-    })().catch(console.error);
-  }, []);
-
-  return <AppNavigator />;
-}
+await Digia.initialize({
+  projectId: 'digia_YOUR_PROJECT_ID',
+  environment: 'production', // or 'sandbox'
+  logLevel: 'error',
+});
 ```
 
-### 2 – Mount the overlay host
+### 2 — Mount `<DigiaHost />`
 
-Place `<DigiaHostView>` at the app root so nudge campaigns (bottom sheets, dialogs, tooltips, spotlights) render above all content:
+Place `<DigiaHost />` at the root of your component tree. It renders the JS-side guide/tooltip/spotlight overlays via a `Modal`.
 
 ```tsx
-import { StyleSheet, View } from 'react-native';
-import { DigiaHostView } from '@digia-engage/core';
-import { Stack } from 'expo-router';
+// app/_layout.tsx (Expo Router) or App.tsx
+import { DigiaHost } from '@digia-engage/core';
 
 export default function RootLayout() {
   return (
-    <View style={styles.root}>
-      <DigiaHostView style={StyleSheet.absoluteFill} />
+    <>
       <Stack />
-    </View>
+      <DigiaHost />
+    </>
   );
 }
-
-const styles = StyleSheet.create({
-  root: { flex: 1 },
-});
 ```
 
-### 3 – Track screen changes
-
-Wire `setCurrentScreen()` to your navigation library so the SDK can trigger screen-scoped campaigns:
+### 3 — Track screen changes
 
 ```tsx
 import { Digia } from '@digia-engage/core';
 
-// React Navigation example:
 <NavigationContainer
   onStateChange={() => {
     const route = navRef.getCurrentRoute();
@@ -97,17 +79,55 @@ import { Digia } from '@digia-engage/core';
 >
 ```
 
-### 4 – Add inline slots
+### 4 — Register anchors for guide campaigns
 
-Place `<DigiaSlotView>` wherever you want inline campaign content (banners, cards):
+Wrap any UI element you want a tooltip or spotlight to point at:
+
+```tsx
+import { DigiaAnchorView } from '@digia-engage/core';
+
+<DigiaAnchorView anchorKey="home_banner_btn">
+  <Button title="Banner" />
+</DigiaAnchorView>
+```
+
+### 5 — Add slots for inline campaigns
 
 ```tsx
 import { DigiaSlotView } from '@digia-engage/core';
 
-<DigiaSlotView
-  placementKey="home_hero_banner"
-  style={{ width: '100%', height: 180 }}
-/>
+// Auto-sizes to native content height
+<DigiaSlotView placementKey="home_banner" />
+```
+
+### 6 — Register a CEP plugin
+
+```tsx
+import { DigiaCleverTapPlugin, createCleverTapClient } from '@digia-engage/clevertap';
+import CleverTap from 'clevertap-react-native';
+
+Digia.register(new DigiaCleverTapPlugin({
+  cleverTap: createCleverTapClient(CleverTap),
+}));
+```
+
+### 7 — (Optional) Handle actions
+
+Override or observe every action the SDK fires:
+
+```tsx
+await Digia.initialize({
+  projectId: '...',
+  onAction: (action, context) => {
+    if (action.type === 'deep_link') {
+      // return true to suppress SDK default; false/void to let SDK handle it
+    }
+  },
+  linking: {
+    routeViaSystemLinking: true,
+    inAppBrowser: defaultInAppBrowser, // requires react-native-inappbrowser-reborn
+  },
+});
 ```
 
 ---
@@ -118,26 +138,36 @@ import { DigiaSlotView } from '@digia-engage/core';
 
 | Method | Signature | Description |
 |---|---|---|
-| `initialize` | `(config: DigiaConfig) => Promise<void>` | Initialise the SDK. Call once at app startup. |
-| `register` | `(plugin: DigiaPlugin) => void` | Register a CEP plugin (e.g. `DigiaCleverTapPlugin`). |
-| `unregister` | `(plugin: DigiaPlugin \| string) => void` | Unregister a plugin and call its `teardown()`. |
-| `setCurrentScreen` | `(name: string) => void` | Notify the SDK of the current screen name. |
+| `initialize` | `(config: DigiaConfig) => Promise<void>` | Initialize the SDK. Call once before anything else. |
+| `register` | `(plugin: DigiaPlugin) => void` | Register a CEP plugin (CleverTap, MoEngage, etc.). |
+| `unregister` | `(plugin: DigiaPlugin \| string) => void` | Remove a previously registered plugin. |
+| `setCurrentScreen` | `(name: string) => void` | Notify the SDK of the active screen. |
+| `registerAnchor` | `(key: string, screen?: string) => void` | Manually register an anchor key. |
+| `unregisterAnchor` | `(key: string) => void` | Remove an anchor registration. |
 
 ### `DigiaConfig`
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `apiKey` | `string` | — | **Required.** Your Digia project API key. |
+| `projectId` | `string` | — | **Required.** Your Digia project ID (format: `digia_…`). Sent as `x-digia-project-id` on all SDK requests. |
 | `environment` | `'production' \| 'sandbox'` | `'production'` | Target environment. |
 | `logLevel` | `'none' \| 'error' \| 'verbose'` | `'error'` | Log verbosity. |
+| `onAction` | `OnAction` | — | Override hook for all actions. Return `true` to suppress SDK default. |
+| `linking.routeViaSystemLinking` | `boolean` | `true` | Use `Linking.openURL` for URL actions. |
+| `linking.inAppBrowser` | `InAppBrowserAdapter` | — | Required for `open_url` with `presentation: 'in_app'`. |
+| `baseUrl` | `string` | — | Override the Digia API base URL. |
 
-### `<DigiaHostView>`
+### `<DigiaHost />`
 
-Transparent overlay that hosts Digia-rendered campaign UI (dialogs, bottom sheets, tooltips, spotlights) above app content. Mount once at the app root.
+No props. Renders the JS guide overlay runtime (`TooltipOverlay`, `SpotlightOverlay`).
+Place it once, anywhere in the root view — `Modal` handles z-ordering.
+
+### `<DigiaAnchorView>`
 
 | Prop | Type | Description |
 |---|---|---|
-| `style` | `ViewStyle?` | Style for the overlay view. Typically `StyleSheet.absoluteFill`. |
+| `anchorKey` | `string` | **Required.** Must match the step's `anchorKey` in the campaign config. |
+| `...ViewProps` | — | All standard React Native `View` props are forwarded. |
 
 ### `<DigiaSlotView>`
 
@@ -145,8 +175,61 @@ Renders inline campaign content (banners, cards) at a named placement. Collapses
 
 | Prop | Type | Description |
 |---|---|---|
-| `placementKey` | `string` | Must match the placement key in your CEP campaign. |
-| `style` | `ViewStyle?` | An explicit height is required — the slot is not visible without one. |
+| `placementKey` | `string` | **Required.** Must match the campaign's `slotKey`. |
+| `style` | `ViewStyle?` | Pass an explicit `height` to fix size; otherwise auto-sizes. |
+
+### `<DigiaHostView>`
+
+Low-level transparent native overlay view (Android/iOS). Use `<DigiaHost />` instead
+unless you need the native Compose/SwiftUI overlay host explicitly.
+
+---
+
+## Campaign types
+
+| Type | Trigger | JS or Native |
+|---|---|---|
+| `guide` (tooltip) | `DigiaGuideController` → `DigiaHost` | **JS** — `TooltipOverlay` via `Modal` |
+| `guide` (spotlight) | `DigiaGuideController` → `DigiaHost` | **JS** — `SpotlightOverlay` via `Modal` |
+| `inline` | `nativeDigiaModule.triggerCampaign()` | **Native** — Android Compose `VWCarousel` |
+| `survey` | `nativeDigiaModule.triggerCampaign()` | **Native** — Android Compose `SurveyRenderer` |
+| `nudge` | `nativeDigiaModule.triggerCampaign()` | **Native** — Android Compose dialog / bottom-sheet |
+
+---
+
+## Architecture
+
+```
+react-native/src/
+  index.ts                  Public API exports
+  Digia.ts                  SDK singleton — initialize, register, setCurrentScreen,
+                            campaign routing, campaign store (fetched from backend)
+  DigiaProvider.tsx         JS guide renderer — TooltipOverlay + SpotlightOverlay + DigiaHost
+  DigiaGuideController.ts   Event bus for guide start/cancel; queues if DigiaHost not mounted
+  digiaAnchorRegistry.ts    In-memory anchor position store with subscriber pattern
+  DigiaAnchorView.tsx       Wraps UI elements; measures position via ref.measure
+  DigiaSlotView.tsx         Native slot view wrapper; auto-sizes to content height
+  DigiaHostView.tsx         Low-level native overlay host (transparent, pointer-events none)
+  NativeDigiaEngage.ts      Codegen native module spec (TurboModule)
+  actionHandler.ts          Action execution — deep link, open URL, next/prev/dismiss;
+                            onAction override; cold-start queue
+  defaultInAppBrowser.ts    Lazily loads react-native-inappbrowser-reborn
+  templateTypes.ts          TypeScript types for TooltipConfig, SpotlightConfig,
+                            CarouselConfig, SurveyTemplateConfig
+  types.ts                  DigiaConfig, DigiaPlugin, DigiaDelegate, InAppPayload,
+                            DigiaAction, ActionContext, DigiaExperienceEvent
+
+react-native/android/       Android bridge
+  DigiaModule.kt            initialize, registerBridge, triggerCampaign, registerAnchor, …
+  DigiaSlotViewManager.kt   DigiaSlotView native view manager
+  DigiaAnchorViewManager.kt DigiaAnchorView native view manager
+  DigiaViewManager.kt       DigiaHostView native view manager
+
+react-native/ios/           iOS bridge
+  DigiaModule.swift         initialize, registerBridge, triggerCampaign, …
+  DigiaHostViewManager.swift
+  DigiaAnchorViewManager.swift
+```
 
 ---
 

package/android/build.gradle

@@ -2,13 +2,13 @@
  * Android Gradle build file for the @digia/engage-react-native library module.
  *
  * This module is a thin bridge layer that:
- *   • Depends on the Digia Engage Android AAR (digia-ui)
+ *   • Depends on the Digia Engage Android AAR
  *   • Depends on the React Native SDK
  *   • Exposes a ReactPackage (DigiaPackage) that registers the native module
  *     and native view to React Native's bridge
  *
  * The Compose runtime/tooling dependencies are inherited transitively from
- * the digia-ui AAR via `api` declarations; we only add what is needed for
+ * the Digia Engage AAR via `api` declarations; we only add what is needed for
  * the bridge code itself.
  */
 

package/android/src/main/java/com/digia/engage/rn/DigiaModule.kt

@@ -22,7 +22,6 @@
  */
 package com.digia.engage.rn
 
-import android.widget.FrameLayout
 import androidx.lifecycle.LifecycleOwner
 import androidx.lifecycle.ViewModelStoreOwner
 import androidx.lifecycle.setViewTreeLifecycleOwner
@@ -59,7 +58,14 @@ internal class DigiaModule(
     // ─── initialize ───────────────────────────────────────────────────────────
 
     @ReactMethod
-    fun initialize(apiKey: String, environment: String, logLevel: String, promise: Promise) {
+    fun initialize(
+            apiKey: String,
+            environment: String,
+            logLevel: String,
+            baseUrl: String?,
+            fontFamily: String?,
+            promise: Promise
+    ) {
         try {
             val config =
                     DigiaConfig(
@@ -75,10 +81,18 @@ internal class DigiaModule(
                                         "none" -> DigiaLogLevel.NONE
                                         else -> DigiaLogLevel.ERROR
                                     },
+                            baseUrl = baseUrl?.takeIf { it.isNotBlank() },
+                            fontFamily = fontFamily?.takeIf { it.isNotBlank() },
                     )
             Digia.initialize(reactContext.applicationContext, config)
 
             UiThreadUtil.runOnUiThread {
+                // Mount the Compose overlay ABOVE the ReactRootView via addContentView().
+                // This keeps it outside Fabric's shadow tree entirely so Fabric hit-testing
+                // never sees it. Touch pass-through is handled by DigiaHostView.dispatchTouchEvent
+                // returning false at the native Android level — which works correctly at this
+                // level of the hierarchy, unlike inside Fabric where pointerEvents="none" on
+                // non-ReactViewGroup views is not respected during shadow-tree hit-testing.
                 mountDigiaHost()
                 promise.resolve(null)
             }
@@ -138,13 +152,42 @@ internal class DigiaModule(
         rnPlugin.delegate?.onCampaignInvalidated(campaignId)
     }
 
+    // ─── Anchor registration ──────────────────────────────────────────────────
+
+    @ReactMethod
+    fun registerAnchor(key: String, x: Int, y: Int, width: Int, height: Int) {
+        Digia.registerAnchor(key, x, y, width, height)
+    }
+
+    @ReactMethod
+    fun unregisterAnchor(key: String) {
+        Digia.unregisterAnchor(key)
+    }
+
     // ─── Internal: mount the Compose overlay host ─────────────────────────────
 
     private fun mountDigiaHost() {
-        val activity = reactContext.currentActivity ?: return
+        val activity = reactContext.currentActivity ?: run {
+            android.util.Log.w("DigiaHost", "[mountDigiaHost] no current activity — skipping")
+            return
+        }
 
         val contentRoot = activity.window.decorView.findViewWithTag<DigiaHostView>(DIGIA_HOST_TAG)
-        if (contentRoot != null) return
+        if (contentRoot != null) {
+            android.util.Log.d("DigiaHost", "[mountDigiaHost] already mounted (tag found) — skipping")
+            return
+        }
+
+        android.util.Log.d("DigiaHost", "[mountDigiaHost] mounting native overlay on DecorView")
+
+        // Mount on the DecorView (not content area) so the overlay covers the full screen
+        // including status bar and navigation bar. This also ensures the Compose Popup's
+        // canvas y=0 aligns with the absolute screen y=0, matching getLocationOnScreen()
+        // coordinates used by DigiaAnchorView.
+        val decorView = activity.window.decorView as? android.view.ViewGroup ?: run {
+            android.util.Log.w("DigiaHost", "[mountDigiaHost] decorView not a ViewGroup — skipping")
+            return
+        }
 
         val composeView =
                 DigiaHostView(activity).apply {
@@ -155,13 +198,14 @@ internal class DigiaModule(
                             setViewTreeSavedStateRegistryOwner(activity)
                 }
 
-        activity.addContentView(
+        decorView.addView(
                 composeView,
-                FrameLayout.LayoutParams(
-                        FrameLayout.LayoutParams.MATCH_PARENT,
-                        FrameLayout.LayoutParams.MATCH_PARENT,
+                android.view.ViewGroup.LayoutParams(
+                        android.view.ViewGroup.LayoutParams.MATCH_PARENT,
+                        android.view.ViewGroup.LayoutParams.MATCH_PARENT,
                 ),
         )
+        android.util.Log.d("DigiaHost", "[mountDigiaHost] done — DecorView child count: ${decorView.childCount}")
     }
 
     companion object {

package/android/src/main/java/com/digia/engage/rn/DigiaSlotViewManager.kt

@@ -26,10 +26,14 @@ private class ContentSizeChangeEvent(
     surfaceId: Int,
     viewTag: Int,
     private val heightDp: Double,
+    private val widthDp: Double,
 ) : Event<ContentSizeChangeEvent>(surfaceId, viewTag) {
     override fun getEventName(): String = "onContentSizeChange"
     override fun getEventData(): WritableMap =
-        Arguments.createMap().apply { putDouble("height", heightDp) }
+        Arguments.createMap().apply {
+            putDouble("height", heightDp)
+            putDouble("width", widthDp)
+        }
 }
 
 // ── DigiaSlotContainerView ────────────────────────────────────────────────────
@@ -141,7 +145,7 @@ internal class DigiaSlotContainerView(context: Context) : FrameLayout(context) {
 
         val dispatcher = UIManagerHelper.getEventDispatcherForReactTag(ctx, id) ?: return
         val surfaceId = UIManagerHelper.getSurfaceId(this)
-        dispatcher.dispatchEvent(ContentSizeChangeEvent(surfaceId, id, heightDp.toDouble()))
+        dispatcher.dispatchEvent(ContentSizeChangeEvent(surfaceId, id, heightDp.toDouble(), 0.0))
     }
 
     companion object {

package/android/src/main/java/com/digia/engage/rn/DigiaViewManager.kt

@@ -54,6 +54,7 @@ internal class DigiaViewManager : SimpleViewManager<DigiaHostView>() {
                         FrameLayout.LayoutParams.MATCH_PARENT,
                 )
 
+        android.util.Log.d("DigiaHost", "[DigiaViewManager] RN-side NativeDigiaHostView instance created (id=${view.id})")
         return view
     }
 

package/ios/DigiaEngageModule.m

@@ -22,9 +22,11 @@
 
 @interface RCT_EXTERN_MODULE(DigiaEngageModule, RCTEventEmitter)
 
-RCT_EXTERN_METHOD(initialize:(NSString *)apiKey
+RCT_EXTERN_METHOD(initialize:(NSString *)projectId
                   environment:(NSString *)environment
                   logLevel:(NSString *)logLevel
+                  baseUrl:(NSString *)baseUrl
+                  fontFamily:(NSString *)fontFamily
                   resolve:(RCTPromiseResolveBlock)resolve
                   reject:(RCTPromiseRejectBlock)reject)
 
@@ -62,3 +64,7 @@ RCT_EXPORT_VIEW_PROPERTY(onContentSizeChange, RCTDirectEventBlock)
 @interface RCT_EXTERN_MODULE(DigiaAnchorView, RCTViewManager)
 RCT_EXPORT_VIEW_PROPERTY(anchorKey, NSString)
 @end
+
+@interface RCT_EXTERN_MODULE(DigiaAnchorView, RCTViewManager)
+RCT_EXPORT_VIEW_PROPERTY(anchorKey, NSString)
+@end

package/ios/DigiaHostViewManager.swift

@@ -48,30 +48,27 @@ final class DigiaHostUIView: UIView {
     }
 
     private func mountHostingController() {
-        guard let parentVC = parentViewController() else { return}
+        let parentVC = parentViewController()
 
         let swiftUIView = DigiaHostWrapperView()
         let hc = UIHostingController(rootView: swiftUIView)
         hc.view.translatesAutoresizingMaskIntoConstraints = false
         hc.view.backgroundColor = .clear
 
-        parentVC.addChild(hc)
-        // Mount onto parentVC.view (full-screen) rather than self, because
-        // DigiaHostView is intentionally sized 0×0 in React Native (it takes no
-        // screen space). A zero-size UIHostingController frame prevents SwiftUI
-        // from rendering its body, which means @ObservedObject subscriptions and
-        // .onChange(of:) modifiers are never established — so activePayload
-        // changes are silently dropped and no overlay is ever shown.
-        // Anchoring to parentVC.view guarantees a non-zero frame so SwiftUI's
-        // rendering loop runs and reacts to SDK state changes.
-        parentVC.view.addSubview(hc.view)
-        hc.didMove(toParent: parentVC)
+        if let parentVC { parentVC.addChild(hc) }
+        // Mount onto self rather than parentVC.view. DigiaHostView is given
+        // absoluteFillObject style from JS so self IS full-screen, and SwiftUI
+        // will render normally. Mounting here means hitTest below is the single
+        // control point for touch dispatch — parentVC.view never has a rogue
+        // full-screen sibling that intercepts all RN touches.
+        addSubview(hc.view)
+        if let parentVC { hc.didMove(toParent: parentVC) }
 
         NSLayoutConstraint.activate([
-            hc.view.leadingAnchor.constraint(equalTo: parentVC.view.leadingAnchor),
-            hc.view.trailingAnchor.constraint(equalTo: parentVC.view.trailingAnchor),
-            hc.view.topAnchor.constraint(equalTo: parentVC.view.topAnchor),
-            hc.view.bottomAnchor.constraint(equalTo: parentVC.view.bottomAnchor),
+            hc.view.leadingAnchor.constraint(equalTo: leadingAnchor),
+            hc.view.trailingAnchor.constraint(equalTo: trailingAnchor),
+            hc.view.topAnchor.constraint(equalTo: topAnchor),
+            hc.view.bottomAnchor.constraint(equalTo: bottomAnchor),
         ])
 
         hostingController = hc
@@ -79,11 +76,14 @@ final class DigiaHostUIView: UIView {
 
     // Pass touches through to RN when no overlay is active.
     // When an overlay renders in-host (bottom sheet / dialog inside DigiaHost's ZStack),
-    // SwiftUI's hit test returns the overlay view and we forward that — making the
-    // overlay fully interactive. When nothing is rendered (EmptyView), SwiftUI returns
-    // nil and we return nil, so UIKit falls through to RN content below.
+    // SwiftUI's hit test returns the overlay view — making the overlay interactive.
+    // When nothing is rendered, _UIHostingView.hitTest returns nil or itself; either
+    // way we return nil so UIKit falls through to RN content below.
     override func hitTest(_ point: CGPoint, with event: UIEvent?) -> UIView? {
-        return hostingController?.view.hitTest(point, with: event)
+        guard let hcView = hostingController?.view else { return nil }
+        let hit = hcView.hitTest(point, with: event)
+        if hit == nil || hit === hcView { return nil }
+        return hit
     }
 
     /// Prefer React Native’s `UIView.reactViewController`, then walk `next` from each view’s `.next`.

package/ios/DigiaModule.swift

@@ -4,7 +4,7 @@
  * React Native NativeModule that bridges the Digia Engage iOS SDK.
  *
  * Exposed methods (callable from JS via NativeModules.DigiaEngageModule):
- *   initialize(apiKey, environment, logLevel): Promise<void>
+ *   initialize(projectId, environment, logLevel): Promise<void>
  *   registerBridge(): void
  *   setCurrentScreen(name): void
  *   triggerCampaign(id, content, cepContext): void
@@ -61,9 +61,11 @@ final class DigiaModule: RCTEventEmitter {
 
     @objc
     func initialize(
-        _ apiKey: String,
+        _ projectId: String,
         environment: String,
         logLevel: String,
+        baseUrl: String?,
+        fontFamily: String?,
         resolve: @escaping RCTPromiseResolveBlock,
         reject: @escaping RCTPromiseRejectBlock
     ) {
@@ -76,9 +78,11 @@ final class DigiaModule: RCTEventEmitter {
         }
 
         let config = DigiaConfig(
-            apiKey: apiKey,
+            apiKey: projectId,
             logLevel: logLevelValue,
-            environment: envValue
+            environment: envValue,
+            developerConfig: baseUrl.flatMap { $0.isEmpty ? nil : DigiaDeveloperConfig(baseURL: $0) },
+            fontFamily: fontFamily.flatMap { $0.isEmpty ? nil : $0 }
         )
 
         Task { @MainActor in