@dashx/react-native 1.1.4 → 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.5'
+  #   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.5"
+  s.dependency "DashX", "~> 1.1.9"
 end

package/README.md

@@ -20,23 +20,16 @@
 
 [![npm version](https://img.shields.io/npm/v/@dashx/react-native.svg)](https://www.npmjs.com/package/@dashx/react-native)
 [![license](https://img.shields.io/npm/l/@dashx/react-native.svg)](https://github.com/dashxhq/dashx-react-native/blob/main/LICENSE)
-[![platforms](https://img.shields.io/badge/platforms-Android%20%7C%20iOS-brightgreen.svg)](#requirements)
+[![platforms](https://img.shields.io/badge/platforms-Android%20%7C%20iOS-brightgreen.svg)](#install)
 
 _DashX SDK for React Native_
 
-## Requirements
+## Install
 
-| Platform | Minimum Version |
-|----------|----------------|
-| iOS | 13.0+ |
-| Android | SDK 26 (Android 8.0)+ |
-| React Native | 0.71+ |
-| Node.js | 16.0+ |
+Requires **React Native 0.71+**, **iOS 13.0+**, **Android SDK 26+**, and **Node.js 16+**.
 
 > **Note:** This SDK uses native modules and is **not compatible with Expo Go**. Use a [development build](https://docs.expo.dev/develop/development-builds/introduction/) if you are using Expo.
 
-## Install
-
 ```sh
 npm install @dashx/react-native
 ```
@@ -47,480 +40,17 @@ or
 yarn add @dashx/react-native
 ```
 
-### Setup for Android
-
-DashX requires Google Services for Firebase Cloud Messaging:
-
-1. Add the `google-services` plugin in your `/android/build.gradle`:
-
-```gradle
-buildscript {
-  dependencies {
-    // ... other dependencies
-    classpath 'com.google.gms:google-services:4.4.2'
-  }
-}
-```
-
-2. Apply the plugin in your `/android/app/build.gradle`:
-
-```gradle
-apply plugin: 'com.google.gms.google-services'
-```
-
-3. Add your Android app on [Firebase Console](https://console.firebase.google.com/): **Project Overview > Add App > Android**
-
-4. Download `google-services.json` and place it at `/android/app/google-services.json`
-
-### Setup for iOS
-
-#### Step 1: Add pods to your Podfile
-
-The DashX iOS SDK is not published to CocoaPods trunk. Add it directly from GitHub along with the Firebase pods required for FCM push notifications.
-
-Add `use_modular_headers!` at the top of your `ios/Podfile`, then add the pods inside the target block:
-
-```ruby
-use_modular_headers!
-
-target 'YourApp' do
-  # ... other pods
-
-  pod 'DashX', :git => 'https://github.com/dashxhq/dashx-ios.git', :tag => '1.1.4'
-  pod 'FirebaseCore'
-  pod 'FirebaseMessaging'
-
-  use_react_native!(...)
-end
-```
-
-Then run:
-
-```sh
-cd ios && pod install
-```
-
-#### Step 2: Add GoogleService-Info.plist
-
-1. Add your iOS app on [Firebase Console](https://console.firebase.google.com/): **Project Overview > Add App > iOS**
-2. Download `GoogleService-Info.plist` and add it to your Xcode project (right-click project root > **Add Files to "YourApp"**, ensure **Copy items if needed** is checked)
-
-#### Step 3: Enable Push Notifications capability
-
-In Xcode, select your app target > **Signing & Capabilities** > **+ Capability** > add **Push Notifications**.
-
-#### Step 4: Configure your AppDelegate
-
-The SDK ships `DashXRCTAppDelegate` which handles permission requests, notification display, and universal link forwarding. Subclass it in your `AppDelegate.swift` and configure Firebase directly:
-
-```swift
-import DashXReactNative
-import ReactAppDependencyProvider
-import FirebaseCore
-import FirebaseMessaging
-import DashX
-import UserNotifications
-
-@main
-class AppDelegate: DashXRCTAppDelegate {
-  override var moduleName: String { "YourAppName" }
-
-  override func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
-    self.dependencyProvider = RCTAppDependencyProvider()
-    FirebaseApp.configure()
-    Messaging.messaging().delegate = self
-    return super.application(application, didFinishLaunchingWithOptions: launchOptions)
-  }
-
-  // Forward the APNS token to Firebase so it can exchange it for an FCM token
-  override func application(_ application: UIApplication, didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
-    Messaging.messaging().setAPNSToken(deviceToken, type: .unknown)
-  }
-
-  override func bundleURL() -> URL? {
-    #if DEBUG
-    RCTBundleURLProvider.sharedSettings().jsBundleURL(forBundleRoot: "index")
-    #else
-    Bundle.main.url(forResource: "main", withExtension: "jsbundle")
-    #endif
-  }
-}
-
-// Receive the FCM token and pass it to DashX
-extension AppDelegate: MessagingDelegate {
-  func messaging(_ messaging: Messaging, didReceiveRegistrationToken fcmToken: String?) {
-    guard let token = fcmToken else { return }
-    DashX.setFCMToken(to: token)
-  }
-}
-```
-
-`DashXRCTAppDelegate` handles the rest automatically:
-- Requests notification permission on launch
-- Displays notifications (banner + sound by default, even while app is in the foreground)
-- Tracks delivery, clicks, and dismissals
-- Forwards universal links to the JS `onLinkReceived` listener
-
-**Override points** (all optional):
-
-```swift
-/// Control foreground notification presentation (default: [.banner, .sound])
-override func notificationDeliveredInForeground(message: [AnyHashable: Any]) -> UNNotificationPresentationOptions {
-  return [.banner, .sound, .badge]
-}
-
-// Called when the user taps a notification or one of its action buttons
-override func notificationClicked(message: [AnyHashable: Any], actionIdentifier: String) {
-  // custom tap handling
-}
-
-// Called when a universal/deep link arrives
-override func handleLink(url: URL) {
-  // custom link handling
-}
-```
-
-#### Step 5: Subscribe in JavaScript
-
-Call `DashX.subscribe()` at app startup so the SDK registers the device as soon as the FCM token is available:
-
-```js
-import { useEffect } from 'react';
-import DashX from '@dashx/react-native';
-
-DashX.configure({ publicKey: 'your-public-key' });
-
-export default function App() {
-  useEffect(() => {
-    DashX.subscribe();
-  }, []);
-
-  // ...
-}
-```
-
-> **Without Firebase:** If you are not using FCM, omit the Firebase pods and the Firebase-related `AppDelegate` code. The SDK will still handle APNS permission requests and notification display via `DashXRCTAppDelegate`.
-
-## Usage
-
-```js
-import DashX from '@dashx/react-native';
-```
-
-### Configure
-
-Initialize the SDK once at app startup. Call `configure` at the top level of your entry file (e.g. `App.js`) so it runs before any component mounts:
-
-```js
-// App.js — call at module level, before the component
-import DashX from '@dashx/react-native';
-
-DashX.configure({
-  publicKey: 'your-public-key',
-  // baseURI: 'https://api.dashx.com',       // optional, custom API endpoint
-  // targetEnvironment: 'production',         // optional
-});
-
-export default function App() {
-  // ...
-}
-```
-
-Calling from `useEffect` in your root component also works, but module-level init is preferred so the SDK is ready as early as possible.
-
-| Option | Type | Required | Description |
-|--------|------|----------|-------------|
-| `publicKey` | `string` | Yes | Your DashX public key |
-| `baseURI` | `string` | No | Custom API base URI |
-| `targetEnvironment` | `string` | No | Target environment name |
-
-### Identify a user
-
-```js
-DashX.identify({
-  firstName: 'John',
-  lastName: 'Doe',
-  email: 'john@example.com',
-});
-```
-
-### Set identity with token
-
-```js
-DashX.setIdentity('user-uid', 'user-token');
-```
-
-### Reset
-
-Clear the current identity:
-
-```js
-DashX.reset();
-```
-
-### Track events
-
-```js
-DashX.track('Item Purchased', {
-  itemId: 'sku-123',
-  price: 9.99,
-});
-```
-
-### Track screen views
-
-```js
-DashX.screen('HomeScreen', {
-  referrer: 'DeepLink',
-});
-```
-
-### Fetch a record
-
-Fetch a single record by URN (e.g. `"article/uuid"`). The URN must use the full UUID form of the record ID.
-
-```js
-const record = await DashX.fetchRecord('article/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx', {
-  preview: false,
-  language: 'en',
-  // fields, include, exclude as arrays of objects if needed
-});
-```
-
-| Option | Type | Description |
-|--------|------|-------------|
-| `preview` | `boolean` | Include draft/preview content |
-| `language` | `string` | Content language |
-| `fields` | `object[]` | Fields to return |
-| `include` | `object[]` | Related data to include |
-| `exclude` | `object[]` | Fields to exclude |
-
-### Search records
-
-```js
-const records = await DashX.searchRecords('article', {
-  filter: { status: 'published' },
-  order: [{ field: 'createdAt', direction: 'desc' }],
-  limit: 10,
-  page: 1,
-  preview: false,
-  language: 'en',
-});
-```
-
-| Option | Type | Description |
-|--------|------|-------------|
-| `filter` | `object` | Filter criteria |
-| `order` | `object[]` | Sort order (e.g. `[{ field, direction }]`) |
-| `limit` | `number` | Max records to return |
-| `page` | `number` | Page number for pagination |
-| `preview` | `boolean` | Preview/draft content |
-| `language` | `string` | Content language |
-| `fields` | `object[]` | Fields to return |
-| `include` | `object[]` | Related data to include |
-| `exclude` | `object[]` | Fields to exclude |
-
-### Push notifications
-
-Subscribe the current device to push notifications:
-
-```js
-DashX.subscribe();
-```
-
-Unsubscribe:
-
-```js
-DashX.unsubscribe();
-```
-
-### Request notification permission (iOS)
-
-Prompt the user for push notification permission. Returns a `NotificationPermissionStatus` integer matching `UNAuthorizationStatus`:
-
-| Value | Meaning |
-|-------|---------|
-| `0` | Not determined |
-| `1` | Denied |
-| `2` | Authorized |
-| `3` | Provisional |
-| `4` | Ephemeral |
-
-```js
-const status = await DashX.requestNotificationPermission();
-if (status === 2) {
-  DashX.subscribe();
-}
-```
-
-To check the current status without prompting the user:
-
-```js
-const status = await DashX.getNotificationPermissionStatus();
-```
-
-### Listen for incoming messages
-
-Register a listener to handle push notifications when they arrive:
-
-```js
-import { useEffect } from 'react';
-
-useEffect(() => {
-  const subscription = DashX.onMessageReceived((message) => {
-    console.log('Notification received:', message);
-  });
-
-  return () => subscription.remove();
-}, []);
-```
-
-### Listen for deep links / universal links (iOS)
-
-Register a listener that fires when the SDK receives a universal link. On the native side, `DashXRCTAppDelegate` forwards links via `DashX.handleUserActivity` automatically.
-
-```js
-useEffect(() => {
-  const subscription = DashX.onLinkReceived((url) => {
-    console.log('Link received:', url);
-  });
-
-  return () => subscription.remove();
-}, []);
-```
-
-### Notification preferences
-
-Fetch the user's stored notification preferences:
+## Documentation
 
-```js
-const preferences = await DashX.fetchStoredPreferences();
-```
+For detailed documentation, visit [React Native SDK documentation](https://docs.dashx.com/sdks/client-side/react-native-sdk).
 
-Save updated preferences:
-
-```js
-await DashX.saveStoredPreferences({
-  marketing_emails: true,
-  product_updates: false,
-});
-```
+## Deep linking and push navigation
 
-### Upload an asset (iOS)
-
-Upload a local file to DashX and associate it with a resource and attribute:
-
-```js
-const response = await DashX.uploadAsset(
-  '/path/to/local/file.jpg',
-  'user',       // resource name
-  'avatar'      // attribute name
-);
-// response: { status, data: { asset: { status, url, playbackIds } } }
-```
-
-### Fetch an asset (iOS)
-
-Retrieve the status and URL of a previously uploaded asset by its ID:
-
-```js
-const asset = await DashX.fetchAsset('asset-id');
-// asset: { status, data: { asset: { status, url, playbackIds } } }
-```
-
-### Lifecycle tracking (iOS)
-
-Enable automatic app lifecycle event tracking (app opened, backgrounded, etc.):
-
-```js
-DashX.enableLifecycleTracking(); // no-op on Android
-```
-
-### Ad tracking / ATT (iOS)
-
-Request App Tracking Transparency permission and enable IDFA tracking:
-
-```js
-DashX.enableAdTracking(); // no-op on Android
-```
-
-Make sure `NSUserTrackingUsageDescription` is set in your `Info.plist`.
-
-### Logging
-
-Set the SDK log level for debugging:
-
-```js
-DashX.setLogLevel(1); // 0 = off, 1 = errors, 2 = debug
-```
-
-## API Reference
-
-| Method | Signature | Platforms | Returns | Description |
-|--------|-----------|-----------|---------|-------------|
-| `configure` | `(options: object)` | iOS, Android | `void` | Initialize the SDK with your public key |
-| `identify` | `(options: object)` | iOS, Android | `void` | Identify the current user with traits |
-| `setIdentity` | `(uid: string, token: string)` | iOS, Android | `void` | Set user identity with UID and auth token |
-| `reset` | `()` | iOS, Android | `void` | Clear the current user identity |
-| `track` | `(event: string, data?: object)` | iOS, Android | `void` | Track a named event with optional data |
-| `screen` | `(screenName: string, data?: object)` | iOS, Android | `void` | Track a screen view |
-| `fetchRecord` | `(urn: string, options?: object)` | iOS, Android | `Promise<object>` | Fetch a single record by URN (`"resource/uuid"`) |
-| `searchRecords` | `(resource: string, options?: object)` | iOS, Android | `Promise<object[]>` | Search records with filter, order, limit, page, etc. |
-| `subscribe` | `()` | iOS, Android | `void` | Subscribe device for push notifications |
-| `unsubscribe` | `()` | iOS, Android | `void` | Unsubscribe device from push notifications |
-| `fetchStoredPreferences` | `()` | iOS, Android | `Promise<object>` | Fetch stored notification preferences |
-| `saveStoredPreferences` | `(data: object)` | iOS, Android | `Promise<object>` | Save notification preferences |
-| `setLogLevel` | `(level: number)` | iOS, Android | `void` | Set SDK log verbosity (0=off, 1=errors, 2=debug) |
-| `onMessageReceived` | `(callback: function)` | iOS, Android | `EmitterSubscription` | Listen for incoming push notifications |
-| `requestNotificationPermission` | `()` | iOS | `Promise<number>` | Prompt for push permission; resolves with `UNAuthorizationStatus` (0-4) |
-| `getNotificationPermissionStatus` | `()` | iOS | `Promise<number>` | Get current push permission status without prompting |
-| `onLinkReceived` | `(callback: function)` | iOS | `EmitterSubscription` | Listen for universal/deep link events |
-| `uploadAsset` | `(filePath: string, resource: string, attribute: string)` | iOS | `Promise<AssetResponse>` | Upload a local file and associate it with a resource attribute |
-| `fetchAsset` | `(assetId: string)` | iOS | `Promise<AssetResponse>` | Fetch status and URL of an uploaded asset |
-| `enableLifecycleTracking` | `()` | iOS | `void` | Enable automatic app lifecycle event tracking |
-| `enableAdTracking` | `()` | iOS | `void` | Request ATT permission and enable IDFA tracking |
-
-For detailed usage and advanced features, refer to the [DashX documentation](https://docs.dashx.com).
-
-### Error Codes
-
-Promise rejections from native methods use a consistent error code across both platforms:
-
-| Code | Description |
-|------|-------------|
-| `EUNSPECIFIED` | An unspecified error occurred |
-
-The error code is available on the `code` property of the rejected error:
-
-```js
-try {
-  await DashX.fetchRecord('article/123');
-} catch (error) {
-  console.log(error.code);    // "EUNSPECIFIED"
-  console.log(error.message); // human-readable description
-}
-```
-
-A `DashXErrorCode` enum is exported from the TypeScript definitions for type-safe comparisons.
+See the [Deep Linking & Push Navigation](https://docs.dashx.com/apps/messaging/deep-linking) guide for setup instructions, payload fields, and code examples.
 
 ## Contributing
 
-Please follow [these steps](https://github.com/dashxhq/dashx-js/tree/master/examples/react-native#setting-up-development-environment) to set up the development environment.
-
-You'll also need Apollo CLI to generate files:
-
-```sh
-npm i -g apollo
-```
-
-## Publishing
-
-Use `yarn publish` to bump the version and release, then push the commit:
-
-```sh
-yarn publish
-git push origin main
-```
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and workflow.
 
 ## License
 

package/__tests__/index.test.js

@@ -16,6 +16,8 @@ const mockNativeModule = {
   fetchAsset: jest.fn(),
   enableLifecycleTracking: jest.fn(),
   enableAdTracking: jest.fn(),
+  processURL: jest.fn(),
+  trackNotificationNavigation: jest.fn(),
   requestNotificationPermission: jest.fn(),
   getNotificationPermissionStatus: jest.fn(),
   addListener: jest.fn(),
@@ -32,6 +34,7 @@ jest.mock('react-native', () => ({
     addListener: mockAddListener,
   })),
   Platform: {
+    OS: 'ios',
     select: jest.fn((obj) => obj.default || ''),
   },
 }));
@@ -325,6 +328,133 @@ describe('fetchAsset', () => {
   });
 });
 
+// --- processURL ---
+
+describe('processURL', () => {
+  it('calls native processURL with defaults', () => {
+    DashX.processURL('https://example.com/path');
+    expect(mockNativeModule.processURL).toHaveBeenCalledWith(
+      'https://example.com/path',
+      null,
+      true
+    );
+  });
+
+  it('passes source option', () => {
+    DashX.processURL('https://example.com', { source: 'universal_link' });
+    expect(mockNativeModule.processURL).toHaveBeenCalledWith(
+      'https://example.com',
+      'universal_link',
+      true
+    );
+  });
+
+  it('passes forwardToLinkHandler as false', () => {
+    DashX.processURL('https://example.com', { forwardToLinkHandler: false });
+    expect(mockNativeModule.processURL).toHaveBeenCalledWith(
+      'https://example.com',
+      null,
+      false
+    );
+  });
+
+  it('throws if url is missing', () => {
+    expect(() => DashX.processURL(null)).toThrow('url is required');
+  });
+
+  it('throws if url is not a string', () => {
+    expect(() => DashX.processURL(123)).toThrow(
+      'url is required and must be a string'
+    );
+  });
+
+  it('no-ops on Android', () => {
+    const { Platform } = require('react-native');
+    Platform.OS = 'android';
+    DashX.processURL('https://example.com');
+    expect(mockNativeModule.processURL).not.toHaveBeenCalled();
+    Platform.OS = 'ios';
+  });
+});
+
+// --- trackNotificationNavigation ---
+
+describe('trackNotificationNavigation', () => {
+  it('calls native with deepLink action', () => {
+    DashX.trackNotificationNavigation(
+      { type: 'deepLink', url: 'https://example.com' },
+      'notif-1'
+    );
+    expect(mockNativeModule.trackNotificationNavigation).toHaveBeenCalledWith(
+      { type: 'deepLink', url: 'https://example.com' },
+      'notif-1'
+    );
+  });
+
+  it('calls native with screen action', () => {
+    DashX.trackNotificationNavigation(
+      { type: 'screen', name: 'Home', data: { ref: 'banner' } },
+      'notif-2'
+    );
+    expect(mockNativeModule.trackNotificationNavigation).toHaveBeenCalledWith(
+      { type: 'screen', name: 'Home', data: { ref: 'banner' } },
+      'notif-2'
+    );
+  });
+
+  it('calls native with richLanding action', () => {
+    DashX.trackNotificationNavigation(
+      { type: 'richLanding', url: 'https://promo.example.com' },
+      'notif-3'
+    );
+    expect(mockNativeModule.trackNotificationNavigation).toHaveBeenCalledWith(
+      { type: 'richLanding', url: 'https://promo.example.com' },
+      'notif-3'
+    );
+  });
+
+  it('calls native with clickAction action', () => {
+    DashX.trackNotificationNavigation(
+      { type: 'clickAction', action: 'OPEN_SETTINGS' },
+      'notif-4'
+    );
+    expect(mockNativeModule.trackNotificationNavigation).toHaveBeenCalledWith(
+      { type: 'clickAction', action: 'OPEN_SETTINGS' },
+      'notif-4'
+    );
+  });
+
+  it('calls native with null action when omitted', () => {
+    DashX.trackNotificationNavigation(null, 'notif-5');
+    expect(mockNativeModule.trackNotificationNavigation).toHaveBeenCalledWith(
+      null,
+      'notif-5'
+    );
+  });
+
+  it('calls native with null for both when both omitted', () => {
+    DashX.trackNotificationNavigation();
+    expect(mockNativeModule.trackNotificationNavigation).toHaveBeenCalledWith(
+      null,
+      null
+    );
+  });
+
+  it('throws if action is not an object', () => {
+    expect(() => DashX.trackNotificationNavigation('bad')).toThrow(
+      'action must be an object or null'
+    );
+  });
+
+  it('no-ops on Android', () => {
+    const { Platform } = require('react-native');
+    Platform.OS = 'android';
+    DashX.trackNotificationNavigation({ type: 'deepLink', url: 'https://example.com' });
+    expect(mockNativeModule.trackNotificationNavigation).not.toHaveBeenCalled();
+    Platform.OS = 'ios';
+  });
+});
+
 // --- requestNotificationPermission / getNotificationPermissionStatus ---
 
 describe('requestNotificationPermission', () => {

package/android/build.gradle

@@ -55,5 +55,5 @@ dependencies {
     // Ensure Firebase Messaging types are available for FCM service subclass
     implementation 'com.google.firebase:firebase-messaging-ktx:23.1.2'
 
-    implementation "com.dashx:dashx-android:1.1.7"
+    implementation "com.dashx:dashx-android:1.2.4"
 }

package/index.d.ts

@@ -66,6 +66,17 @@ export interface NotificationMessage {
   [key: string]: unknown;
 }
 
+export type NavigationAction =
+  | { type: 'deepLink'; url: string }
+  | { type: 'screen'; name: string; data?: Record<string, string> }
+  | { type: 'richLanding'; url: string }
+  | { type: 'clickAction'; action: string };
+
+export interface ProcessURLOptions {
+  source?: string;
+  forwardToLinkHandler?: boolean;
+}
+
 export interface DashXInstance {
   /**
    * Initialize the SDK with your public key and optional configuration.
@@ -176,6 +187,24 @@ export interface DashXInstance {
    */
   enableAdTracking(): void;
 
+  /**
+   * Track a deep link open event and optionally forward the URL to the link handler (iOS only).
+   * @param url The deep link URL string.
+   * @param options.source Optional attribution source (e.g. "universal_link", "notification").
+   * @param options.forwardToLinkHandler Whether to forward to the link handler callback (default: true).
+   */
+  processURL(url: string, options?: ProcessURLOptions): void;
+
+  /**
+   * Track a notification navigation event when the user taps a notification (iOS only).
+   * @param action The navigation action taken, or null/undefined for default.
+   * @param notificationId Optional notification ID to associate with the event.
+   */
+  trackNotificationNavigation(
+    action?: NavigationAction | null,
+    notificationId?: string
+  ): void;
+
   /**
    * Request push notification permission from the user.
    * Resolves with a NotificationPermissionStatus integer.

package/index.js

@@ -177,6 +177,31 @@ const DashX = {
     return getNativeDashX().enableAdTracking();
   },
 
+  processURL(url, options = {}) {
+    if (Platform.OS !== 'ios') return;
+    if (!url || typeof url !== 'string') {
+      throw new Error('DashX.processURL: url is required and must be a string');
+    }
+    return getNativeDashX().processURL(
+      url,
+      options.source || null,
+      options.forwardToLinkHandler !== false
+    );
+  },
+
+  trackNotificationNavigation(action, notificationId) {
+    if (Platform.OS !== 'ios') return;
+    if (action != null && typeof action !== 'object') {
+      throw new Error(
+        'DashX.trackNotificationNavigation: action must be an object or null'
+      );
+    }
+    return getNativeDashX().trackNotificationNavigation(
+      action || null,
+      notificationId || null
+    );
+  },
+
   requestNotificationPermission() {
     return getNativeDashX().requestNotificationPermission();
   },

package/ios/DashXReactNative.swift

@@ -183,6 +183,40 @@ class DashXReactNative: RCTEventEmitter {
         DashX.enableAdTracking()
     }
 
+    @objc(processURL:source:forwardToLinkHandler:)
+    func processURL(_ url: String, source: NSString?, forwardToLinkHandler: Bool) {
+        guard let parsedURL = URL(string: url) else { return }
+        DashX.processURL(parsedURL, source: source as String?, forwardToLinkHandler: forwardToLinkHandler)
+    }
+
+    @objc(trackNotificationNavigation:notificationId:)
+    func trackNotificationNavigation(_ action: NSDictionary?, notificationId: NSString?) {
+        var navigationAction: NavigationAction? = nil
+        if let action = action, let type = action["type"] as? String {
+            switch type {
+            case "deepLink":
+                if let urlString = action["url"] as? String, let url = URL(string: urlString) {
+                    navigationAction = .deepLink(url: url)
+                }
+            case "screen":
+                if let name = action["name"] as? String {
+                    navigationAction = .screen(name: name, data: action["data"] as? [String: String])
+                }
+            case "richLanding":
+                if let urlString = action["url"] as? String, let url = URL(string: urlString) {
+                    navigationAction = .richLanding(url: url)
+                }
+            case "clickAction":
+                if let actionStr = action["action"] as? String {
+                    navigationAction = .clickAction(action: actionStr)
+                }
+            default:
+                break
+            }
+        }
+        DashX.trackNotificationNavigation(navigationAction, notificationId: notificationId as String?)
+    }
+
     @objc(requestNotificationPermission:rejecter:)
     func requestNotificationPermission(_ resolve: @escaping RCTPromiseResolveBlock, rejecter reject: @escaping RCTPromiseRejectBlock) {
         DashX.requestNotificationPermission { status in resolve(status.rawValue) }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@dashx/react-native",
   "title": "DashX React Native",
-  "version": "1.1.4",
+  "version": "1.1.5",
   "description": "DashX SDK for React Native",
   "main": "index.js",
   "types": "index.d.ts",