@linkforty/mobile-sdk-react-native 1.1.2 → 1.1.4

package/CHANGELOG.md

@@ -7,6 +7,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.1.3] - 2026-02-12
+### Fixed
+- Replaced `new URL()` and `URLSearchParams` usage with manual string parsing — `URL.pathname` is not implemented in React Native's Hermes engine, which caused `parseURL()` to crash silently and skip server-side deep link resolution entirely
+- Rounded screen dimensions to integers in `FingerprintCollector` — Android's `Dimensions.get('window')` returns floats (e.g. `434.717`) which caused PostgreSQL INSERT errors on INTEGER columns in the install endpoint
+
 ## [1.1.2] - 2026-02-12
 ### Added
 - `createLink()` method for creating short links programmatically from mobile apps via the LinkForty API

package/README.md

@@ -4,20 +4,19 @@ Official React Native SDK for [LinkForty](https://github.com/linkforty/core) - O
 
 ## Features
 
-- ✅ **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
+- **Direct Deep Linking** - Handle Universal Links (iOS) and App Links (Android) with automatic server-side resolution
+- **Deferred Deep Linking** - Route new users to specific content after install
+- **Link Creation** - Create short links programmatically from your app
+- **Probabilistic Attribution** - Match installs to clicks via device fingerprinting
+- **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
 
 ## Installation
 
 ```bash
-npm i @linkforty/mobile-sdk-react-native
-# or
-yarn add @linkforty/mobile-sdk-react-native
+npm install @linkforty/mobile-sdk-react-native
 ```
 
 ### Requirements
@@ -26,9 +25,7 @@ yarn add @linkforty/mobile-sdk-react-native
 - React >= 17.0.0
 - Node.js >= 20.0.0
 
-### Additional Dependencies
-
-This SDK requires the following peer dependencies:
+### Peer Dependencies
 
 ```bash
 npm install @react-native-async-storage/async-storage react-native-device-info
@@ -44,16 +41,15 @@ cd ios && pod install
 
 2. Configure Universal Links in Xcode:
    - Open your project in Xcode
-   - Select your app target → Signing & Capabilities
+   - Select your app target > Signing & Capabilities
    - Add "Associated Domains" capability
-   - Add domain: `applinks:go.yourdomain.com` (replace with your LinkForty or custom domain)
+   - Add domain: `applinks:go.yourdomain.com` (replace with your LinkForty domain)
 
-3. Create AASA file on your server at:
+3. Host an Apple App Site Association (AASA) file at:
    ```
    https://go.yourdomain.com/.well-known/apple-app-site-association
    ```
 
-   Example AASA file:
    ```json
    {
      "applinks": {
@@ -70,7 +66,7 @@ cd ios && pod install
 
 ### Android Setup
 
-1. Configure App Links in `android/app/src/main/AndroidManifest.xml`:
+1. Add an App Links intent filter in `android/app/src/main/AndroidManifest.xml`:
 
 ```xml
 <activity android:name=".MainActivity">
@@ -84,12 +80,11 @@ cd ios && pod install
 </activity>
 ```
 
-2. Create Digital Asset Links file on your server at:
+2. Host a Digital Asset Links file at:
    ```
    https://go.yourdomain.com/.well-known/assetlinks.json
    ```
 
-   Example assetlinks.json:
    ```json
    [{
      "relation": ["delegate_permission/common.handle_all_urls"],
@@ -101,187 +96,223 @@ cd ios && pod install
    }]
    ```
 
+3. Ensure `MainActivity` preserves the Intent for React Native. In `MainActivity.kt`:
+
+```kotlin
+override fun onNewIntent(intent: Intent) {
+    setIntent(intent) // Required for React Native's Linking.getInitialURL()
+    super.onNewIntent(intent)
+}
+```
+
+> **Note:** If you use other SDKs that consume Intent data (e.g., CleverTap), make sure they receive a **copy** of the URI in `onCreate` rather than consuming the original Intent, otherwise `Linking.getInitialURL()` may return `null`.
+
 ## Quick Start
 
 ```typescript
 import LinkForty from '@linkforty/mobile-sdk-react-native';
 
-// Initialize SDK (call in App.tsx or index.js)
+// 1. Initialize the SDK (call once at app startup)
 await LinkForty.init({
   baseUrl: 'https://go.yourdomain.com',
-  apiKey: 'optional-for-cloud-users', // Optional
-  debug: __DEV__, // Enable debug logging in development
+  apiKey: 'your-api-key', // Required for createLink(), optional otherwise
+  debug: __DEV__,
 });
 
-// Handle deferred deep links (new installs)
-LinkForty.onDeferredDeepLink((deepLinkData) => {
-  if (deepLinkData) {
-    // User clicked a link before installing
-    console.log('Deferred deep link:', deepLinkData);
+// 2. Handle direct deep links (user taps a link while app is installed)
+LinkForty.onDeepLink((url, data) => {
+  if (data?.customParameters) {
+    const { route, id } = data.customParameters;
+    // Navigate to the target screen
+    navigation.navigate(route, { id });
+  }
+});
 
-    // Navigate to specific content
-    navigation.navigate('Product', {
-      id: deepLinkData.utmParameters?.content
-    });
+// 3. Handle deferred deep links (user installs app after tapping a link)
+LinkForty.onDeferredDeepLink((data) => {
+  if (data?.customParameters) {
+    const { route, id } = data.customParameters;
+    navigation.navigate(route, { id });
   } else {
-    // Organic install (no link clicked)
-    console.log('Organic install');
+    console.log('Organic install — no link clicked');
   }
 });
+```
 
-// Handle direct deep links (existing users)
-LinkForty.onDeepLink((url, deepLinkData) => {
-  console.log('Deep link opened:', url, deepLinkData);
+## API Reference
 
-  if (deepLinkData) {
-    // Navigate to specific content
-    navigation.navigate('Product', {
-      id: deepLinkData.utmParameters?.content
-    });
-  }
-});
+### `init(config)`
 
-// Track in-app events
-await LinkForty.trackEvent('purchase', {
-  amount: 99.99,
-  currency: 'USD',
-  productId: 'premium_plan'
+Initialize the SDK. Must be called before any other method.
+
+```typescript
+await LinkForty.init({
+  baseUrl: 'https://go.yourdomain.com', // Required
+  apiKey: 'your-api-key',               // Optional (required for createLink)
+  debug: true,                           // Optional (default: false)
+  attributionWindow: 7,                  // Optional, in days (default: 7)
 });
 ```
 
-## API Reference
-
-### `init(config: LinkFortyConfig): Promise<void>`
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `baseUrl` | `string` | Yes | Base URL of your LinkForty instance |
+| `apiKey` | `string` | No | API key for authenticated endpoints (Cloud) |
+| `debug` | `boolean` | No | Enable debug logging |
+| `attributionWindow` | `number` | No | Attribution window in days (default: 7) |
 
-Initialize the SDK. Must be called before using any other methods.
+---
 
-**Parameters:**
+### `onDeepLink(callback)`
 
-- `config.baseUrl` (string, required) - Base URL of your LinkForty instance
-- `config.apiKey` (string, optional) - API key for Cloud authentication
-- `config.debug` (boolean, optional) - Enable debug logging
-- `config.attributionWindow` (number, optional) - Attribution window in days (default: 7)
+Listen for direct deep links. Called when the app is opened via a Universal Link (iOS) or App Link (Android).
 
-**Example:**
+When the URL matches your LinkForty `baseUrl`, the SDK automatically resolves it via the server to retrieve the full link data including `customParameters`, UTM parameters, and metadata. If resolution fails, the SDK falls back to local URL parsing.
 
 ```typescript
-await LinkForty.init({
-  baseUrl: 'https://go.yourdomain.com',
-  debug: true,
-  attributionWindow: 7,
+LinkForty.onDeepLink((url: string, data: DeepLinkData | null) => {
+  console.log('Link URL:', url);
+
+  if (data?.customParameters) {
+    const { route, id } = data.customParameters;
+    navigation.navigate(route, { id });
+  }
 });
 ```
 
-### `onDeferredDeepLink(callback: (deepLinkData: DeepLinkData | null) => void): void`
+| Callback Parameter | Type | Description |
+|--------------------|------|-------------|
+| `url` | `string` | The full URL that opened the app |
+| `data` | `DeepLinkData \| null` | Parsed link data, or `null` if parsing failed |
 
-Register a callback for deferred deep links. Called when the app is launched for the first time after installation.
-
-**Parameters:**
+---
 
-- `callback` - Function called with deep link data or `null` for organic installs
+### `onDeferredDeepLink(callback)`
 
-**Example:**
+Listen for deferred deep links. Called on first launch after install if the user clicked a LinkForty link before installing.
 
 ```typescript
-LinkForty.onDeferredDeepLink((deepLinkData) => {
-  if (deepLinkData) {
-    // Attributed install
-    console.log('User came from:', deepLinkData.utmParameters?.source);
+LinkForty.onDeferredDeepLink((data: DeepLinkData | null) => {
+  if (data) {
+    // Attributed install — user clicked a link before installing
+    console.log('Came from:', data.utmParameters?.source);
+    const { route, id } = data.customParameters || {};
+    if (route) navigation.navigate(route, { id });
   } else {
-    // Organic install
+    // Organic install or attribution failed
     console.log('Organic install');
   }
 });
 ```
 
-### `onDeepLink(callback: (url: string, deepLinkData: DeepLinkData | null) => void): void`
+| Callback Parameter | Type | Description |
+|--------------------|------|-------------|
+| `data` | `DeepLinkData \| null` | Attributed link data, or `null` for organic installs |
 
-Register a callback for direct deep links. Called when the app is opened via a Universal Link (iOS) or App Link (Android).
+---
 
-**Parameters:**
+### `createLink(options)`
 
-- `callback` - Function called with the full URL and parsed deep link data
+Create a short link programmatically. Requires `apiKey` to be set in `init()`.
 
-**Example:**
+When `templateId` is omitted, the server auto-selects your organization's default template.
 
 ```typescript
-LinkForty.onDeepLink((url, deepLinkData) => {
-  if (deepLinkData?.shortCode) {
-    // Navigate based on link
-    navigation.navigate('Details', { id: deepLinkData.shortCode });
-  }
+const result = await LinkForty.createLink({
+  deepLinkParameters: { route: 'VIDEO_VIEWER', id: 'e4338ed6-...' },
+  title: 'Check out this video',
+  utmParameters: { source: 'share', medium: 'app' },
 });
+
+console.log(result.url);       // https://go.yourdomain.com/tmpl/abc123
+console.log(result.shortCode); // abc123
+console.log(result.linkId);    // uuid
 ```
 
-### `trackEvent(name: string, properties?: Record<string, any>): Promise<void>`
+**Options:**
 
-Track an in-app event with optional properties.
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `deepLinkParameters` | `Record<string, string>` | No | Custom parameters embedded in the link (e.g., `{ route, id }`) |
+| `title` | `string` | No | Link title for internal reference |
+| `description` | `string` | No | Link description |
+| `customCode` | `string` | No | Custom short code (auto-generated if omitted) |
+| `utmParameters` | `object` | No | UTM parameters (`source`, `medium`, `campaign`, `term`, `content`) |
+| `templateId` | `string` | No | Template UUID (auto-selected if omitted) |
+| `templateSlug` | `string` | No | Template slug (only needed with `templateId`) |
 
-**Parameters:**
+**Returns:** `CreateLinkResult`
 
-- `name` - Event name (e.g., 'purchase', 'signup', 'add_to_cart')
-- `properties` - Optional event properties
+| Field | Type | Description |
+|-------|------|-------------|
+| `url` | `string` | Full shareable URL |
+| `shortCode` | `string` | The generated short code |
+| `linkId` | `string` | Link UUID |
 
-**Example:**
+---
+
+### `trackEvent(name, properties?)`
+
+Track an in-app event for attribution analytics. Requires a successful install report (automatic on first launch).
 
 ```typescript
 await LinkForty.trackEvent('purchase', {
   amount: 99.99,
   currency: 'USD',
   productId: 'premium_plan',
-  category: 'subscription'
 });
 ```
 
-### `getInstallData(): Promise<DeepLinkData | null>`
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `name` | `string` | Yes | Event name (e.g., `'purchase'`, `'signup'`) |
+| `properties` | `Record<string, any>` | No | Arbitrary event properties |
 
-Get cached install attribution data.
+---
 
-**Returns:** Deep link data from install or `null` if not attributed
+### `getInstallData()`
 
-**Example:**
+Retrieve cached install attribution data from a previous deferred deep link.
 
 ```typescript
-const installData = await LinkForty.getInstallData();
-if (installData) {
-  console.log('Install source:', installData.utmParameters?.source);
+const data = await LinkForty.getInstallData();
+if (data) {
+  console.log('Install attributed to:', data.utmParameters?.source);
 }
 ```
 
-### `getInstallId(): Promise<string | null>`
+**Returns:** `DeepLinkData | null`
 
-Get the unique install ID for this app installation.
+---
 
-**Returns:** Install ID or `null` if not available
+### `getInstallId()`
 
-**Example:**
+Get the unique install ID assigned by the LinkForty server on first launch.
 
 ```typescript
 const installId = await LinkForty.getInstallId();
-console.log('Install ID:', installId);
 ```
 
-### `clearData(): Promise<void>`
+**Returns:** `string | null`
 
-Clear all cached SDK data. Useful for testing.
+---
+
+### `clearData()`
 
-**Example:**
+Clear all cached SDK data (install ID, attribution data, first-launch flag). The next app launch will behave as a fresh install.
 
 ```typescript
 await LinkForty.clearData();
-// App will behave as if it's a fresh install
 ```
 
-## TypeScript Types
+## Types
 
 ### `DeepLinkData`
 
 ```typescript
 interface DeepLinkData {
   shortCode: string;
-  iosUrl?: string;
-  androidUrl?: string;
-  webUrl?: string;
+  customParameters?: Record<string, string>;
   utmParameters?: {
     source?: string;
     medium?: string;
@@ -289,7 +320,11 @@ interface DeepLinkData {
     term?: string;
     content?: string;
   };
-  customParameters?: Record<string, string>;
+  iosUrl?: string;
+  androidUrl?: string;
+  webUrl?: string;
+  deepLinkPath?: string;
+  appScheme?: string;
   clickedAt?: string;
   linkId?: string;
 }
@@ -306,79 +341,94 @@ interface LinkFortyConfig {
 }
 ```
 
-## Advanced Usage
+### `CreateLinkOptions`
 
-### Testing Deferred Deep Linking
+```typescript
+interface CreateLinkOptions {
+  templateId?: string;
+  templateSlug?: string;
+  deepLinkParameters?: Record<string, string>;
+  title?: string;
+  description?: string;
+  customCode?: string;
+  utmParameters?: {
+    source?: string;
+    medium?: string;
+    campaign?: string;
+    term?: string;
+    content?: string;
+  };
+}
+```
 
-1. **Uninstall the app** or clear all data:
-   ```typescript
-   await LinkForty.clearData();
-   ```
+### `CreateLinkResult`
 
-2. **Click a LinkForty link** on your device (in Safari/Chrome, not in the app)
+```typescript
+interface CreateLinkResult {
+  url: string;
+  shortCode: string;
+  linkId: string;
+}
+```
 
-3. **Install/Open the app** from App Store/Play Store
+## How Deep Linking Works
 
-4. **Check logs** - you should see attribution data in the `onDeferredDeepLink` callback
+### Direct Deep Links (App Installed)
 
-### Using with Self-Hosted LinkForty Core
+When a user taps a LinkForty URL and the app is already installed:
 
-```typescript
-// Point to your self-hosted instance
-await LinkForty.init({
-  baseUrl: 'http://localhost:3000', // or your domain
-  debug: true,
-});
-```
+1. The OS intercepts the URL via App Links (Android) or Universal Links (iOS) and opens your app directly
+2. The SDK receives the URL via React Native's `Linking` API
+3. The SDK calls your LinkForty server's resolve endpoint to retrieve the full link data (`customParameters`, UTM params, etc.)
+4. Your `onDeepLink` callback fires with the resolved data
+5. Your app navigates to the target screen
 
-### Using with LinkForty Cloud
-
-```typescript
-// Add API key for Cloud authentication
-await LinkForty.init({
-  baseUrl: 'https://go.yourdomain.com',
-  apiKey: 'your-api-key-here',
-  debug: false,
-});
-```
+### Deferred Deep Links (App Not Installed)
 
-### Custom Attribution Window
+When a user taps a LinkForty URL and the app is **not** installed:
 
-```typescript
-// Change attribution window to 14 days
-await LinkForty.init({
-  baseUrl: 'https://go.yourdomain.com',
-  attributionWindow: 14, // days
-});
-```
+1. The LinkForty server records a click with the user's device fingerprint
+2. The user is redirected to the App Store / Play Store
+3. After installing and opening the app, the SDK reports the install with the device's fingerprint
+4. The server matches the fingerprint to the original click (probabilistic attribution)
+5. Your `onDeferredDeepLink` callback fires with the matched link data
+6. Your app navigates to the content the user originally clicked on
 
 ## Troubleshooting
 
 ### Deep links not working on iOS
 
-1. Verify your AASA file is accessible at `https://go.yourdomain.com/.well-known/apple-app-site-association`
-2. Check that your Team ID and Bundle ID are correct
-3. Make sure "Associated Domains" capability is added in Xcode
-4. Test with a real device (Universal Links don't work in simulator)
+1. Verify AASA file is accessible at `https://yourdomain.com/.well-known/apple-app-site-association`
+2. Check that Team ID and Bundle ID are correct in the AASA file
+3. Confirm "Associated Domains" capability is added in Xcode with `applinks:yourdomain.com`
+4. Test on a real device (Universal Links don't work in the simulator)
 
 ### Deep links not working on Android
 
-1. Verify your assetlinks.json file is accessible at `https://go.yourdomain.com/.well-known/assetlinks.json`
-2. Check that your package name and SHA256 fingerprint are correct
-3. Run `adb shell pm get-app-links com.yourapp` to verify link verification status
-4. Make sure `android:autoVerify="true"` is set in your intent filter
+1. Verify assetlinks.json is accessible at `https://yourdomain.com/.well-known/assetlinks.json`
+2. Check package name and SHA256 fingerprint are correct
+3. Run `adb shell pm get-app-links com.yourapp` to check link verification status
+4. Confirm `android:autoVerify="true"` is set in your intent filter
+5. Ensure `MainActivity` calls `setIntent(intent)` in `onNewIntent` (see [Android Setup](#android-setup))
+
+### `getInitialURL()` returns null on Android
+
+This usually means another SDK or library is consuming the Intent data before React Native reads it. In `MainActivity.kt`:
+
+- Call `setIntent(intent)` in `onNewIntent` so React Native sees the updated Intent on warm starts
+- If using CleverTap or similar SDKs, pass a **copy** of the URI to them in `onCreate` rather than the original Intent data
 
 ### Deferred deep links not attributing
 
-1. Make sure you're testing on first install (or call `clearData()`)
-2. Check debug logs for fingerprint data
-3. Verify your LinkForty backend is receiving the install event
+1. Confirm this is a first install (or call `clearData()` first)
+2. Enable `debug: true` and check logs for fingerprint data
+3. Verify your LinkForty server received the install event
 4. Ensure the click and install happen within the attribution window (default: 7 days)
-5. Try clicking the link and installing from the same network
+5. Test on the same network for best fingerprint match accuracy
 
 ### TypeScript errors
 
-Make sure you have the latest type definitions installed:
+Ensure peer dependencies are installed:
 
 ```bash
 npm install --save-dev @types/react @types/react-native
@@ -386,25 +436,18 @@ npm install --save-dev @types/react @types/react-native
 
 ## Contributing
 
-Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
 
 ## License
 
-MIT License - see [LICENSE](LICENSE) file for details
+MIT License - see [LICENSE](LICENSE) for details.
 
 ## Support
 
-- **Documentation:** Coming soon (self-hosting guide available in Core repository)
-- **Issues:** [Report on GitHub](https://github.com/linkforty/react-native-sdk/issues)
-- **Questions:** Open a GitHub Discussion or Issue
+- **Issues:** [GitHub Issues](https://github.com/linkforty/react-native-sdk/issues)
+- **Documentation:** [LinkForty Core](https://github.com/linkforty/core)
 
 ## Related Projects
 
 - [LinkForty Cloud](https://linkforty.com) - Cloud platform with dashboard and API
 - [LinkForty Core](https://github.com/linkforty/core) - Self-hosted open-source backend
-- **iOS SDK** - Native Swift SDK (planned for future release)
-- **Android SDK** - Native Kotlin SDK (planned for future release)
-
----
-
-Made with ❤️ by the LinkForty team

package/dist/DeepLinkHandler.d.ts

@@ -12,6 +12,16 @@ export declare class DeepLinkHandler {
     private callback;
     private baseUrl;
     private resolveFn;
+    /**
+     * Parse a URL string manually.
+     * The URL/URLSearchParams APIs are not fully implemented in React Native's Hermes engine
+     * (URL.pathname throws "not implemented"), so we parse with basic string operations.
+     */
+    private static parseUrlString;
+    /**
+     * Build a query string from key-value pairs without URLSearchParams.
+     */
+    private static buildQueryString;
     /**
      * Initialize deep link listener
      * @param baseUrl - LinkForty instance base URL for detecting LinkForty URLs

package/dist/DeepLinkHandler.d.ts.map

@@ -1 +1 @@
-{"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"}
+{"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;;;;OAIG;IACH,OAAO,CAAC,MAAM,CAAC,cAAc;IAsC7B;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,gBAAgB;IAM/B;;;;;OAKG;IACH,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,gBAAgB,EAAE,SAAS,CAAC,EAAE,eAAe,GAAG,IAAI;IAqB1F;;OAEG;IACH,OAAO,IAAI,IAAI;IAKf;;;;OAIG;IACH,OAAO,CAAC,cAAc,CAiCpB;IAEF;;;;OAIG;YACW,UAAU;IAgDxB;;;OAGG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI;CA+C3C"}

package/dist/DeepLinkHandler.js

@@ -13,6 +13,51 @@ export class DeepLinkHandler {
     callback = null;
     baseUrl = null;
     resolveFn = null;
+    /**
+     * Parse a URL string manually.
+     * The URL/URLSearchParams APIs are not fully implemented in React Native's Hermes engine
+     * (URL.pathname throws "not implemented"), so we parse with basic string operations.
+     */
+    static parseUrlString(url) {
+        try {
+            const protocolEnd = url.indexOf('://');
+            if (protocolEnd === -1)
+                return null;
+            const afterProtocol = url.substring(protocolEnd + 3);
+            const pathStart = afterProtocol.indexOf('/');
+            const pathAndQuery = pathStart === -1 ? '/' : afterProtocol.substring(pathStart);
+            const hashIndex = pathAndQuery.indexOf('#');
+            const withoutHash = hashIndex === -1 ? pathAndQuery : pathAndQuery.substring(0, hashIndex);
+            const queryStart = withoutHash.indexOf('?');
+            const pathname = queryStart === -1 ? withoutHash : withoutHash.substring(0, queryStart);
+            const queryString = queryStart === -1 ? '' : withoutHash.substring(queryStart + 1);
+            const searchParams = new Map();
+            if (queryString) {
+                for (const pair of queryString.split('&')) {
+                    const eqIndex = pair.indexOf('=');
+                    if (eqIndex === -1) {
+                        searchParams.set(decodeURIComponent(pair), '');
+                    }
+                    else {
+                        searchParams.set(decodeURIComponent(pair.substring(0, eqIndex)), decodeURIComponent(pair.substring(eqIndex + 1)));
+                    }
+                }
+            }
+            return { pathname, searchParams };
+        }
+        catch (error) {
+            console.error('[LinkForty] Failed to parse URL string:', error);
+            return null;
+        }
+    }
+    /**
+     * Build a query string from key-value pairs without URLSearchParams.
+     */
+    static buildQueryString(params) {
+        return Object.entries(params)
+            .map(([key, value]) => `${encodeURIComponent(key)}=${encodeURIComponent(value)}`)
+            .join('&');
+    }
     /**
      * Initialize deep link listener
      * @param baseUrl - LinkForty instance base URL for detecting LinkForty URLs
@@ -23,13 +68,18 @@ export class DeepLinkHandler {
         this.baseUrl = baseUrl;
         this.callback = callback;
         this.resolveFn = resolveFn || null;
+        console.log('[LinkForty] DeepLinkHandler.initialize: baseUrl=', baseUrl, 'hasResolveFn=', !!resolveFn);
         // Listen for deep links when app is already open
         Linking.addEventListener('url', this.handleDeepLink);
         // Check if app was opened via deep link
         Linking.getInitialURL().then((url) => {
+            console.log('[LinkForty] getInitialURL result:', url);
             if (url) {
                 this.handleDeepLink({ url });
             }
+            else {
+                console.warn('[LinkForty] getInitialURL returned null — app may not have been opened via deep link, or Android consumed the Intent');
+            }
         });
     }
     /**
@@ -45,25 +95,35 @@ export class DeepLinkHandler {
      * Falls back to local URL parsing on failure.
      */
     handleDeepLink = async ({ url }) => {
+        console.log('[LinkForty] handleDeepLink called with url:', url);
         if (!this.callback || !url) {
+            console.warn('[LinkForty] handleDeepLink early return: callback=', !!this.callback, 'url=', url);
             return;
         }
         // Parse locally first (for fallback and to detect LinkForty URLs)
         const localData = this.parseURL(url);
+        console.log('[LinkForty] localData parsed:', JSON.stringify(localData));
         // 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 {
+                console.log('[LinkForty] Resolving URL via server...');
                 const resolvedData = await this.resolveURL(url);
+                console.log('[LinkForty] Resolve result:', JSON.stringify(resolvedData));
                 if (resolvedData) {
                     this.callback(url, resolvedData);
                     return;
                 }
+                console.warn('[LinkForty] Resolve returned null, falling back to local parse');
             }
             catch (error) {
                 console.warn('[LinkForty] Failed to resolve URL from server, falling back to local parse:', error);
             }
         }
-        // Fallback to locally-parsed data
+        else {
+            console.warn('[LinkForty] Skipping server resolve: localData=', !!localData, 'resolveFn=', !!this.resolveFn, 'baseUrl=', this.baseUrl, 'urlMatch=', url.startsWith(this.baseUrl || ''));
+        }
+        // Fallback to locally-parsed data (no customParameters from server)
+        console.warn('[LinkForty] Using local fallback — customParameters will be empty for App Link URLs');
         this.callback(url, localData);
     };
     /**
@@ -75,8 +135,11 @@ export class DeepLinkHandler {
         if (!this.resolveFn) {
             return null;
         }
-        const parsedUrl = new URL(url);
-        const pathSegments = parsedUrl.pathname.split('/').filter(Boolean);
+        const parsed = DeepLinkHandler.parseUrlString(url);
+        if (!parsed) {
+            return null;
+        }
+        const pathSegments = parsed.pathname.split('/').filter(Boolean);
         if (pathSegments.length === 0) {
             return null;
         }
@@ -92,16 +155,17 @@ export class DeepLinkHandler {
         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);
+            const fpParams = {
+                fp_tz: fingerprint.timezone,
+                fp_lang: fingerprint.language,
+                fp_sw: sw,
+                fp_sh: sh,
+                fp_platform: fingerprint.platform,
+            };
             if (fingerprint.osVersion) {
-                queryParams.set('fp_pv', fingerprint.osVersion);
+                fpParams.fp_pv = fingerprint.osVersion;
             }
-            resolvePath += `?${queryParams.toString()}`;
+            resolvePath += `?${DeepLinkHandler.buildQueryString(fpParams)}`;
         }
         catch (error) {
             // If fingerprint collection fails, still resolve without it
@@ -115,28 +179,31 @@ export class DeepLinkHandler {
      */
     parseURL(url) {
         try {
-            const parsedUrl = new URL(url);
             // Check if this is a LinkForty URL
             if (this.baseUrl && !url.startsWith(this.baseUrl)) {
                 return null;
             }
+            const parsed = DeepLinkHandler.parseUrlString(url);
+            if (!parsed) {
+                return null;
+            }
             // Extract short code from path (last segment handles both /shortCode and /templateSlug/shortCode)
-            const pathSegments = parsedUrl.pathname.split('/').filter(Boolean);
+            const pathSegments = parsed.pathname.split('/').filter(Boolean);
             const shortCode = pathSegments[pathSegments.length - 1];
             if (!shortCode) {
                 return null;
             }
             // Extract UTM parameters
             const utmParameters = {
-                source: parsedUrl.searchParams.get('utm_source') || undefined,
-                medium: parsedUrl.searchParams.get('utm_medium') || undefined,
-                campaign: parsedUrl.searchParams.get('utm_campaign') || undefined,
-                term: parsedUrl.searchParams.get('utm_term') || undefined,
-                content: parsedUrl.searchParams.get('utm_content') || undefined,
+                source: parsed.searchParams.get('utm_source') || undefined,
+                medium: parsed.searchParams.get('utm_medium') || undefined,
+                campaign: parsed.searchParams.get('utm_campaign') || undefined,
+                term: parsed.searchParams.get('utm_term') || undefined,
+                content: parsed.searchParams.get('utm_content') || undefined,
             };
             // Extract all other query parameters as custom parameters
             const customParameters = {};
-            parsedUrl.searchParams.forEach((value, key) => {
+            parsed.searchParams.forEach((value, key) => {
                 if (!key.startsWith('utm_')) {
                     customParameters[key] = value;
                 }

package/dist/FingerprintCollector.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"FingerprintCollector.d.ts","sourceRoot":"","sources":["../src/FingerprintCollector.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAEjD,qBAAa,oBAAoB;IAC/B;;OAEG;WACU,OAAO,IAAI,OAAO,CAAC,iBAAiB,CAAC;IAmBlD;;OAEG;WACU,mBAAmB,IAAI,OAAO,CAAC,MAAM,CAAC;IAiBnD;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,WAAW;IAS1B;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,WAAW;CAuB3B"}
+{"version":3,"file":"FingerprintCollector.d.ts","sourceRoot":"","sources":["../src/FingerprintCollector.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAEjD,qBAAa,oBAAoB;IAC/B;;OAEG;WACU,OAAO,IAAI,OAAO,CAAC,iBAAiB,CAAC;IAoBlD;;OAEG;WACU,mBAAmB,IAAI,OAAO,CAAC,MAAM,CAAC;IAoBnD;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,WAAW;IAS1B;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,WAAW;CAuB3B"}

package/dist/FingerprintCollector.js

@@ -11,11 +11,12 @@ export class FingerprintCollector {
         const { width, height } = Dimensions.get('window');
         const timezone = this.getTimezone();
         const language = this.getLanguage();
+        // Round dimensions — Android returns floats (e.g. 434.717) but the server expects integers
         const fingerprint = {
             userAgent: await DeviceInfo.getUserAgent(),
             timezone,
             language,
-            screenResolution: `${width}x${height}`,
+            screenResolution: `${Math.round(width)}x${Math.round(height)}`,
             platform: Platform.OS,
             deviceModel: await DeviceInfo.getModel(),
             osVersion: await DeviceInfo.getSystemVersion(),
@@ -28,17 +29,23 @@ export class FingerprintCollector {
      */
     static async generateQueryParams() {
         const fingerprint = await this.collect();
-        const params = new URLSearchParams({
+        // Build query string manually — URLSearchParams is not reliable in Hermes
+        const params = {
             ua: fingerprint.userAgent,
             tz: fingerprint.timezone,
             lang: fingerprint.language,
             screen: fingerprint.screenResolution,
             platform: fingerprint.platform,
-            ...(fingerprint.deviceModel && { model: fingerprint.deviceModel }),
-            ...(fingerprint.osVersion && { os: fingerprint.osVersion }),
-            ...(fingerprint.appVersion && { app_version: fingerprint.appVersion }),
-        });
-        return params.toString();
+        };
+        if (fingerprint.deviceModel)
+            params.model = fingerprint.deviceModel;
+        if (fingerprint.osVersion)
+            params.os = fingerprint.osVersion;
+        if (fingerprint.appVersion)
+            params.app_version = fingerprint.appVersion;
+        return Object.entries(params)
+            .map(([key, value]) => `${encodeURIComponent(key)}=${encodeURIComponent(value)}`)
+            .join('&');
     }
     /**
      * Get device timezone

package/dist/LinkFortySDK.js

@@ -255,7 +255,7 @@ export class LinkFortySDK {
             // Parse screen resolution (e.g., "1080x1920" -> [1080, 1920])
             const [screenWidth, screenHeight] = fingerprint.screenResolution
                 .split('x')
-                .map(Number);
+                .map((v) => Math.round(Number(v)));
             // Convert attribution window from days to hours
             const attributionWindowHours = (this.config.attributionWindow || 7) * 24;
             // Call install endpoint with flattened structure matching backend contract

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@linkforty/mobile-sdk-react-native",
-  "version": "1.1.2",
+  "version": "1.1.4",
   "description": "React Native SDK for LinkForty - Open-source deep linking and mobile attribution platform",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -45,6 +45,7 @@
     "react-native": ">=0.64.0"
   },
   "dependencies": {
+    "@linkforty/mobile-sdk-react-native": "file:linkforty-mobile-sdk-react-native-1.1.2.tgz",
     "@react-native-async-storage/async-storage": "^2.2.0",
     "react-native-device-info": "^15.0.0"
   },

package/src/DeepLinkHandler.ts

@@ -17,6 +17,58 @@ export class DeepLinkHandler {
   private baseUrl: string | null = null;
   private resolveFn: ResolveFunction | null = null;
 
+  /**
+   * Parse a URL string manually.
+   * The URL/URLSearchParams APIs are not fully implemented in React Native's Hermes engine
+   * (URL.pathname throws "not implemented"), so we parse with basic string operations.
+   */
+  private static parseUrlString(url: string): { pathname: string; searchParams: Map<string, string> } | null {
+    try {
+      const protocolEnd = url.indexOf('://');
+      if (protocolEnd === -1) return null;
+
+      const afterProtocol = url.substring(protocolEnd + 3);
+      const pathStart = afterProtocol.indexOf('/');
+      const pathAndQuery = pathStart === -1 ? '/' : afterProtocol.substring(pathStart);
+
+      const hashIndex = pathAndQuery.indexOf('#');
+      const withoutHash = hashIndex === -1 ? pathAndQuery : pathAndQuery.substring(0, hashIndex);
+
+      const queryStart = withoutHash.indexOf('?');
+      const pathname = queryStart === -1 ? withoutHash : withoutHash.substring(0, queryStart);
+      const queryString = queryStart === -1 ? '' : withoutHash.substring(queryStart + 1);
+
+      const searchParams = new Map<string, string>();
+      if (queryString) {
+        for (const pair of queryString.split('&')) {
+          const eqIndex = pair.indexOf('=');
+          if (eqIndex === -1) {
+            searchParams.set(decodeURIComponent(pair), '');
+          } else {
+            searchParams.set(
+              decodeURIComponent(pair.substring(0, eqIndex)),
+              decodeURIComponent(pair.substring(eqIndex + 1)),
+            );
+          }
+        }
+      }
+
+      return { pathname, searchParams };
+    } catch (error) {
+      console.error('[LinkForty] Failed to parse URL string:', error);
+      return null;
+    }
+  }
+
+  /**
+   * Build a query string from key-value pairs without URLSearchParams.
+   */
+  private static buildQueryString(params: Record<string, string>): string {
+    return Object.entries(params)
+      .map(([key, value]) => `${encodeURIComponent(key)}=${encodeURIComponent(value)}`)
+      .join('&');
+  }
+
   /**
    * Initialize deep link listener
    * @param baseUrl - LinkForty instance base URL for detecting LinkForty URLs
@@ -28,13 +80,18 @@ export class DeepLinkHandler {
     this.callback = callback;
     this.resolveFn = resolveFn || null;
 
+    console.log('[LinkForty] DeepLinkHandler.initialize: baseUrl=', baseUrl, 'hasResolveFn=', !!resolveFn);
+
     // Listen for deep links when app is already open
     Linking.addEventListener('url', this.handleDeepLink);
 
     // Check if app was opened via deep link
     Linking.getInitialURL().then((url) => {
+      console.log('[LinkForty] getInitialURL result:', url);
       if (url) {
         this.handleDeepLink({ url });
+      } else {
+        console.warn('[LinkForty] getInitialURL returned null — app may not have been opened via deep link, or Android consumed the Intent');
       }
     });
   }
@@ -53,27 +110,37 @@ export class DeepLinkHandler {
    * Falls back to local URL parsing on failure.
    */
   private handleDeepLink = async ({ url }: { url: string }): Promise<void> => {
+    console.log('[LinkForty] handleDeepLink called with url:', url);
+
     if (!this.callback || !url) {
+      console.warn('[LinkForty] handleDeepLink early return: callback=', !!this.callback, 'url=', url);
       return;
     }
 
     // Parse locally first (for fallback and to detect LinkForty URLs)
     const localData = this.parseURL(url);
+    console.log('[LinkForty] localData parsed:', JSON.stringify(localData));
 
     // 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 {
+        console.log('[LinkForty] Resolving URL via server...');
         const resolvedData = await this.resolveURL(url);
+        console.log('[LinkForty] Resolve result:', JSON.stringify(resolvedData));
         if (resolvedData) {
           this.callback(url, resolvedData);
           return;
         }
+        console.warn('[LinkForty] Resolve returned null, falling back to local parse');
       } catch (error) {
         console.warn('[LinkForty] Failed to resolve URL from server, falling back to local parse:', error);
       }
+    } else {
+      console.warn('[LinkForty] Skipping server resolve: localData=', !!localData, 'resolveFn=', !!this.resolveFn, 'baseUrl=', this.baseUrl, 'urlMatch=', url.startsWith(this.baseUrl || ''));
     }
 
-    // Fallback to locally-parsed data
+    // Fallback to locally-parsed data (no customParameters from server)
+    console.warn('[LinkForty] Using local fallback — customParameters will be empty for App Link URLs');
     this.callback(url, localData);
   };
 
@@ -87,8 +154,12 @@ export class DeepLinkHandler {
       return null;
     }
 
-    const parsedUrl = new URL(url);
-    const pathSegments = parsedUrl.pathname.split('/').filter(Boolean);
+    const parsed = DeepLinkHandler.parseUrlString(url);
+    if (!parsed) {
+      return null;
+    }
+
+    const pathSegments = parsed.pathname.split('/').filter(Boolean);
 
     if (pathSegments.length === 0) {
       return null;
@@ -106,17 +177,18 @@ export class DeepLinkHandler {
     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);
+      const fpParams: Record<string, string> = {
+        fp_tz: fingerprint.timezone,
+        fp_lang: fingerprint.language,
+        fp_sw: sw,
+        fp_sh: sh,
+        fp_platform: fingerprint.platform,
+      };
       if (fingerprint.osVersion) {
-        queryParams.set('fp_pv', fingerprint.osVersion);
+        fpParams.fp_pv = fingerprint.osVersion;
       }
 
-      resolvePath += `?${queryParams.toString()}`;
+      resolvePath += `?${DeepLinkHandler.buildQueryString(fpParams)}`;
     } catch (error) {
       // If fingerprint collection fails, still resolve without it
       console.warn('[LinkForty] Fingerprint collection failed, resolving without fingerprint:', error);
@@ -131,15 +203,18 @@ export class DeepLinkHandler {
    */
   parseURL(url: string): DeepLinkData | null {
     try {
-      const parsedUrl = new URL(url);
-
       // Check if this is a LinkForty URL
       if (this.baseUrl && !url.startsWith(this.baseUrl)) {
         return null;
       }
 
+      const parsed = DeepLinkHandler.parseUrlString(url);
+      if (!parsed) {
+        return null;
+      }
+
       // Extract short code from path (last segment handles both /shortCode and /templateSlug/shortCode)
-      const pathSegments = parsedUrl.pathname.split('/').filter(Boolean);
+      const pathSegments = parsed.pathname.split('/').filter(Boolean);
       const shortCode = pathSegments[pathSegments.length - 1];
 
       if (!shortCode) {
@@ -148,16 +223,16 @@ export class DeepLinkHandler {
 
       // Extract UTM parameters
       const utmParameters = {
-        source: parsedUrl.searchParams.get('utm_source') || undefined,
-        medium: parsedUrl.searchParams.get('utm_medium') || undefined,
-        campaign: parsedUrl.searchParams.get('utm_campaign') || undefined,
-        term: parsedUrl.searchParams.get('utm_term') || undefined,
-        content: parsedUrl.searchParams.get('utm_content') || undefined,
+        source: parsed.searchParams.get('utm_source') || undefined,
+        medium: parsed.searchParams.get('utm_medium') || undefined,
+        campaign: parsed.searchParams.get('utm_campaign') || undefined,
+        term: parsed.searchParams.get('utm_term') || undefined,
+        content: parsed.searchParams.get('utm_content') || undefined,
       };
 
       // Extract all other query parameters as custom parameters
       const customParameters: Record<string, string> = {};
-      parsedUrl.searchParams.forEach((value, key) => {
+      parsed.searchParams.forEach((value, key) => {
         if (!key.startsWith('utm_')) {
           customParameters[key] = value;
         }

package/src/FingerprintCollector.ts

@@ -15,11 +15,12 @@ export class FingerprintCollector {
     const timezone = this.getTimezone();
     const language = this.getLanguage();
 
+    // Round dimensions — Android returns floats (e.g. 434.717) but the server expects integers
     const fingerprint: DeviceFingerprint = {
       userAgent: await DeviceInfo.getUserAgent(),
       timezone,
       language,
-      screenResolution: `${width}x${height}`,
+      screenResolution: `${Math.round(width)}x${Math.round(height)}`,
       platform: Platform.OS,
       deviceModel: await DeviceInfo.getModel(),
       osVersion: await DeviceInfo.getSystemVersion(),
@@ -35,18 +36,21 @@ export class FingerprintCollector {
   static async generateQueryParams(): Promise<string> {
     const fingerprint = await this.collect();
 
-    const params = new URLSearchParams({
+    // Build query string manually — URLSearchParams is not reliable in Hermes
+    const params: Record<string, string> = {
       ua: fingerprint.userAgent,
       tz: fingerprint.timezone,
       lang: fingerprint.language,
       screen: fingerprint.screenResolution,
       platform: fingerprint.platform,
-      ...(fingerprint.deviceModel && { model: fingerprint.deviceModel }),
-      ...(fingerprint.osVersion && { os: fingerprint.osVersion }),
-      ...(fingerprint.appVersion && { app_version: fingerprint.appVersion }),
-    });
+    };
+    if (fingerprint.deviceModel) params.model = fingerprint.deviceModel;
+    if (fingerprint.osVersion) params.os = fingerprint.osVersion;
+    if (fingerprint.appVersion) params.app_version = fingerprint.appVersion;
 
-    return params.toString();
+    return Object.entries(params)
+      .map(([key, value]) => `${encodeURIComponent(key)}=${encodeURIComponent(value)}`)
+      .join('&');
   }
 
   /**

package/src/LinkFortySDK.ts

@@ -310,7 +310,7 @@ export class LinkFortySDK {
       // Parse screen resolution (e.g., "1080x1920" -> [1080, 1920])
       const [screenWidth, screenHeight] = fingerprint.screenResolution
         .split('x')
-        .map(Number);
+        .map((v) => Math.round(Number(v)));
 
       // Convert attribution window from days to hours
       const attributionWindowHours = (this.config.attributionWindow || 7) * 24;