@dashx/react-native 1.1.3 → 1.1.5

package/.cursor/plans/deep_linking_implementation_plan_303c2ca9.plan.md

@@ -0,0 +1,216 @@
+---
+name: Deep Linking Implementation Plan
+overview: Implement MoEngage-like deep linking features in dashx-ios and dashx-android SDKs, covering notification-driven deep links, universal/app links, rich landing pages, structured navigation actions, and host-app callbacks.
+todos:
+  - id: phase-1-payload
+    content: "Phase 1: Extend payload models on both platforms (ActionButton URLs, screenName, screenData, NavigationAction type)"
+    status: pending
+  - id: phase-2-callbacks
+    content: "Phase 2: Notification click callback API -- DashXAppDelegate override (iOS) and DashXNotificationListener interface (Android)"
+    status: pending
+  - id: phase-3-action-buttons
+    content: "Phase 3: Per-action-button deep links on iOS (UNNotificationAction) and Android (NotificationCompat.Action)"
+    status: pending
+  - id: phase-4-rich-landing
+    content: "Phase 4: Rich Landing -- SFSafariViewController (iOS) and Chrome Custom Tabs (Android)"
+    status: completed
+  - id: phase-5-scene-delegate
+    content: "Phase 5: SceneDelegate deep link support -- openURLContexts and continue userActivity (iOS only)"
+    status: completed
+  - id: phase-6-analytics
+    content: "Phase 6: Deep link source tracking -- processURL / processDeepLink analytics events"
+    status: completed
+  - id: phase-7-docs
+    content: "Phase 7: Documentation and demo app updates for all deep linking features"
+    status: completed
+isProject: false
+---
+
+# Deep Linking Implementation Plan
+
+## Current State vs MoEngage: Feature Comparison
+
+### What We Have Today
+
+**dashx-ios** ([DashXAppDelegate.swift](dashx-ios/Sources/DashXFirebase/DashXAppDelegate.swift), [DashXClient.swift](dashx-ios/Sources/DashX/DashXClient.swift), [DashXData.swift](dashx-ios/Sources/DashX/DashXData.swift)):
+- Notification `url` field in `DashXNotificationData` -- opens via `handleLink(url:)` callback
+- Universal link forwarding via `DashXClient.handleUserActivity()` + `linkHandler` closure (AppDelegate only)
+- `notificationClicked(message:, actionIdentifier:)` open method for subclass overrides
+- `notificationDeliveredInForeground(message:)` callback
+- Message tracking: delivered / clicked / dismissed
+- `DashXSceneDelegate` exists but only handles ad tracking -- no deep link or URL handling
+
+**dashx-android** ([NotificationProcessor.kt](dashx-android/dashx/src/main/java/com/dashx/sdk/NotificationProcessor.kt), [DashXFirebaseMessagingService.kt](dashx-android/dashx/src/main/java/com/dashx/sdk/DashXFirebaseMessagingService.kt)):
+- Notification `url` field in `DashXPayload` -- opens via system `ACTION_VIEW` intent
+- `click_action` field -- resolves as Activity class name or Intent action string
+- `NotificationReceiver` (translucent Activity) delegates to `NotificationProcessor.handleClick()`
+- Message tracking: DELIVERED / OPENED / DISMISSED
+- No callback mechanism for the host app to intercept deep link navigation
+
+### What MoEngage Has That We Don't
+
+| Feature | MoEngage | DashX iOS | DashX Android |
+|---------|----------|-----------|---------------|
+| Custom URL scheme handling | Auto via swizzle or `processURL()` | Not handled | N/A (system intent) |
+| SceneDelegate deep link support | `scene(_:openURLContexts:)` + `scene(_:continue:)` | Missing | N/A |
+| Rich Landing (in-app browser) | SFSafariViewController / Chrome Custom Tabs | Missing | Missing |
+| Navigate to Screen (structured) | `screenName` + `screenData` in payload | Missing | Missing |
+| Per-action-button deep links | Each button has its own URL/action | Buttons have no URL | No action buttons at all |
+| Notification click callback with control | `onNotificationClicked()` returns bool to control redirection | Partial (subclass override, no control flag) | Missing entirely |
+| Notification received callback | `onNotificationReceived()` | Partial (foreground only) | Missing |
+| Notification cleared callback | `onNotificationCleared()` | Has `dismissed` tracking | Has `DISMISSED` tracking |
+| Deep link URL tracking/analytics | `processURL()` tracks source attribution | Missing | Missing |
+| Customizable notification builder | `customizeNotification()` / `customizeNotificationBuilder()` | Not exposed | Not exposed |
+| Self-handled notification | `onSelfHandledNotificationReceived()` | N/A | Missing |
+| AppDelegate proxy/swizzling | Auto-intercepts deep link AppDelegate methods | Not implemented | N/A |
+
+---
+
+## Implementation Plan
+
+### Phase 1: Enhanced Payload Models (Both Platforms)
+
+Extend the notification payload models to support structured navigation.
+
+**iOS** -- Update `ActionButton` and `DashXNotificationData` in [DashXData.swift](dashx-ios/Sources/DashX/DashXData.swift):
+- Add `url: String?` and `clickAction: String?` to `ActionButton`
+- Add `screenName: String?` and `screenData: [String: String]?` to `DashXNotificationData`
+- Add `clickAction: String?` (currently iOS has no `click_action` at all)
+
+**Android** -- Update `DashXPayload` in [DashXFirebaseMessagingService.kt](dashx-android/dashx/src/main/java/com/dashx/sdk/DashXFirebaseMessagingService.kt):
+- Add `screenName: String?` (`screen_name`) and `screenData: Map<String, String>?` (`screen_data`) to `DashXPayload`
+- Create an `ActionButton` model (currently Android has no action button support)
+- Add `actionButtons: List<ActionButton>?` (`action_buttons`) to `DashXPayload`
+
+Create a shared `NavigationAction` model on both platforms:
+
+```kotlin
+// Android
+sealed class NavigationAction {
+    data class DeepLink(val url: String) : NavigationAction()
+    data class Screen(val name: String, val data: Map<String, String>?) : NavigationAction()
+    data class RichLanding(val url: String) : NavigationAction()
+}
+```
+
+```swift
+// iOS
+public enum NavigationAction {
+    case deepLink(url: URL)
+    case screen(name: String, data: [String: String]?)
+    case richLanding(url: URL)
+}
+```
+
+### Phase 2: Notification Click Callback API (Both Platforms)
+
+Provide a callback mechanism that gives the host app full control over deep link handling.
+
+**iOS** -- In [DashXAppDelegate.swift](dashx-ios/Sources/DashXFirebase/DashXAppDelegate.swift):
+- Add `open func onNotificationClicked(message:, action: NavigationAction?, actionIdentifier: String) -> Bool` -- return `true` to suppress SDK default handling
+- Refactor `userNotificationCenter(_:didReceive:)` to resolve `NavigationAction` from the payload, call the callback, and only proceed with default handling if it returns `false`
+- Deprecate the existing `notificationClicked(message:actionIdentifier:)` (keep for backward compat)
+
+**Android** -- Create a new `DashXNotificationListener` interface in a new file `DashXNotificationListener.kt`:
+```kotlin
+interface DashXNotificationListener {
+    fun onNotificationReceived(payload: DashXPayload) {}
+    fun onNotificationClicked(payload: DashXPayload, action: NavigationAction?): Boolean = false
+    fun onNotificationDismissed(payload: DashXPayload) {}
+}
+```
+- Add `DashX.registerNotificationListener(listener)` and `DashX.unregisterNotificationListener()`
+- Wire into `NotificationProcessor.handleClick()` and `DashXFirebaseMessagingService.onMessageReceived()`
+- If `onNotificationClicked` returns `true`, skip the SDK's default URL/click_action handling
+
+### Phase 3: Action Button Deep Links
+
+**iOS** -- In [DashXAppDelegate.swift](dashx-ios/Sources/DashXFirebase/DashXAppDelegate.swift):
+- When building `UNNotificationAction` items from `actionButtons`, store the per-button URL/action in `userInfo` (via `UNNotificationCategory`)
+- In `didReceive response`, match `response.actionIdentifier` to the button's identifier and resolve its `NavigationAction`
+
+**Android**:
+- Parse `action_buttons` from `DashXPayload` and build `NotificationCompat.Action` items
+- Attach per-button `PendingIntent` with the button's URL or action
+- Handle button clicks in `NotificationProcessor` by resolving the specific button's `NavigationAction`
+
+### Phase 4: Rich Landing (In-App Browser)
+
+When a notification's action is `richLanding` (or a URL is explicitly marked for in-app display):
+
+**iOS**:
+- Add a helper in `DashXClient` or a new `DashXBrowser.swift` that presents `SFSafariViewController` for a given URL
+- Wire it as the default handler when `NavigationAction.richLanding` is resolved and the callback doesn't suppress it
+
+**Android**:
+- Add `implementation 'androidx.browser:browser:1.x.x'` as a dependency
+- Create `DashXBrowser.kt` that opens `CustomTabsIntent` for the URL
+- Wire as default handler for `NavigationAction.RichLanding`
+
+### Phase 5: SceneDelegate Deep Link Support (iOS Only)
+
+Update [DashXSceneDelegate.swift](dashx-ios/Sources/DashX/DashXSceneDelegate.swift) to handle both custom URL schemes and universal links:
+
+```swift
+@available(iOS 13.0, *)
+open func scene(_ scene: UIScene, openURLContexts URLContexts: Set<UIOpenURLContext>) {
+    guard let url = URLContexts.first?.url else { return }
+    DashXClient.instance.linkHandler?(url)
+}
+
+@available(iOS 13.0, *)
+open func scene(_ scene: UIScene, continue userActivity: NSUserActivity) {
+    DashXClient.instance.handleUserActivity(userActivity: userActivity)
+}
+```
+
+### Phase 6: Deep Link Source Tracking / Analytics
+
+Add a `trackDeepLink(url:, source:)` method on both platforms to record deep link opens as analytics events.
+
+**iOS** -- In [DashXClient.swift](dashx-ios/Sources/DashX/DashXClient.swift):
+- Add `public func processURL(_ url: URL, source: String? = nil)` that:
+  1. Fires a `dx_deep_link_opened` event with URL, source, timestamp
+  2. Invokes `linkHandler?(url)`
+- Update `handleUserActivity` and the notification click path to go through `processURL`
+
+**Android** -- In `DashX.kt`:
+- Add `fun processDeepLink(uri: Uri, source: String? = null)` with equivalent behavior
+- Update `NotificationProcessor.handleClick()` to call `processDeepLink` before opening the URL
+
+### Phase 7: Documentation and Demo App Updates
+
+- Update [dashx-ios/README.md](dashx-ios/README.md) and [dashx-android/README.md](dashx-android/README.md) with deep linking integration guides
+- Update [dashx-demo-rn](dashx-demo-rn/), [dashx-demo-ios](dashx-demo-ios/), and [dashx-demo-android](dashx-demo-android/) to demonstrate:
+  - Handling deep links from push notifications
+  - Custom URL scheme setup
+  - Universal Links / App Links configuration
+  - Rich landing page behavior
+  - Navigate-to-screen with custom data
+
+---
+
+## Architecture: Notification Click Flow (After Implementation)
+
+```mermaid
+flowchart TD
+    NotifTap[User Taps Notification] --> ParsePayload[Parse DashX Payload]
+    ParsePayload --> ResolveAction[Resolve NavigationAction]
+    ResolveAction --> TrackClick[trackMessage: CLICKED/OPENED]
+    TrackClick --> CallbackCheck{Host App Callback}
+    CallbackCheck -->|returns true| Done[Host App Handles]
+    CallbackCheck -->|returns false| ActionType{Action Type?}
+    ActionType -->|DeepLink| OpenURL[Open URL via system / linkHandler]
+    ActionType -->|RichLanding| InAppBrowser[SFSafari / CustomTabs]
+    ActionType -->|Screen| ScreenNav[Invoke screenHandler callback]
+    ActionType -->|None| FallbackClick[Call legacy notificationClicked]
+```
+
+---
+
+## Key Design Decisions
+
+- **Callback-first, not swizzle**: Unlike MoEngage's AppDelegate proxy approach, we keep our subclass/callback pattern. Swizzling is fragile and conflicts with other SDKs. The host app subclasses `DashXAppDelegate`/`DashXSceneDelegate` (iOS) or registers a `DashXNotificationListener` (Android).
+- **NavigationAction as a first-class type**: Rather than passing raw strings, provide a sealed/enum type so host apps can pattern-match on the navigation intent.
+- **Backward compatible**: The existing `handleLink(url:)`, `notificationClicked(message:actionIdentifier:)` (iOS), and `click_action`/`url` behavior (Android) continue to work. New APIs are additive.
+- **Rich landing is opt-in**: URLs default to system handling (external browser / `ACTION_VIEW`). Rich landing requires explicit `rich_landing` flag in the payload or a configuration option.

package/.gitignore

@@ -42,5 +42,5 @@ buck-out/
 \.buckd/
 *.keystore
 
-# VS Code
-.vscode/
+# Cursor plans
+.cursor

package/DashXReactNative.podspec

@@ -42,8 +42,8 @@ Pod::Spec.new do |s|
 
   s.dependency "React-RCTAppDelegate"
   # DashX iOS SDK — consumers must provide the source in their Podfile:
-  #   pod 'DashX', :git => 'https://github.com/dashxhq/dashx-ios.git', :tag => '1.1.4'
+  #   pod 'DashX', :git => 'https://github.com/dashxhq/dashx-ios.git', :tag => '1.1.9'
   # For local development:
   #   pod 'DashX', :path => '../dashx-ios'
-  s.dependency "DashX", "~> 1.1.4"
+  s.dependency "DashX", "~> 1.1.9"
 end