@linkforty/mobile-sdk-react-native 1.0.0 → 1.1.0

package/CHANGELOG.md

@@ -1,136 +1,28 @@
 # Changelog
 
-All notable changes to the LinkForty React Native SDK will be documented in this file.
+All notable changes to this project will be documented in this file.
 
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [1.0.0] - 2024-11-22
+## [1.1.0] - 2026-02-11
 
 ### Added
-- Initial release of LinkForty React Native SDK
-- **Deferred Deep Linking** - Route new users to specific content after install
-- **Direct Deep Linking** - Handle Universal Links (iOS) and App Links (Android)
-- **Probabilistic Attribution** - Match installs to clicks with 70%+ confidence
-- **Event Tracking** - Track in-app events with attribution
-- **Privacy-Focused** - No persistent device IDs required
-- **TypeScript Support** - Full type definitions included
-- **Works with Core & Cloud** - Compatible with self-hosted and Cloud instances
-
-### Core Features
-
-#### SDK Initialization
-- `init(config)` - Initialize SDK with base URL and optional API key
-- Support for debug logging during development
-- Customizable attribution window (default: 7 days)
-
-#### Deep Linking
-- `onDeferredDeepLink(callback)` - Handle deferred deep links for new installs
-- `onDeepLink(callback)` - Handle direct deep links for existing users
-- Automatic Universal Links (iOS) and App Links (Android) configuration
-- Deep link data includes UTM parameters and custom parameters
-
-#### Event Tracking
-- `trackEvent(name, properties)` - Track in-app events with optional properties
-- Automatic attribution to install source
-- Webhook triggers for conversion events
-- Support for revenue tracking and custom event properties
-
-#### Data Management
-- `getInstallData()` - Retrieve cached install attribution data
-- `getInstallId()` - Get unique install ID for this app installation
-- `clearData()` - Clear all cached SDK data (useful for testing)
-
-### Device Fingerprinting
-
-Collects the following non-invasive signals for probabilistic attribution:
-- User agent string
-- Device timezone
-- Device language
-- Screen resolution
-- Platform (iOS/Android)
-- Device model and OS version
-- IP address (server-side only)
-
-### API Endpoints
-
-Uses the following LinkForty Core API endpoints:
-- `POST /api/sdk/v1/install` - Report app installation
-- `POST /api/sdk/v1/event` - Track in-app events
-- `GET /api/sdk/v1/attribution/:fingerprint` - Debug attribution data
-- `GET /api/sdk/v1/health` - Health check
-
-### Dependencies
-
-**Peer Dependencies:**
-- `react` >= 16.8.0
-- `react-native` >= 0.60.0
-
-**Runtime Dependencies:**
-- `@react-native-async-storage/async-storage` ^1.21.0
-- `react-native-device-info` ^10.12.0
-
-### Platform Support
-
-- ✅ iOS 12+
-- ✅ Android 5.0+ (API level 21+)
-- ✅ React Native 0.60+
-- ✅ TypeScript 5.3+
-- ✅ Expo (with custom native modules)
-
-### Security
-
-- No persistent device identifiers stored
-- Privacy-focused fingerprinting
-- Configurable attribution window
-- Secure HTTPS-only communication
-- No third-party tracking SDKs
-
-### Documentation
-
-- Comprehensive README with setup instructions
-- TypeScript type definitions included
-- iOS Universal Links setup guide
-- Android App Links setup guide
-- Troubleshooting guide
-- API reference with examples
-
----
-
-## [Unreleased]
+- Server-side URL resolution for deep links intercepted by App Links (Android) and Universal Links (iOS) — when the OS opens the app directly, the SDK now calls the resolve endpoint to retrieve custom parameters, UTM data, and link metadata
+- Device fingerprint collection sent with resolve requests for click attribution and deferred deep linking analytics
+- `deepLinkPath` and `appScheme` optional fields on `DeepLinkData` type
+- `ResolveFunction` type export for advanced SDK consumers
 
 ### Changed
-- Removed unused dependencies `@onamfc/developer-log` and `@onamfc/pkg-inspect` to reduce bundle size
-
-### Planned Features
-- iOS SDK (Native Swift) - Q2 2025
-- Android SDK (Native Kotlin) - Q2 2025
-- React Native Expo compatibility mode
-- Offline event queue for poor network conditions
-- Advanced debugging tools
-- Custom domain support
-- A/B testing integration
-- User segmentation
-
----
-
-## Version History
-
-- **1.0.0** - Initial release (2024-11-22)
-
-## Migration Guides
-
-### Upgrading to 1.0.0
-
-This is the initial release, so no migration is necessary.
-
-## Support
+- `DeepLinkHandler.handleDeepLink` is now async to support server-side URL resolution
+- `DeepLinkHandler.initialize` accepts an optional `resolveFn` parameter for URL resolution
+- `DeepLinkHandler.parseURL` now correctly extracts the short code from template URLs (e.g., `/templateSlug/shortCode`)
+- `LinkFortySDK.onDeepLink` automatically provides a resolver that calls the backend resolve endpoint
+- Deferred deep link responses now normalize `deepLinkParameters` from the backend into `customParameters` for a consistent interface across direct and deferred deep link paths
 
-For issues, questions, or feature requests:
-- GitHub Issues: https://github.com/linkforty/react-native-sdk/issues
-- Documentation: https://docs.linkforty.com
-- Discord Community: https://discord.gg/linkforty
+### Fixed
+- Fixed deep links returning empty `customParameters` when the app was opened via App Links or Universal Links, where the OS intercepted the URL before the LinkForty server could append parameters via redirect
 
-## License
+## [1.0.1] - 2025-12-11
 
-This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+- Initial release

package/README.md

@@ -15,15 +15,15 @@ Official React Native SDK for [LinkForty](https://github.com/linkforty/core) - O
 ## Installation
 
 ```bash
-npm install @linkforty/react-native-sdk
+npm i @linkforty/mobile-sdk-react-native
 # or
-yarn add @linkforty/react-native-sdk
+yarn add @linkforty/mobile-sdk-react-native
 ```
 
 ### Requirements
 
-- React Native >= 0.76.0
-- React >= 18.3.0
+- React Native >= 0.64.0
+- React >= 17.0.0
 - Node.js >= 20.0.0
 
 ### Additional Dependencies
@@ -104,7 +104,7 @@ cd ios && pod install
 ## Quick Start
 
 ```typescript
-import LinkForty from '@linkforty/react-native-sdk';
+import LinkForty from '@linkforty/mobile-sdk-react-native';
 
 // Initialize SDK (call in App.tsx or index.js)
 await LinkForty.init({

package/dist/DeepLinkHandler.d.ts

@@ -1,24 +1,43 @@
 /**
  * DeepLinkHandler - Handles Universal Links (iOS) and App Links (Android)
+ *
+ * When the OS intercepts a LinkForty URL via App Links or Universal Links,
+ * the redirect server is bypassed. This handler detects LinkForty URLs and
+ * resolves them via the server API to retrieve the full deep link data
+ * (custom parameters, UTM params, etc.) that would normally be appended
+ * during the redirect.
  */
-import type { DeepLinkData, DeepLinkCallback } from './types';
+import type { DeepLinkData, DeepLinkCallback, ResolveFunction } from './types';
 export declare class DeepLinkHandler {
     private callback;
     private baseUrl;
+    private resolveFn;
     /**
      * Initialize deep link listener
+     * @param baseUrl - LinkForty instance base URL for detecting LinkForty URLs
+     * @param callback - Callback invoked with parsed/resolved deep link data
+     * @param resolveFn - Optional function to resolve LinkForty URLs via the server API
      */
-    initialize(baseUrl: string, callback: DeepLinkCallback): void;
+    initialize(baseUrl: string, callback: DeepLinkCallback, resolveFn?: ResolveFunction): void;
     /**
      * Clean up listeners
      */
     cleanup(): void;
     /**
-     * Handle incoming deep link
+     * Handle incoming deep link.
+     * If the URL is a LinkForty URL and a resolver is available, resolves via the server.
+     * Falls back to local URL parsing on failure.
      */
     private handleDeepLink;
     /**
-     * Parse deep link URL and extract data
+     * Resolve a LinkForty URL via the server API.
+     * Extracts the path from the URL, collects fingerprint data for click attribution,
+     * and calls the resolve endpoint.
+     */
+    private resolveURL;
+    /**
+     * Parse deep link URL and extract data locally (without server call).
+     * Used as fallback when server resolution fails or for non-LinkForty URLs.
      */
     parseURL(url: string): DeepLinkData | null;
 }

package/dist/DeepLinkHandler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"DeepLinkHandler.d.ts","sourceRoot":"","sources":["../src/DeepLinkHandler.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAE9D,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAiC;IACjD,OAAO,CAAC,OAAO,CAAuB;IAEtC;;OAEG;IACH,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,gBAAgB,GAAG,IAAI;IAe7D;;OAEG;IACH,OAAO,IAAI,IAAI;IAKf;;OAEG;IACH,OAAO,CAAC,cAAc,CAOpB;IAEF;;OAEG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI;CA2C3C"}
+{"version":3,"file":"DeepLinkHandler.d.ts","sourceRoot":"","sources":["../src/DeepLinkHandler.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,KAAK,EAAE,YAAY,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAE/E,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAiC;IACjD,OAAO,CAAC,OAAO,CAAuB;IACtC,OAAO,CAAC,SAAS,CAAgC;IAEjD;;;;;OAKG;IACH,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,gBAAgB,EAAE,SAAS,CAAC,EAAE,eAAe,GAAG,IAAI;IAgB1F;;OAEG;IACH,OAAO,IAAI,IAAI;IAKf;;;;OAIG;IACH,OAAO,CAAC,cAAc,CAuBpB;IAEF;;;;OAIG;YACW,UAAU;IA2CxB;;;OAGG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI;CA4C3C"}

package/dist/DeepLinkHandler.js

@@ -1,16 +1,28 @@
 /**
  * DeepLinkHandler - Handles Universal Links (iOS) and App Links (Android)
+ *
+ * When the OS intercepts a LinkForty URL via App Links or Universal Links,
+ * the redirect server is bypassed. This handler detects LinkForty URLs and
+ * resolves them via the server API to retrieve the full deep link data
+ * (custom parameters, UTM params, etc.) that would normally be appended
+ * during the redirect.
  */
 import { Linking } from 'react-native';
+import { FingerprintCollector } from './FingerprintCollector';
 export class DeepLinkHandler {
     callback = null;
     baseUrl = null;
+    resolveFn = null;
     /**
      * Initialize deep link listener
+     * @param baseUrl - LinkForty instance base URL for detecting LinkForty URLs
+     * @param callback - Callback invoked with parsed/resolved deep link data
+     * @param resolveFn - Optional function to resolve LinkForty URLs via the server API
      */
-    initialize(baseUrl, callback) {
+    initialize(baseUrl, callback, resolveFn) {
         this.baseUrl = baseUrl;
         this.callback = callback;
+        this.resolveFn = resolveFn || null;
         // Listen for deep links when app is already open
         Linking.addEventListener('url', this.handleDeepLink);
         // Check if app was opened via deep link
@@ -28,17 +40,78 @@ export class DeepLinkHandler {
         this.callback = null;
     }
     /**
-     * Handle incoming deep link
+     * Handle incoming deep link.
+     * If the URL is a LinkForty URL and a resolver is available, resolves via the server.
+     * Falls back to local URL parsing on failure.
      */
-    handleDeepLink = ({ url }) => {
+    handleDeepLink = async ({ url }) => {
         if (!this.callback || !url) {
             return;
         }
-        const deepLinkData = this.parseURL(url);
-        this.callback(url, deepLinkData);
+        // Parse locally first (for fallback and to detect LinkForty URLs)
+        const localData = this.parseURL(url);
+        // If this is a LinkForty URL and we have a resolver, try the server
+        if (localData && this.resolveFn && this.baseUrl && url.startsWith(this.baseUrl)) {
+            try {
+                const resolvedData = await this.resolveURL(url);
+                if (resolvedData) {
+                    this.callback(url, resolvedData);
+                    return;
+                }
+            }
+            catch (error) {
+                console.warn('[LinkForty] Failed to resolve URL from server, falling back to local parse:', error);
+            }
+        }
+        // Fallback to locally-parsed data
+        this.callback(url, localData);
     };
     /**
-     * Parse deep link URL and extract data
+     * Resolve a LinkForty URL via the server API.
+     * Extracts the path from the URL, collects fingerprint data for click attribution,
+     * and calls the resolve endpoint.
+     */
+    async resolveURL(url) {
+        if (!this.resolveFn) {
+            return null;
+        }
+        const parsedUrl = new URL(url);
+        const pathSegments = parsedUrl.pathname.split('/').filter(Boolean);
+        if (pathSegments.length === 0) {
+            return null;
+        }
+        // Build resolve endpoint path (handles both /shortCode and /templateSlug/shortCode)
+        let resolvePath;
+        if (pathSegments.length >= 2) {
+            resolvePath = `/api/sdk/v1/resolve/${pathSegments[0]}/${pathSegments[1]}`;
+        }
+        else {
+            resolvePath = `/api/sdk/v1/resolve/${pathSegments[0]}`;
+        }
+        // Collect fingerprint data for click attribution
+        try {
+            const fingerprint = await FingerprintCollector.collect();
+            const [sw, sh] = fingerprint.screenResolution.split('x');
+            const queryParams = new URLSearchParams();
+            queryParams.set('fp_tz', fingerprint.timezone);
+            queryParams.set('fp_lang', fingerprint.language);
+            queryParams.set('fp_sw', sw);
+            queryParams.set('fp_sh', sh);
+            queryParams.set('fp_platform', fingerprint.platform);
+            if (fingerprint.osVersion) {
+                queryParams.set('fp_pv', fingerprint.osVersion);
+            }
+            resolvePath += `?${queryParams.toString()}`;
+        }
+        catch (error) {
+            // If fingerprint collection fails, still resolve without it
+            console.warn('[LinkForty] Fingerprint collection failed, resolving without fingerprint:', error);
+        }
+        return this.resolveFn(resolvePath);
+    }
+    /**
+     * Parse deep link URL and extract data locally (without server call).
+     * Used as fallback when server resolution fails or for non-LinkForty URLs.
      */
     parseURL(url) {
         try {
@@ -47,8 +120,9 @@ export class DeepLinkHandler {
             if (this.baseUrl && !url.startsWith(this.baseUrl)) {
                 return null;
             }
-            // Extract short code from path
-            const shortCode = parsedUrl.pathname.replace('/', '');
+            // Extract short code from path (last segment handles both /shortCode and /templateSlug/shortCode)
+            const pathSegments = parsedUrl.pathname.split('/').filter(Boolean);
+            const shortCode = pathSegments[pathSegments.length - 1];
             if (!shortCode) {
                 return null;
             }

package/dist/LinkFortySDK.d.ts

@@ -21,7 +21,9 @@ export declare class LinkFortySDK {
      */
     onDeferredDeepLink(callback: DeferredDeepLinkCallback): void;
     /**
-     * Register callback for direct deep links (existing users)
+     * Register callback for direct deep links (existing users).
+     * When a LinkForty URL is detected, the SDK will resolve it via the server
+     * to retrieve the full deep link data (custom parameters, UTM params, etc.).
      */
     onDeepLink(callback: DeepLinkCallback): void;
     /**

package/dist/LinkFortySDK.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"LinkFortySDK.d.ts","sourceRoot":"","sources":["../src/LinkFortySDK.ts"],"names":[],"mappings":"AAAA;;GAEG;AAKH,OAAO,KAAK,EACV,eAAe,EAEf,YAAY,EACZ,wBAAwB,EACxB,gBAAgB,EACjB,MAAM,SAAS,CAAC;AAQjB,qBAAa,YAAY;IACvB,OAAO,CAAC,MAAM,CAAgC;IAC9C,OAAO,CAAC,eAAe,CAAgC;IACvD,OAAO,CAAC,wBAAwB,CAAyC;IACzE,OAAO,CAAC,SAAS,CAAuB;IACxC,OAAO,CAAC,WAAW,CAAkB;IAErC;;OAEG;IACG,IAAI,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IAiClD;;OAEG;IACG,cAAc,IAAI,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC;IAQpD;;OAEG;IACH,kBAAkB,CAAC,QAAQ,EAAE,wBAAwB,GAAG,IAAI;IAW5D;;OAEG;IACH,UAAU,CAAC,QAAQ,EAAE,gBAAgB,GAAG,IAAI;IAY5C;;OAEG;IACG,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAgC/E;;OAEG;IACG,YAAY,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAa5C;;OAEG;IACG,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;IAchC;;OAEG;YACW,aAAa;IAW3B;;OAEG;YACW,aAAa;IAsF3B;;OAEG;YACW,eAAe;IAI7B;;OAEG;YACW,UAAU;CA+BzB;;AAGD,wBAAkC"}
+{"version":3,"file":"LinkFortySDK.d.ts","sourceRoot":"","sources":["../src/LinkFortySDK.ts"],"names":[],"mappings":"AAAA;;GAEG;AAKH,OAAO,KAAK,EACV,eAAe,EAEf,YAAY,EACZ,wBAAwB,EACxB,gBAAgB,EACjB,MAAM,SAAS,CAAC;AAQjB,qBAAa,YAAY;IACvB,OAAO,CAAC,MAAM,CAAgC;IAC9C,OAAO,CAAC,eAAe,CAAgC;IACvD,OAAO,CAAC,wBAAwB,CAAyC;IACzE,OAAO,CAAC,SAAS,CAAuB;IACxC,OAAO,CAAC,WAAW,CAAkB;IAErC;;OAEG;IACG,IAAI,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IAiClD;;OAEG;IACG,cAAc,IAAI,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC;IAQpD;;OAEG;IACH,kBAAkB,CAAC,QAAQ,EAAE,wBAAwB,GAAG,IAAI;IAW5D;;;;OAIG;IACH,UAAU,CAAC,QAAQ,EAAE,gBAAgB,GAAG,IAAI;IAwB5C;;OAEG;IACG,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAgC/E;;OAEG;IACG,YAAY,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAa5C;;OAEG;IACG,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;IAchC;;OAEG;YACW,aAAa;IAW3B;;OAEG;YACW,aAAa;IA+F3B;;OAEG;YACW,eAAe;IAI7B;;OAEG;YACW,UAAU;CA+BzB;;AAGD,wBAAkC"}

package/dist/LinkFortySDK.js

@@ -67,7 +67,9 @@ export class LinkFortySDK {
         });
     }
     /**
-     * Register callback for direct deep links (existing users)
+     * Register callback for direct deep links (existing users).
+     * When a LinkForty URL is detected, the SDK will resolve it via the server
+     * to retrieve the full deep link data (custom parameters, UTM params, etc.).
      */
     onDeepLink(callback) {
         if (!this.config) {
@@ -76,7 +78,19 @@ export class LinkFortySDK {
         if (!this.deepLinkHandler) {
             this.deepLinkHandler = new DeepLinkHandler();
         }
-        this.deepLinkHandler.initialize(this.config.baseUrl, callback);
+        // Create a resolver that wraps the private apiRequest method
+        const resolveFn = async (path) => {
+            try {
+                return await this.apiRequest(path);
+            }
+            catch (error) {
+                if (this.config?.debug) {
+                    console.log('[LinkForty] URL resolve failed:', error);
+                }
+                return null;
+            }
+        };
+        this.deepLinkHandler.initialize(this.config.baseUrl, callback, resolveFn);
     }
     /**
      * Track in-app event
@@ -191,10 +205,18 @@ export class LinkFortySDK {
             }
             // If attributed, store deep link data
             if (response.attributed && response.deepLinkData) {
-                await AsyncStorage.setItem(STORAGE_KEYS.INSTALL_DATA, JSON.stringify(response.deepLinkData));
+                // Normalize backend response to match DeepLinkData type
+                // Populate customParameters from deepLinkParameters so app developers
+                // get a consistent field regardless of direct vs deferred deep link path
+                const deepLinkData = {
+                    ...response.deepLinkData,
+                    customParameters: response.deepLinkData.deepLinkParameters
+                        || response.deepLinkData.customParameters,
+                };
+                await AsyncStorage.setItem(STORAGE_KEYS.INSTALL_DATA, JSON.stringify(deepLinkData));
                 // Call deferred deep link callback if registered
                 if (this.deferredDeepLinkCallback) {
-                    this.deferredDeepLinkCallback(response.deepLinkData);
+                    this.deferredDeepLinkCallback(deepLinkData);
                 }
                 if (this.config.debug) {
                     console.log('[LinkForty] Install attributed with confidence:', response.confidenceScore);

package/dist/index.d.ts

@@ -9,5 +9,5 @@ export { default } from './LinkFortySDK';
 export { LinkFortySDK } from './LinkFortySDK';
 export { FingerprintCollector } from './FingerprintCollector';
 export { DeepLinkHandler } from './DeepLinkHandler';
-export type { LinkFortyConfig, DeviceFingerprint, DeepLinkData, InstallAttributionResponse, EventData, DeferredDeepLinkCallback, DeepLinkCallback, } from './types';
+export type { LinkFortyConfig, DeviceFingerprint, DeepLinkData, InstallAttributionResponse, EventData, DeferredDeepLinkCallback, DeepLinkCallback, ResolveFunction, } from './types';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAGzC,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAC9D,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAGpD,YAAY,EACV,eAAe,EACf,iBAAiB,EACjB,YAAY,EACZ,0BAA0B,EAC1B,SAAS,EACT,wBAAwB,EACxB,gBAAgB,GACjB,MAAM,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAGzC,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAC9D,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAGpD,YAAY,EACV,eAAe,EACf,iBAAiB,EACjB,YAAY,EACZ,0BAA0B,EAC1B,SAAS,EACT,wBAAwB,EACxB,gBAAgB,EAChB,eAAe,GAChB,MAAM,SAAS,CAAC"}

package/dist/types.d.ts

@@ -57,8 +57,12 @@ export interface DeepLinkData {
         term?: string;
         content?: string;
     };
-    /** Custom query parameters */
+    /** Custom parameters (from URL query params on direct links, or from link configuration on deferred links) */
     customParameters?: Record<string, string>;
+    /** In-app destination path (e.g., '/video/123') */
+    deepLinkPath?: string;
+    /** Custom URI scheme (e.g., 'myapp') */
+    appScheme?: string;
     /** Click timestamp */
     clickedAt?: string;
     /** Link ID */
@@ -103,4 +107,10 @@ export type DeferredDeepLinkCallback = (deepLinkData: DeepLinkData | null) => vo
  * Callback function for direct deep links
  */
 export type DeepLinkCallback = (url: string, deepLinkData: DeepLinkData | null) => void;
+/**
+ * Function that resolves a LinkForty URL path to deep link data via the server.
+ * Used internally by DeepLinkHandler when the OS intercepts a LinkForty URL
+ * before the server can process the redirect.
+ */
+export type ResolveFunction = (path: string) => Promise<DeepLinkData | null>;
 //# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,8EAA8E;IAC9E,OAAO,EAAE,MAAM,CAAC;IAChB,gDAAgD;IAChD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,2BAA2B;IAC3B,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,qDAAqD;IACrD,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,+BAA+B;IAC/B,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,wBAAwB;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB,sBAAsB;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,sBAAsB;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,yCAAyC;IACzC,gBAAgB,EAAE,MAAM,CAAC;IACzB,oCAAoC;IACpC,QAAQ,EAAE,MAAM,CAAC;IACjB,mBAAmB;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,iBAAiB;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,kBAAkB;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,kCAAkC;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB,kBAAkB;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,sBAAsB;IACtB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,uBAAuB;IACvB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,qBAAqB;IACrB,aAAa,CAAC,EAAE;QACd,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,OAAO,CAAC,EAAE,MAAM,CAAC;KAClB,CAAC;IACF,8BAA8B;IAC9B,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC1C,sBAAsB;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,cAAc;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;GAGG;AACH,MAAM,WAAW,0BAA0B;IACzC,yBAAyB;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,yCAAyC;IACzC,UAAU,EAAE,OAAO,CAAC;IACpB,2CAA2C;IAC3C,eAAe,EAAE,MAAM,CAAC;IACxB,0GAA0G;IAC1G,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,4FAA4F;IAC5F,YAAY,EAAE,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;CACpD;AAED;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,6DAA6D;IAC7D,IAAI,EAAE,MAAM,CAAC;IACb,uBAAuB;IACvB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IACjC,6CAA6C;IAC7C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,kCAAkC;IAClC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,iCAAiC;IACjC,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,MAAM,wBAAwB,GAAG,CAAC,YAAY,EAAE,YAAY,GAAG,IAAI,KAAK,IAAI,CAAC;AAEnF;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,YAAY,EAAE,YAAY,GAAG,IAAI,KAAK,IAAI,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,8EAA8E;IAC9E,OAAO,EAAE,MAAM,CAAC;IAChB,gDAAgD;IAChD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,2BAA2B;IAC3B,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,qDAAqD;IACrD,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,+BAA+B;IAC/B,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,wBAAwB;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB,sBAAsB;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,sBAAsB;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,yCAAyC;IACzC,gBAAgB,EAAE,MAAM,CAAC;IACzB,oCAAoC;IACpC,QAAQ,EAAE,MAAM,CAAC;IACjB,mBAAmB;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,iBAAiB;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,kBAAkB;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,kCAAkC;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB,kBAAkB;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,sBAAsB;IACtB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,uBAAuB;IACvB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,qBAAqB;IACrB,aAAa,CAAC,EAAE;QACd,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,OAAO,CAAC,EAAE,MAAM,CAAC;KAClB,CAAC;IACF,8GAA8G;IAC9G,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC1C,mDAAmD;IACnD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,wCAAwC;IACxC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,sBAAsB;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,cAAc;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;GAGG;AACH,MAAM,WAAW,0BAA0B;IACzC,yBAAyB;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,yCAAyC;IACzC,UAAU,EAAE,OAAO,CAAC;IACpB,2CAA2C;IAC3C,eAAe,EAAE,MAAM,CAAC;IACxB,0GAA0G;IAC1G,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,4FAA4F;IAC5F,YAAY,EAAE,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;CACpD;AAED;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,6DAA6D;IAC7D,IAAI,EAAE,MAAM,CAAC;IACb,uBAAuB;IACvB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IACjC,6CAA6C;IAC7C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,kCAAkC;IAClC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,iCAAiC;IACjC,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,MAAM,wBAAwB,GAAG,CAAC,YAAY,EAAE,YAAY,GAAG,IAAI,KAAK,IAAI,CAAC;AAEnF;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,YAAY,EAAE,YAAY,GAAG,IAAI,KAAK,IAAI,CAAC;AAExF;;;;GAIG;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@linkforty/mobile-sdk-react-native",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "React Native SDK for LinkForty - Open-source deep linking and mobile attribution platform",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -41,8 +41,8 @@
     "npm": ">=10.0.0"
   },
   "peerDependencies": {
-    "react": ">=18.3.0",
-    "react-native": ">=0.76.0"
+    "react": ">=17.0.0",
+    "react-native": ">=0.64.0"
   },
   "dependencies": {
     "@react-native-async-storage/async-storage": "^2.2.0",

package/src/DeepLinkHandler.ts

@@ -1,20 +1,32 @@
 /**
  * DeepLinkHandler - Handles Universal Links (iOS) and App Links (Android)
+ *
+ * When the OS intercepts a LinkForty URL via App Links or Universal Links,
+ * the redirect server is bypassed. This handler detects LinkForty URLs and
+ * resolves them via the server API to retrieve the full deep link data
+ * (custom parameters, UTM params, etc.) that would normally be appended
+ * during the redirect.
  */
 
 import { Linking } from 'react-native';
-import type { DeepLinkData, DeepLinkCallback } from './types';
+import { FingerprintCollector } from './FingerprintCollector';
+import type { DeepLinkData, DeepLinkCallback, ResolveFunction } from './types';
 
 export class DeepLinkHandler {
   private callback: DeepLinkCallback | null = null;
   private baseUrl: string | null = null;
+  private resolveFn: ResolveFunction | null = null;
 
   /**
    * Initialize deep link listener
+   * @param baseUrl - LinkForty instance base URL for detecting LinkForty URLs
+   * @param callback - Callback invoked with parsed/resolved deep link data
+   * @param resolveFn - Optional function to resolve LinkForty URLs via the server API
    */
-  initialize(baseUrl: string, callback: DeepLinkCallback): void {
+  initialize(baseUrl: string, callback: DeepLinkCallback, resolveFn?: ResolveFunction): void {
     this.baseUrl = baseUrl;
     this.callback = callback;
+    this.resolveFn = resolveFn || null;
 
     // Listen for deep links when app is already open
     Linking.addEventListener('url', this.handleDeepLink);
@@ -36,19 +48,86 @@ export class DeepLinkHandler {
   }
 
   /**
-   * Handle incoming deep link
+   * Handle incoming deep link.
+   * If the URL is a LinkForty URL and a resolver is available, resolves via the server.
+   * Falls back to local URL parsing on failure.
    */
-  private handleDeepLink = ({ url }: { url: string }): void => {
+  private handleDeepLink = async ({ url }: { url: string }): Promise<void> => {
     if (!this.callback || !url) {
       return;
     }
 
-    const deepLinkData = this.parseURL(url);
-    this.callback(url, deepLinkData);
+    // Parse locally first (for fallback and to detect LinkForty URLs)
+    const localData = this.parseURL(url);
+
+    // If this is a LinkForty URL and we have a resolver, try the server
+    if (localData && this.resolveFn && this.baseUrl && url.startsWith(this.baseUrl)) {
+      try {
+        const resolvedData = await this.resolveURL(url);
+        if (resolvedData) {
+          this.callback(url, resolvedData);
+          return;
+        }
+      } catch (error) {
+        console.warn('[LinkForty] Failed to resolve URL from server, falling back to local parse:', error);
+      }
+    }
+
+    // Fallback to locally-parsed data
+    this.callback(url, localData);
   };
 
   /**
-   * Parse deep link URL and extract data
+   * Resolve a LinkForty URL via the server API.
+   * Extracts the path from the URL, collects fingerprint data for click attribution,
+   * and calls the resolve endpoint.
+   */
+  private async resolveURL(url: string): Promise<DeepLinkData | null> {
+    if (!this.resolveFn) {
+      return null;
+    }
+
+    const parsedUrl = new URL(url);
+    const pathSegments = parsedUrl.pathname.split('/').filter(Boolean);
+
+    if (pathSegments.length === 0) {
+      return null;
+    }
+
+    // Build resolve endpoint path (handles both /shortCode and /templateSlug/shortCode)
+    let resolvePath: string;
+    if (pathSegments.length >= 2) {
+      resolvePath = `/api/sdk/v1/resolve/${pathSegments[0]}/${pathSegments[1]}`;
+    } else {
+      resolvePath = `/api/sdk/v1/resolve/${pathSegments[0]}`;
+    }
+
+    // Collect fingerprint data for click attribution
+    try {
+      const fingerprint = await FingerprintCollector.collect();
+      const [sw, sh] = fingerprint.screenResolution.split('x');
+      const queryParams = new URLSearchParams();
+      queryParams.set('fp_tz', fingerprint.timezone);
+      queryParams.set('fp_lang', fingerprint.language);
+      queryParams.set('fp_sw', sw);
+      queryParams.set('fp_sh', sh);
+      queryParams.set('fp_platform', fingerprint.platform);
+      if (fingerprint.osVersion) {
+        queryParams.set('fp_pv', fingerprint.osVersion);
+      }
+
+      resolvePath += `?${queryParams.toString()}`;
+    } catch (error) {
+      // If fingerprint collection fails, still resolve without it
+      console.warn('[LinkForty] Fingerprint collection failed, resolving without fingerprint:', error);
+    }
+
+    return this.resolveFn(resolvePath);
+  }
+
+  /**
+   * Parse deep link URL and extract data locally (without server call).
+   * Used as fallback when server resolution fails or for non-LinkForty URLs.
    */
   parseURL(url: string): DeepLinkData | null {
     try {
@@ -59,8 +138,9 @@ export class DeepLinkHandler {
         return null;
       }
 
-      // Extract short code from path
-      const shortCode = parsedUrl.pathname.replace('/', '');
+      // Extract short code from path (last segment handles both /shortCode and /templateSlug/shortCode)
+      const pathSegments = parsedUrl.pathname.split('/').filter(Boolean);
+      const shortCode = pathSegments[pathSegments.length - 1];
 
       if (!shortCode) {
         return null;

package/src/LinkFortySDK.ts

@@ -88,7 +88,9 @@ export class LinkFortySDK {
   }
 
   /**
-   * Register callback for direct deep links (existing users)
+   * Register callback for direct deep links (existing users).
+   * When a LinkForty URL is detected, the SDK will resolve it via the server
+   * to retrieve the full deep link data (custom parameters, UTM params, etc.).
    */
   onDeepLink(callback: DeepLinkCallback): void {
     if (!this.config) {
@@ -99,7 +101,19 @@ export class LinkFortySDK {
       this.deepLinkHandler = new DeepLinkHandler();
     }
 
-    this.deepLinkHandler.initialize(this.config.baseUrl, callback);
+    // Create a resolver that wraps the private apiRequest method
+    const resolveFn = async (path: string): Promise<DeepLinkData | null> => {
+      try {
+        return await this.apiRequest<DeepLinkData>(path);
+      } catch (error) {
+        if (this.config?.debug) {
+          console.log('[LinkForty] URL resolve failed:', error);
+        }
+        return null;
+      }
+    };
+
+    this.deepLinkHandler.initialize(this.config.baseUrl, callback, resolveFn);
   }
 
   /**
@@ -239,14 +253,23 @@ export class LinkFortySDK {
 
       // If attributed, store deep link data
       if (response.attributed && response.deepLinkData) {
+        // Normalize backend response to match DeepLinkData type
+        // Populate customParameters from deepLinkParameters so app developers
+        // get a consistent field regardless of direct vs deferred deep link path
+        const deepLinkData: DeepLinkData = {
+          ...response.deepLinkData as DeepLinkData,
+          customParameters: (response.deepLinkData as any).deepLinkParameters
+            || (response.deepLinkData as DeepLinkData).customParameters,
+        };
+
         await AsyncStorage.setItem(
           STORAGE_KEYS.INSTALL_DATA,
-          JSON.stringify(response.deepLinkData)
+          JSON.stringify(deepLinkData)
         );
 
         // Call deferred deep link callback if registered
         if (this.deferredDeepLinkCallback) {
-          this.deferredDeepLinkCallback(response.deepLinkData as DeepLinkData);
+          this.deferredDeepLinkCallback(deepLinkData);
         }
 
         if (this.config.debug) {

package/src/index.ts

@@ -23,4 +23,5 @@ export type {
   EventData,
   DeferredDeepLinkCallback,
   DeepLinkCallback,
+  ResolveFunction,
 } from './types';

package/src/types.ts

@@ -60,8 +60,12 @@ export interface DeepLinkData {
     term?: string;
     content?: string;
   };
-  /** Custom query parameters */
+  /** Custom parameters (from URL query params on direct links, or from link configuration on deferred links) */
   customParameters?: Record<string, string>;
+  /** In-app destination path (e.g., '/video/123') */
+  deepLinkPath?: string;
+  /** Custom URI scheme (e.g., 'myapp') */
+  appScheme?: string;
   /** Click timestamp */
   clickedAt?: string;
   /** Link ID */
@@ -110,3 +114,10 @@ export type DeferredDeepLinkCallback = (deepLinkData: DeepLinkData | null) => vo
  * Callback function for direct deep links
  */
 export type DeepLinkCallback = (url: string, deepLinkData: DeepLinkData | null) => void;
+
+/**
+ * Function that resolves a LinkForty URL path to deep link data via the server.
+ * Used internally by DeepLinkHandler when the OS intercepts a LinkForty URL
+ * before the server can process the redirect.
+ */
+export type ResolveFunction = (path: string) => Promise<DeepLinkData | null>;